Configure OAuth Relationship with a Wallet

Overview and Application Config

The Wallet acts as the Requesting Party's agent during transactions within an FPX network. Wallets have the most visibility into a user's data, and are responsible for holding and securing the tokens and identities that the user uses throughout the network.

Wallets will use OAuth 2.0 to request access tokens from the RSA. If they request a token with the rot.scope:fpx_rot scope (defined in config, defaulting to 'fpx_rot'), they will be able to request Resource Owner Token materials (ROTs) on a Requesting Party's (RQP's) behalf. These ROTs will enable them to share permissions to Authorization Servers for the RQP's resources, managed by the RSA. Customized scopes, or even a different authentication/authorizing protocol may be used to protect the issuance of Resource Owner Tokens so long as they are understood by both the Wallet and Resource Server.

The Wallet will negotiate with the RSA to authenticate the Requesting Party and control their permissions to Clients. The RSA will return the above-mentioned ROT back to the Wallet upon successful Requesting Party authentication at the Federated OIDC Provider.

The following snippets outline the configuration details required for ROT creation at the RSA. Different ROT strategies have different configurations. The endpoint for requesting and issuing ROTs is defined at rot.endpoint, defaulting to /discover/complete. The Wallet will make requests for a ROT using a bearer OAuth Access Token issued by the RSA upon successful RQP authentication.

There are multiple profiles for the protocol surrounding ROTs, depending on the strength, revocation, repudiation, and other security concerns required of the tokens. The weakest protocol is the 'simple' protocol. Currently, the strongest protocol supported is the 'HMAC-JWT' which involves sharing a derived proof with the Wallet. The Wallet would use this proof to further sign JWTs that must (at the final step of the FPX flow) be verified at the RSA. The following profiles are currently available (NOTE: The field rot.implementation-strategy must have only one of these options as its value or the field should be completely omitted as the simple strategy is deemed to be the default):

HMAC-JWT

rot:
  scope:fpx_rot
  endpoint: /discover/complete
  implementation-strategy: HMAC-JWT 
  hmac-jwt:
    expiryDurationInSeconds: 1800
    numberOfPseudonyms: 10 ## number of UUIDs issued to the wallet when it requests for ROTs at the ROT issuance endpoint

Simple (DEFAULT)

rot:
  scope:fpx_rot
  endpoint: /discover/complete
  implementation-strategy: simple
  simple: 
    rotLength: 64
    expiryDurationInSeconds: 1800

The ROT's default timeout is 1800 seconds. You can set a custom timeout through the rot.{strategy}.expiryDurationInSeconds field for either strategy.

IMPORTANT NOTE

The ROT timeout must be set to a value less than the session length set at the Federated Provider. If it's set to a value higher than the session length at the federated provider, the user will mistakenly believe they're still logged in at the federated provider as the Wallet UI will show that their connection at the RSA is still valid and hasn't expired.

Request Attributes

The request attributes shown here are for the request to Register Wallet at the RSA. To see the attributes for the requests to the Wallet Admin API instead, please refer to the User Guide's section on configuring a data source for the Wallet, here.

The attributes in this request are described below according to the entity they belong to.

OAuth Client

JSON-API type: oauth-client

Parameter	Description	Required
clientId	This value is the identifier of the OAuth Client.	Yes
clientName	A human-readable name for the OAuth Client.	No
redirectUris	The set of URIs that the OAuth Client will be allowed to use to redirect back to the RSA-OIDC.	No

OAuth Client Metadata

JSON-API type: oauth-client-metadata

