Skip to main content

Configure OAuth Relationship with a Wallet

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 following snippets outline 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 an 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.

Setting up the Wallet as an OAuth Client

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.

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 Wallet must be registered as an OAuth Client to the RSA. The following Database Insert statements outline a sample Wallet being configured as such:

INSERT INTO registered_client (id, version, date_created, last_updated, application_type, client_id, client_name, client_secret) 
VALUES (1,1,now(), now(), 0, "example-wallet-id", "example-Wallet", "example-wallet-secret");

At this point, the credentials used to register the Wallet at the RSA should be used to register the RSA within the Wallet using the Wallet Admin API. After it has been registered you will need to add a registered client redirect URI (this redirect URI will depend on its configuration within the Wallet).

INSERT INTO registered_client_redirect_uris (RegisteredClient_id, redirect_uris) 
VALUES (1, "https://example-wallet-base-url/callback-path");
NOTE
  1. The RegisteredClient_id must correspond to the 'id' of the appropriate Wallet entry in the registered_client table of the RSA.
  2. The value that has been configured for rot.scope ('fpx_rot' is default), must be appropriately inserted into the "oauth_provider_custom_scopes" table at the Wallet along with all appropriate scopes the Wallet expects to apply to 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).

For example the following INSERT query may be used At the Wallet:

INSERT INTO oauth_provider_custom_scopes (id,version, date_created, last_updated, scopes, provider_id) values (1,1,now(), now(), "fpx_rot openid email profile", 2);

As this is a query at the Wallet database, the value inserted for the 'provider_id' must correspond to whatever entry represents the RSA-OIDC Adapter within the 'oauth_provider' table (Note that this table is for the Wallet database, NOT the RSA-OIDC database). For scopes, you can insert as many scopes separated with a space within one entry. For this query, the implication is that the rot.scope value at the RSA is set to 'fpx_rot'.