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 ROT's is defined at rot.endpoint, defaulting to /discover/complete. 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 ROT's, depending on the strength, revocation, repudiation, and other security concerns required of the tokens. The weakest protocol is the 'simple' protocol while 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.

Setting up a Wallet as an OAuth Client using Database Configuration​

The Wallet is an application that 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 RSA-LDAP extension.

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, 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.

Note #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. Additionally, as the Wallet does require an openid identifier for a resource owner's connection to the RSA-LDAP, a scope of "openid" must also be required. Additional scopes such as 'profile' and 'email' may also be requested depending on your business requirements.

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 profile email", 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-LDAP Adapter within the "oauth_provider" table (Again, this table is for the Wallet database, NOT the RSA-LDAP 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".