Parameter	Description	Example value	Required
clientSecret	The secret the OAuth Client is expected to provide to RSA-OIDC.	wallet-to-rsa-client-secret	Yes
issuerUri	This must correspond to the base URI of the OAuth Client.	{{WALLET_SERVER_URI}}	Yes
jwksUri	The endpoint where a JSON Web Key Set may be requested from the OAuth Client.	{{WALLET_SERVER_URI}}/jwks	No
clientAuthenticationMethod	The authentication method the OAuth Client uses with RSA-OIDC. If left null, defaults to `CLIENT_SECRET_BASIC`.	client_secret_basic	No
clientType	In the case of a relationship with the Wallet, this value must be `CONFIDENTIAL`.	CONFIDENTIAL	Yes
grantTypes	Defines which grant types the OAuth Client will be allowed to receive.	null	No
scopes	Defines which scopes the OAuth Client will be allowed to request.	null	No
metaDataRaw	Metadata can be provided in raw text format using this field.	null	No

Relationship	Description	Required
oAuthClientMetaData	Of type `oauth-client-metadata`. The OAuth Client Metadata that should be used for this OAuth Client	Yes

Sample Requests using Admin API

Register Wallet at the RSA

The Wallet must be registered as an OAuth Client to the RSA. The following Admin API request demonstrates how to configure a Wallet as such:

curl -X PATCH '{{RSA_ADMIN_URI}}' \
  --header 'Accept: */*' \
  --header 'Content-Type: application/vnd.api+json; ext=jsonpatch' \
  --header 'ApiVersion: {{RSA_ADMIN_VERSION}}' \
  --header 'Authorization: {{RSA_ADMIN_STATIC_TOKEN}}' \
  --data-raw '[
  {
    "op": "add",
    "path": "/oauth-client-metadata",
    "value": {
      "type": "oauth-client-metadata",
      "id": 1,
      "attributes": {
        "clientSecret": "wallet-to-rsa-client-secret",
        "issuerUri": "{{WALLET_SERVER_URI}}",
        "jwksUri": {WALLET_SERVER_URI}}/jwks,
        "clientAuthenticationMethod": "client_secret_basic",
        "clientType": "CONFIDENTIAL",
        "scopes": null,
        "grantTypes": null,
        "metaDataRaw": null
      }
    }
  },
  {
    "op": "add",
    "path": "/oauth-client",
    "value": {
      "type": "oauth-client",
      "id": 1,
      "attributes": {
        "clientName": "IDENTOS Wallet",
        "clientId": "wallet-to-rsa-client-id",
        "redirectUris": [
          "{{WALLET_SERVER_URI}}/data-sources/3/callback",
          "{{WALLET_SERVER_URI}}/login/idps/rsa-oidc-idp/callback"
        ]
      },
      "relationships": {
        "oAuthClientMetaData": {
          "data": {
            "type": "oauth-client-metadata",
            "id": 1
          }
        }
      }
    }
  }
]'

Register RSA at the Wallet

At this point, the credentials used to register the Wallet at the RSA should be used to register the RSA as an OAuth Provider at the Wallet using the Wallet Admin API.

These requests use the same format as shown in the chapter on configuring the Wallet Server. Further details about these requests and their attributes may be found there: Configuring a Data Source at the Wallet

First, create OAuth Provider and Data Source entries at the Wallet:

curl -X PATCH '{{WALLET_ADMIN_URI}}' \
  --header 'Accept: */*' \
  --header 'Content-Type: application/vnd.api+json; ext=jsonpatch' \
  --header 'ApiVersion: {{WS_ADMIN_VERSION}}' \
  --header 'Authorization: {{WS_ADMIN_STATIC_TOKEN}}' \
  --header 'Accept-Language: en' \
  --data-raw '[
  {
    "op": "add",
    "path": "/oauth-provider",
    "value": {
      "type": "oauth-provider",
      "id": 4,
      "attributes": {
        "name": "RSA-OIDC",
        "clientId": "wallet-to-rsa-client-id",
        "clientSecret": "wallet-to-rsa-client-secret",
        "issuerUri": "{{RSA_URI}}",
        "clientAuthenticationMethod": null,
        "additionalRequestParams": {}
      }
    }
  },
  {
    "op": "add",
    "path": "/oauth-provider/4/dataSource",
    "value": {
      "type": "data-source",
      "id": 3,
      "attributes": {
        "logoUrl": "https://icons.iconarchive.com/icons/icons8/ios7/256/Science-Gamma-icon.png",
        "styleColor": "#FFFFFF",
        "styleFontColor": "#000000"
      },
      "relationships": {
        "organization": {
          "data": {
            "type": "organization",
            "id": 1
          }
        }
      }
    }
  }
]'

