Configuring a Wallet

Scope and Audience

This section is meant for an administrator of an FPX network, and covers how to register a new Wallet or update an existing one in an FPX environment directly through the Admin API.

Required Reference

The reader of this document should be familiar with the architecture and terminology associated with the FPX specification. This specification extends the UMA 2.0 specification by enabling privacy preservation and governable network actors.

If you are unfamiliar with Resource Definitions or Scopes, refer to the Glossary and the Partners section of the guide for more information before trying to add a resource definition.

Overview

Before a Wallet can begin to interact with a Federated Privacy Exchange (FPX) Network, an FPX Admin User must register their service at the AS (Authorization Server). This process can be scripted and automated by directly integrating with the associated AS Admin API.

Onboarding is a simple one-step process. The Wallet must be registered and set up as both an OAuth 2.0 Client and an OAuth 2.0 Provider of the Authorization Server. The Wallet will act in an OAuth Provider role when the Authorization Server federates out to a Wallet to do claims-gathering with the user. The Wallet will act as an OAuth Client role when it requests ticket information from the Authorization Server.

Wallets will represent the user, and have visibility on user data and transactions. It is integral from a security standpoint that Wallet partners are from vetted, regularly audited sources. Many FPX networks may wish to deploy and operate their own Wallet without allowing third-party Wallets.

Configuring a Wallet

Wallet configuration at the Authorization Server can be done directly through the API.

Before you start

Make sure you obtain the following valid parameters from the Helm chart:

AS_URI
AS_ADMIN_URI
AS_ADMIN_STATIC_TOKEN
WALLET_SERVER

Further instruction can be found at here

Overview

A fully functional Wallet in the FPX network requires data from the following data types (Ordered by the creation time from old to latest):

oauth-client-metadata
oauth-client
oauth-provider
wallet

Type: "oauth-client-metadata"

Defines additional data for OAuth Client. For example, authentication type, scope, secret, etc.

Note

The clientAuthenticationType, grantTypes, scopes and secret attributes MUST contain valid data. Failure to provide these details will result in an error being returned by the Authorization Server.

Note

"" means empty string

Attributes	Description	Example value	Required	Localizable
issuerUri	Provide the host URL of OAuth Client.	`{{WALLET_SERVER_URI}}`	Yes	No
clientType	Client type.	CONFIDENTIAL	Yes	No
jwksUri	URL of a set of keys containing the public keys.	`{{WALLET_SERVER_URI}}/jwks`	Yes, if authentication type is private_key_jwt	No
clientAuthenticationType	The authentication method the Authorization Server uses with the OAuth Provider. Currently the following values are supported for the wallet: - private_key_jwt	private_key_jwt	Yes	No
grantTypes	Grant type, currently the following values are supported: authorization_code, urn:ietf:params:oauth:grant-type:uma-ticket, urn:ietf:params:oauth:grant-type:capability-ticket, client_credentials, refresh_token	"refresh_token client_credentials authorization_code"	Yes	No
scopes	Client permission scope, for example, "register user uma_protection". The three pre-defined scopes assist users in accessing distinct endpoints. The 'register' (required) scope enables users to access the dynamic client register endpoint, the user scope allows access to the CRUD permission endpoint, and the 'uma_protection' scope allows users to access a particular resource endpoint. For a Wallet, the 'register' scope is required.	register	No	No
clientSecret	Any string length `<=` 255. Secret isn't required when using the private_key_jwt authentication type	wallet-identos-clientsecret	No	No

Type: "oauth-client"

Defines Client ID of Wallet

Attribute	Description	Example value	Required	Localizable
clientId	Client identifier as a string.	wallet-identos-clientid	Yes	No
clientName	A human readable name for the client.	Identos Wallet	No	No

Relationship	Description	Required
oAuthClientMetaData	Metadata for the OAuth Client. The ID needs to match that of the associated OAuth Client Metadata, see the sample request	Yes

Type: "oauth-provider"

Defines baseUrl & JwkUrl of the Wallet Server

Note

The clientSecret and clientId attributes MUST contain valid data. Failure to provide these details will result in an error being returned by the Authorization Server.

