Skip to main content

Configuring a Wallet via 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):

  1. oauth-client-metadata
  2. oauth-client
  3. oauth-provider
  4. 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

AttributesDescriptionExample valueRequiredLocalizable
issuerUriProvide the host URL of OAuth Client.{{WALLET_SERVER_URI}}YesNo
clientTypeClient type.CONFIDENTIALYesNo
jwksUriURL of a set of keys containing the public keys.{{WALLET_SERVER_URI}}/jwksYes, if authentication type is private_key_jwtNo
clientAuthenticationTypeThe authentication method the Authorization Server uses with the OAuth Provider. Currently the following values are supported for the wallet:
- private_key_jwt		private_key_jwtYesNo
grantTypesGrant 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"YesNo
scopesClient 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.registerNoNo
clientSecretAny string length <= 255. Secret isn't required when using the private_key_jwt authentication typewallet-identos-clientsecretNoNo

Type: "oauth-client"​

Defines Client ID of Wallet

AttributeDescriptionExample valueRequiredLocalizable
clientIdClient identifier as a string.wallet-identos-clientidYesNo
clientNameA human readable name for the client.Identos WalletNoNo
RelationshipDescriptionRequired
oAuthClientMetaDataMetadata for the OAuth Client. The ID needs to match that of the associated OAuth Client Metadata, see the sample requestYes

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.

AttributeDescriptionExample ValueRequiredLocalizable
nameA human readable name for the Wallet"Identos Wallet"NoNo
issuerUriProvide host URL of the Wallet"https://wallet.dev.ca"YesNo
jwksUriURL of a set of keys containing the public keys."https://wallet.dev.ca/jwks"YesNo
clientSecretA secret the Authorization Server uses with the OAuth Provider (the Wallet in this case)authserver-client-secretNoNo
clientIdThis value is used to identify the Authorization Server with the OAuth Provider (the Wallet in this case)authserver-client-idNoNo
jwksRawRaw data of JWK.nullNoNo
clientAuthenticationMethodThe authentication method the Authorization Server uses with the OAuth Provider (the Wallet in this case). If left null, defaults to CLIENT_SECRET_BASICprivate_key_jwtNoNo
metaDataRawOAuth 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" }NoNo
clientTypeOAuth 2 Client typeCONFIDENTIALYesNo
defaultScopesDefault scopes to include in requests to the OAuth ProvidernullNoNo
defaultPromptDefault prompt to include in requests to the OAuth ProvidernullNoNo
additionalRequestParamsAdditional parameters to include in requests to the OAuth Provider{}NoNo

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.

AttributeDescriptionExample ValueRequiredLocalizable
nameName of the Wallet."FPX Wallet Server"YesYes
walletIdUnique identifier of Wallet."wallet-identos-clientid"YesNo
optionImgA URI of an image resource that is displayed for this Wallet on the Wallet Select page (when more than one Wallet is available)""NoYes
optionColourThe colour used for this Wallet on the Wallet Select page (when more than one Wallet is available)"#000000"NoNo
disabledOnDate 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"NoNo
RelationshipDescriptionRequired
oAuthClientOAuth Client previously createdYes
oAuthProviderOAuth Provider previously createdYes

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"
                    }
                }
            }
        }
    }
]'

Get Wallet related information - OAuthClient_Metadata​

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'

Get Wallet related information - OAuthClient​

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'

Get Wallet related information - OAuthProvider​

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.