Then, enroll the Data Source as a Resource Server at the Wallet and add Custom Scopes:

curl -X PATCH '{{WALLET_ADMIN_URI}}' \
  --header 'Accept: */*' \
  --header 'Content-Type: application/vnd.api+json; ext=jsonpatch' \
  --header 'ApiVersion: {{WS_ADMIN_VERSION}}' \
  --header 'Authorization: {{WS_ADMIN_STATIC_TOKEN}}' \
  --data-raw '[
  {
    "op": "add",
    "path": "/enrolled-rs",
    "value": {
      "type": "enrolled-rs",
      "id": 3,
      "attributes": {
        "enrolledIdentifier": "rsa-oidc-rs",
        "disabled": null
      },
      "relationships": {
        "authorizationServer": {
          "data": {
            "type": "authorization-server",
            "id": 1
          }
        },
        "dataSource": {
          "data": {
            "type": "data-source",
            "id": 3
          }
        }
      }
    }
  },
  {
    "op": "add",
    "path": "/oauth-provider/4/customScopes",
    "value": {
      "type": "oauth-provider-custom-scopes",
      "id": 4,
      "attributes": {
        "scopes": "fpx_rot openid"
      }
    }
  }
]'

Next, enroll the Data Source as an Identity Provider at the Wallet:

curl -X POST '{{WALLET_ADMIN_URI}}/idp-authenticator' \
  --header 'Accept: */*' \
  --header 'Content-Type: application/vnd.api+json; ext=jsonpatch' \
  --header 'ApiVersion: {{WS_ADMIN_VERSION}}' \
  --header 'Authorization: {{WS_ADMIN_STATIC_TOKEN}}' \
  --data-raw '{
  "data": {
    "type": "idp-authenticator",
    "id": 3,
    "attributes": {
      "name": "RSA-OIDC",
      "identifier": "rsa-oidc-idp",
      "logoUrl": "https://icons.iconarchive.com/icons/icons8/ios7/256/Science-Gamma-icon.png",
      "styleColor": "#FFFFFF",
      "styleFontColor": "#000000"
    },
    "relationships": {
      "dataSource": {
        "data": {
          "type": "data-source",
          "id": 3
        }
      }
    }
  }
}'

Finally, register the Resource at the Wallet Server:

curl --location --request POST 'admin.wallet.as-3464.dev.identos.ca/json-api/enrolled-rs/3/rsResources' \
--header 'Accept: */*' \
--header 'Content-Type: application/vnd.api+json' \
--header 'ApiVersion: v1.0' \
--header 'Authorization: c94856c7-50ac-4fd3-b395-89af4c7d7bbc' \
--data-raw '{
  "data": {
    "type": "rs-resource",
    "id": 2,
    "attributes": {
      "identifier": "rsa-userinfo"
    },
    "relationships": {
      "resourceScopes": {
        "data": [
          {
            "type": "resource-scope",
            "id": 1
          }
        ]
      },
      "resourceDefinition": {
        "data": {
          "type": "resource-definition",
          "id": 1
        }
      }
    }
  }
}'

NOTE

The value that has been configured for rot.scope in the application config ('fpx_rot', by default), must be included in the scopes attribute of the operation that adds custom scopes for the OAuth Provider (this operation immediately precedes this notice in the sample request above. A value can hold all required scopes, as long as they are each separated by a single space.

This will define the scopes the Wallet will include in its OIDC authorize call to the RSA, such as 'openid' ('profile' and 'email' are other examples that may be requested as per your resource needs for your service providers).

Overview and Application Config​

HMAC-JWT​

Simple (DEFAULT)​

Request Attributes​

OAuth Client​

OAuth Client Metadata​

Sample Requests using Admin API​

Register Wallet at the RSA​

Register RSA at the Wallet​