Attribute	Description	Example Value	Required	Localizable
name	A human readable name for the Wallet	"Identos Wallet"	No	No
issuerUri	Provide host URL of the Wallet	"https://wallet.dev.ca"	Yes	No
jwksUri	URL of a set of keys containing the public keys.	"https://wallet.dev.ca/jwks"	Yes	No
clientSecret	A secret the Authorization Server uses with the OAuth Provider (the Wallet in this case)	authserver-client-secret	No	No
clientId	This value is used to identify the Authorization Server with the OAuth Provider (the Wallet in this case)	authserver-client-id	No	No
jwksRaw	Raw data of JWK.	null	No	No
clientAuthenticationMethod	The authentication method the Authorization Server uses with the OAuth Provider (the Wallet in this case). If left null, defaults to CLIENT_SECRET_BASIC	private_key_jwt	No	No
metaDataRaw	OAuth provider metadata registered directly into the database as text. This allows the metadata to be resolved without an HTTP call to the provider. A very simple example is shown	`{ "authorization_endpoint": "https://provider/oauth2/login", "token_endpoint": "https://provider/oauth2/token", "jwks_uri": "https://provider/oauth2/jwks" }`	No	No
clientType	OAuth 2 Client type	CONFIDENTIAL	Yes	No
defaultScopes	Default scopes to include in requests to the OAuth Provider	null	No	No
defaultPrompt	Default prompt to include in requests to the OAuth Provider	null	No	No
additionalRequestParams	Additional parameters to include in requests to the OAuth Provider		No	No

Type: "wallet"

Define basic Wallet information such as name & id.

Note

The oAuthClient and oAuthProvider attributes MUST contain valid data. Failure to provide these details will result in an error being returned by the Authorization Server.

Attribute	Description	Example Value	Required	Localizable
name	Name of the Wallet.	"FPX Wallet Server"	Yes	Yes
walletId	Unique identifier of Wallet.	"wallet-identos-clientid"	Yes	No
optionImg	A URI of an image resource that is displayed for this Wallet on the Wallet Select page (when more than one Wallet is available)	""	No	Yes
optionColour	The colour used for this Wallet on the Wallet Select page (when more than one Wallet is available)	"#000000"	No	No
disabledOn	Date and time at which the entity was, or will be, disabled. The value must be in "yyyy-MM-dd'T'HH:mm:ss'Z'" format. In order to re-enable, the value must be reset to the default value `null`.	"2021-01-01T11:00:00Z"	No	No

Relationship	Description	Required
oAuthClient	OAuth Client previously created	Yes
oAuthProvider	OAuth Provider previously created	Yes

Sample Requests

Create Wallet - All-in-one

curl --location -g --request PATCH '{{AS_ADMIN_URI}}' \
--header 'Content-Type: application/vnd.api+json; ext=jsonpatch' \
--header 'Authorization: {{AS_ADMIN_STATIC_TOKEN}}' \
--header 'ApiVersion: v1.0' \
--header 'Accept-Language: en' \
--data-raw '[
    {
        "op": "add",
        "path": "/oauth-client-metadata",
        "value": {
            "id": 1,
            "type": "oauth-client-metadata",
            "attributes": {
                "issuerUri": "{{WALLET_SERVER_URI}}",
                "clientAuthenticationType": "client_secret_basic",
                "clientType": "CONFIDENTIAL",
                "grantTypes": "refresh_token client_credentials authorization_code",
                "jwksRaw": null,
                "jwksUri": null,
                "scopes": "register",
                "clientSecret": "wallet-identos-clientsecret"
            }
        }
    },
    {
        "op": "add",
        "path": "/oauth-client",
        "value": {
            "type": "oauth-client",
            "id": 1,
            "attributes": {
                "clientId": "wallet-identos-clientid",
                "clientName": "Identos Wallet"
            },
            "relationships": {
                "oAuthClientMetaData": {
                    "data": {
                        "type": "oauth-client-metadata",
                        "id": 1
                    }
                }
            }
        }
    },
    {
        "op": "add",
        "path": "/oauth-provider",
        "value": {
            "type": "oauth-provider",
            "id": 1,
            "attributes": {
                "name": "Identos Wallet",
                "issuerUri": "{{WALLET_SERVER_URI}}",
                "clientId": "authserver-client-id",
                "clientType": "CONFIDENTIAL",
                "clientSecret": "authserver-client-secret",
                "jwksRaw": null,
                "jwksUri": "{{WALLET_SERVER_URI}}/jwks"
            }
        }
    },
    {
        "op": "add",
        "path": "/wallet",
        "value": {
            "type": "wallet",
            "id": 1,
            "attributes": {
                "name": "Wallet server name",
                "optionImg": "https://some-image-url",
                "walletId": "wallet-identos-clientid"
            },
            "relationships": {
                "oAuthClient": {
                    "data": {
                        "id": 1,
                        "type": "oauth-client"
                    }
                },
                "oAuthProvider": {
                    "data": {
                        "id": 1,
                        "type": "oauth-provider"
                    }
                }
            }
        }
    }
]'

curl --location -g --request GET '{{AS_ADMIN_URI}}/oauth-client-metadata/1' \
--header 'Content-Type: application/vnd.api+json' \
--header 'ApiVersion: v1.0' \
--header 'Authorization: {{AS_ADMIN_STATIC_TOKEN}}' \
--header 'Accept-Language: en'

curl --location -g --request GET '{{AS_ADMIN_URI}}/oauth-client/1' \
--header 'Content-Type: application/vnd.api+json' \
--header 'ApiVersion: v1.0' \
--header 'Authorization: {{AS_ADMIN_STATIC_TOKEN}}' \
--header 'Accept-Language: en'

curl --location --request GET '{{AS_ADMIN_URI}}/oauth-provider/1' \
--header 'Content-Type: application/vnd.api+json' \
--header 'ApiVersion: v1.0' \
--header 'Authorization: {{AS_ADMIN_STATIC_TOKEN}}' \
--header 'Accept-Language: en'

Get Wallet

curl --location --request GET '{{AS_ADMIN_URI}}/wallet/1' \
--header 'Content-Type: application/vnd.api+json' \
--header 'ApiVersion: v1.0' \
--header 'Authorization: {{AS_ADMIN_STATIC_TOKEN}}' \
--header 'Accept-Language: en'

Updating Wallet - All in one

curl --location -g --request PATCH '{{AS_ADMIN_URI}}' \
--header 'Content-Type: application/vnd.api+json; ext=jsonpatch' \
--header 'Authorization: {{AS_ADMIN_STATIC_TOKEN}}' \
--header 'ApiVersion: v1.0' \
--header 'Accept-Language: en' \
--data-raw '[
    {
        "op": "replace",
        "path": "/oauth-client-metadata/1",
        "value": {
            "id": 1,
            "type": "oauth-client-metadata",
            "attributes": {
                "issuerUri": "{{WALLET_SERVER_URI}}",
                "clientAuthenticationType": "client_secret_jwt",
                "clientType": "CONFIDENTIAL",
                "grantTypes": "refresh_token client_credentials authorization_code",
                "jwksRaw": null,
                "jwksUri": null,
                "scopes": "register",
                "clientSecret": "wallet-identos-clientsecret"
            }
        }
    },
    {
        "op": "replace",
        "path": "/oauth-client/1",
        "value": {
            "type": "oauth-client",
            "id": 1,
            "attributes": {
                "clientId": "wallet-identos-clientid",
                "clientName": "Identos Wallet"
            },
            "relationships": {
                "oAuthClientMetaData": {
                    "data": {
                        "type": "oauth-client-metadata",
                        "id": 1
                    }
                }
            }
        }
    },
    {
        "op": "replace",
        "path": "/oauth-provider/1",
        "value": {
            "type": "oauth-provider",
            "id": 1,
            "attributes": {
                "name": "Identos Wallet",
                "issuerUri": "{{WALLET_SERVER_URI}}",
                "clientId": "authserver-client-id",
                "clientType": "CONFIDENTIAL",
                "clientSecret": "authserver-client-secret",
                "jwksRaw": null,
                "jwksUri": "{{WALLET_SERVER_URI}}/jwks"
            }
        }
    },
    {
        "op": "replace",
        "path": "/wallet/1",
        "value": {
            "type": "wallet",
            "id": 1,
            "attributes": {
                "name": "Wallet server name - Multilanguage fr",
                "optionImg": "Image option - Multilanguage fr",
                "walletId": "wallet-identos-clientid"
            },
            "relationships": {
                "oAuthClient": {
                    "data": {
                        "id": 1,
                        "type": "oauth-client"
                    }
                },
                "oAuthProvider": {
                    "data": {
                        "id": 1,
                        "type": "oauth-provider"
                    }
                }
            }
        }
    }
]'

Disable Wallet

curl --location -g --request PATCH '{{AS_ADMIN_URI}}/wallet/1' \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: {{AS_ADMIN_STATIC_TOKEN}}' \
--header 'ApiVersion: v1.0' \
--data-raw '{
     "data": {
            "type": "wallet",
            "id": 1,
            "attributes": {
                "disabledOn": "2021-01-01T11:00:00Z"
        }
    }
}'

note

The localization feature is covered in more detail here.

Scope and Audience​

Required Reference​

Overview​

Configuring a Wallet​

Overview​

Type: "oauth-client-metadata"​

Type: "oauth-client"​

Type: "oauth-provider"​

Type: "wallet"​

Sample Requests​

Create Wallet - All-in-one​

Get Wallet related information - OAuthClient_Metadata​

Get Wallet related information - OAuthClient​

Get Wallet related information - OAuthProvider​

Get Wallet​

Updating Wallet - All in one​

Disable Wallet​

Scope and Audience

Required Reference

Overview

Configuring a Wallet

Overview

Type: "oauth-client-metadata"

Type: "oauth-client"

Type: "oauth-provider"

Type: "wallet"

Sample Requests

Create Wallet - All-in-one

Get Wallet related information - OAuthClient_Metadata

Get Wallet related information - OAuthClient

Get Wallet related information - OAuthProvider

Get Wallet

Updating Wallet - All in one

Disable Wallet