Remote consent

AM supports OAuth 2.0 remote consent services, which allow the consent-gathering part of an OAuth 2.0 flow to be handed off to a separate service.

A remote consent service renders a consent page, gathers the result, signs and encrypts the result, and returns it to the authorization server.

During an OAuth 2.0 flow that requires user consent, AM can create a consent request JWT that contains the necessary information to render a consent gathering page. It does not send the actual values of the requested scopes.

Consent request JWT example and properties

{
  "clientId": "myClient",
  "iss": "https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha",
  "csrf": "gjeH2C43nFJwW+Ir1zL3hl8kux9oatSZRso7aCzI0vk=",
  "client_description": "",
  "aud": "rcs",
  "save_consent_enabled": true,
  "claims": {},
  "scopes": {
      "write": null
  },
  "exp": 1536229486,
  "iat": 1536229306,
  "client_name": "My Client",
  "consentApprovalRedirectUri": "https://openam.example.com:8443/openam/oauth2/authorize?client_id=MyClient&response_type=code&redirect_uri=https://application.example.com:8443/callback&scope=write&state=1234zy",
  "username": "demo"
}

iat

Specifies the creation time of the JWT.

iss

Specifies the name of the issuer - configured in the OAuth 2.0 provider service in AM.

aud

Specifies the name of the expected recipient of the JWT, in this case, the remote consent service.

exp

Specifies the expiration time of the JWT.

Use short expiration times, for example, 180 seconds, as the JWT is intended for use in machine-to-machine interactions.

csrf

Specifies a unique string that must be returned in the response to help prevent cross-site request forgery (CSRF) attacks.

AM generates this string from a hash of the user’s session ID.

client_id

Specifies the ID of the OAuth 2.0 client making the request.

client_name

Specifies the display name of the OAuth 2.0 client making the request.

client_description

Specifies a description of the OAuth 2.0 client making the request.

username

Specifies the username of the logged-in user.

Ensure you encrypt the JWT if the username could be considered personally identifiable information.

scopes

Specifies the requested scopes.

claims

Specifies the claims the request is making.

Use the claims field for additional information to display on the remote consent page that helps the user to determine if consent should be granted. For example, Open Banking OAuth 2.0 flows may include identifiers for a money transaction.

save_consent_enabled

Specifies whether to provide the user the option to save their consent decision.

If set to false, the value of the save_consent property in the consent response from the RCS must also be false.

consentApprovalRedirectUri

Specifies the URI to return the resource owner to after they have provided consent. The response JWT must be sent as a consent_response form parameter in a POST operation to this URI.

Acting as the authorization server, AM signs and encrypts the JWT.

The remote consent service decrypts the JWT, verifies the signature and other details, such as the validity of the aud, iss and exp properties, and renders the consent page to the resource owner.

After the remote consent service gathers the user’s consent, it creates a consent response JWT, encrypts and signs the response, and returns it to AM for processing.

Consent response JWT example and properties

{
  "consent_response" : {
    "clientId": "myClient",
    "iss": "rcs",
    "csrf": "gjeH2C43nFJwW+Ir1zL3hl8kux9oatSZRso7aCzI0vk=",
    "client_description": "",
    "aud": "https://openam.example.com:8443/openam/oauth2",
    "save_consent": true,
    "claims": {},
    "scopes": "[write]",
    "exp": 1536229430,
    "iat": 1536229250,
    "client_name": "My Client",
    "consentApprovalRedirectUri": "https://openam.example.com:8443/openam/oauth2/authorize?client_id=MyClient&response_type=code&redirect_uri=https://application.example.com:8443/callback&scope=write&state=1234zy",
    "username": "demo",
    "decision": true
  },

}

iat: Specifies the creation time of the JWT.
iss: Specifies the name of the remote consent service.

Must match the value of the aud property received from AM.
aud: Specifies the name of the expected recipient of the JWT, in this case, AM acting as the AS.

Must match the value of the iss property received from AM.
exp: Specifies the expiration time of the JWT.

Use short expiration times, for example, 180 seconds, as the JWT is intended for use in machine-to-machine interactions.
decision: Specifies true if consent was provided, or `false ` if consent was withheld.
client_id: Specifies the ID of the OAuth 2.0 client making the request, matching the value provided in the request.
client_name: Specifies the display name of the OAuth 2.0 client making the request.
client_description: Specifies a description of the OAuth 2.0 client making the request.
scopes: Specifies an array of allowed scopes.

Must be equal to, or a subset of the array of scopes in the request.
save_consent: Specifies true if the user chose to save their consent decision, or false if they did not.

If save_consent_enabled was set to false in the request, save_consent must also be false.
consentApprovalRedirectUri: Specifies the URI to return the resource owner to after they have provided consent.

AM decrypts and verifies the signature of the consent response and other details, such as the validity of the aud, iss and exp properties, and processes the response. For example, it may save the consent decision if configured to do so.

If the remote consent service compresses the consent response JWT, AM rejects JWTs that expand to a size larger than 32 KiB (32768 bytes). For more information, refer to Control the size of compressed JWTs.

AM and the remote consent service make their required public keys available from two `jwk_uri`s, to enable signing and encryption between the two servers.

Configuring a remote consent service requires completion of these high-level tasks:

Task Resources

Task	Resources
Add the details of the remote consent service as an agent profile in AM You can configure a single remote consent service in a realm, by adding the details to a remote consent agent profile. The profile defines properties for signing and encrypting the consent request and consent response, redirect URI, and the `jwk_uri` URI details of the remote consent service.	Configure AM to use a remote consent service
Enable remote consent and specify the agent profile in AM’s OAuth 2.0 provider service.	Configure the OAuth 2.0 provider to use a remote consent agent profile
Configure the remote consent service with AM’s `jwk_uri` URI details. The remote consent service must be able to obtain the required signature and decryption keys from AM.	N/A

Add the details of the remote consent service as an agent profile in AM

You can configure a single remote consent service in a realm, by adding the details to a remote consent agent profile.

The profile defines properties for signing and encrypting the consent request and consent response, redirect URI, and the jwk_uri URI details of the remote consent service.

Configure AM to use a remote consent service

Enable remote consent and specify the agent profile in AM’s OAuth 2.0 provider service.

Configure the OAuth 2.0 provider to use a remote consent agent profile

Configure the remote consent service with AM’s jwk_uri URI details.

The remote consent service must be able to obtain the required signature and decryption keys from AM.

N/A

AM includes an example remote consent service. Do not use the example in production environments.

See Configure the AM example remote consent service.

Configure AM to use a remote consent service

To add the details of the remote consent service as an agent profile:

In the AM admin UI, go to Realms > Realm Name > Applications > OAuth 2.0 > Remote Consent, and click Add Remote Consent Agent.
Enter an agent ID, for example, myRCSAgent, and click Create.
If you will be using an HMAC algorithm for signing the JWTs, enter the shared symmetric key in the Remote Consent Service secret field.

This step is not required when using other algorithms.

Select the Remote Consent Agent, and configure the properties as required.

Remote consent agent properties

Group

Configure several remote consent agent profiles by assigning them to a group.

Default value: none

amster attribute: agentgroup

Remote Consent Service secret

If the remote consent agent needs to authenticate to AM, enter the password it will use.

amster attribute: userpassword

Redirect URL

Specify the URL to which the user should be redirected during the OAuth 2.0 flow to obtain their consent.

The AM example remote consent service provides an /oauth2/consent path to obtain consent from the user.

Example: https://rcs.example.com:8443/openam/oauth2/consent

amster attribute: remoteConsentRedirectUrl

Enable consent request Encryption

Specify whether to encrypt the consent request JWT sent to the remote consent service.

Default: true

amster attribute: remoteConsentRequestEncryptionEnabled

Consent request Encryption Algorithm

Specify the encryption algorithm used to encrypt the consent request JWT sent to the remote consent service.

AM supports the following encryption algorithms:

A128KW - AES Key Wrapping with 128-bit key derived from the client secret.
A192KW - AES Key Wrapping with 192-bit key derived from the client secret.
A256KW - AES Key Wrapping with 256-bit key derived from the client secret.
RSA-OAEP - RSA with Optimal Asymmetric Encryption Padding (OAEP) with SHA-1 and MGF-1.
RSA-OAEP-256 - RSA with OAEP with SHA-256 and MGF-1.
RSA1_5 - RSA with PKCS#1 v1.5 padding.
dir - Direct encryption with AES using the hashed client secret.

Default value: RSA-OAEP-256

amster attribute: remoteConsentRequestEncryptionAlgorithm

Consent request Encryption Method

Specify the encryption method used to encrypt the consent request JWT sent to the remote consent service

AM supports the following encryption methods:

A128GCM, A192GCM, and A256GCM - AES in Galois Counter Mode (GCM) authenticated encryption mode.
A128CBC-HS256, A192CBC-HS384, and A256CBC-HS512 - AES encryption in CBC mode, with HMAC-SHA-2 for integrity.

Default value: A128GCM

amster attribute: remoteConsentRequestEncryptionMethod

Consent response signing algorithm

Specify the algorithm used to verify a signed consent response JWT received from the remote consent service.

AM supports signing algorithms listed in JSON Web Algorithms (JWA): "alg" (Algorithm) Header Parameter Values for JWS:

ES256 - ECDSA with SHA-256 and NIST standard P-256 elliptic curve.
ES384 - ECDSA with SHA-384 and NIST standard P-384 elliptic curve.
ES512 - ECDSA with SHA-512 and NIST standard P-521 elliptic curve.
HS256 - HMAC with SHA-256.
HS384 - HMAC with SHA-384.
HS512 - HMAC with SHA-512.
RS256 - RSASSA-PKCS-v1_5 using SHA-256.

Default value: RS256

amster attribute: remoteConsentResponseSigningAlg

Consent response encryption algorithm

Specify the encryption algorithm used to decrypt the consent response JWT received from the remote consent service.

AM supports the following encryption algorithms:

A128KW - AES Key Wrapping with 128-bit key derived from the client secret.
A192KW - AES Key Wrapping with 192-bit key derived from the client secret.
A256KW - AES Key Wrapping with 256-bit key derived from the client secret.
RSA-OAEP-256 - RSA with OAEP with SHA-256 and MGF-1.
dir - Direct encryption with AES using the hashed client secret.

The decryption key used depends on the selected algorithm. This table shows the secret label mapping used to decrypt remote consent responses:

Secret label Default alias Algorithms⁽¹⁾

Secret label	Default alias	Algorithms⁽¹⁾
`am.services.oauth2.remote.consent.response.decryption`	`test`	RSA-OAEP-256

am.services.oauth2.remote.consent.response.decryption

test

RSA-OAEP-256

⁽¹⁾ If you select an algorithm other than RSA-OAEP-256 for decrypting consent responses, the value of the remote consent service secret property is used, instead of an entry from the secret stores.

By default, secret labels are mapped to demo keys contained in the default keystore provided with AM and mapped to the default-keystore secret store. Use these keys for demo and test purposes only. For production environments, replace the secrets as required and create mappings for them in a secret store configured in AM.

For details about managing secret stores and mapping secret labels to aliases, refer to Secrets, certificates, and keys.

Default value: RSA-OAEP-256

amster attribute: remoteConsentResponseEncryptionAlgorithm

Consent request Signing Algorithm

Specify the algorithm used to sign the consent request JWT sent to the remote consent service.

The signing key used depends on the selected algorithm.

This table shows the secret label mappings used to sign remote consent requests:

Secret label Default Alias Algorithms⁽¹⁾

Secret label	Default Alias	Algorithms⁽¹⁾
`am.applications.agents.remote.consent.request.signing.ES256`	`es256test`	ES256
`am.applications.agents.remote.consent.request.signing.ES384`	`es384test`	ES384
`am.applications.agents.remote.consent.request.signing.ES512`	`es512test`	ES512
`am.applications.agents.remote.consent.request.signing.RSA`	`rsajwtsigningkey`	RS256 RS384 RS512 PS256 PS384 PS512

am.applications.agents.remote.consent.request.signing.ES256

es256test

ES256

am.applications.agents.remote.consent.request.signing.ES384

es384test

ES384

am.applications.agents.remote.consent.request.signing.ES512

es512test

ES512

am.applications.agents.remote.consent.request.signing.RSA

rsajwtsigningkey

RS256
RS384
RS512
PS256
PS384
PS512

⁽¹⁾ If you select an HMAC algorithm for signing consent requests (HS256, HS384, or HS512), the value of the Remote Consent Service secret property is used, instead of an entry from the secret stores.

Because AM and the remote consent client share the HMAC secret, a malicious user compromising the client could potentially create tokens that AM would trust. Therefore, to protect against misuse, AM also signs the token using a non-shared signing key configured in the am.services.oauth2.jwt.authenticity.signing secret label.

By default, secret labels are mapped to demo keys in the default keystore provided with AM and mapped to the default-keystore keystore secret store. Use these keys for demo and test purposes only. For production environments, replace the secrets as required and create mappings for them in a secret store configured in AM.

For information about managing secret stores and mapping secret labels to aliases, refer to Secrets, certificates, and keys.

Default value: RS256

amster attribute: remoteConsentRequestSigningAlgorithm

Consent response encryption method

Specify the encryption method used to decrypt the consent response JWT received from the remote consent service.

AM supports the following encryption methods:

A128GCM, A192GCM, and A256GCM - AES in Galois Counter Mode (GCM) authenticated encryption mode.
A128CBC-HS256, A192CBC-HS384, and A256CBC-HS512 - AES encryption in CBC mode, with HMAC-SHA-2 for integrity.

Default value: A128GCM

amster attribute: remoteConsentResponseEncryptionMethod

Public key selector

Specify whether the remote consent service provides its public keys using a JWKs_URI, or manually in JWKs format.

If you select JWKs, enter the keys in the Json Web Key property. Otherwise complete the JWKs URI-related properties.

Default: JWKs_URI

amster attribute: remoteConsentRedirectUrl

Json Web Key URI

Specify the URI from which AM can obtain the remote consent service’s public keys.

The example remote consent service uses the URI /oauth2/consent/jwk_uri to provide its public keys.

Example: http://rcs.example.com:8080/openam/oauth2/consent/jwk_uri

amster attribute: jwksUri

JWKs URI content cache timeout in ms

Specify the amount of time, in milliseconds, that the content of the JWKs' URI is cached for before being refreshed. Caching the content avoids fetching it for every token encryption or validation.

Default: 3600000

amster attribute: com.forgerock.openam.oauth2provider.jwksCacheTimeout

JWKs URI content cache miss cache time

Specify the amount of time, in milliseconds, that AM waits before fetching the URI’s content again when a key ID (kid) is not in the JWKs that are already cached.

For example, if a request comes in with a kid that is not in the cached JWKs, AM checks the value of JWKs' URI content cache miss cache time. If the amount of time specified in this property has already passed since the last time AM fetched the JWKs, AM fetches them again. Otherwise, the request is rejected.

Use this property as a rate limit to prevent denial-of-service attacks against the URI.

Default: 60000

amster attribute: com.forgerock.openam.oauth2provider.jwkStoreCacheMissCacheTime

Json Web Key

If the Public key selector: property is set to JWKs, specify the remote consent service’s public keys, in JSON Web Key format.

Example:

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "RemA6Gw0...LzsJ5zG3E=",
      "use": "enc",
      "alg": "RSA-OAEP-256",
      "n": "AL4kjz74rDo3VQ3Wx...nhch4qJRGt2QnCF7M0",
      "e": "AQAB"
    },
    {
      "kty": "RSA",
      "kid": "wUy3ifIIaL...eM1rP1QM=",
      "use": "sig",
      "alg": "RS256",
      "n": "ANdIhkOZeSHagT9Ze...ciOACVuGUoNTzztlCUk",
      "e": "AQAB"
    }
  ]
}

amster attribute: jwkSet

Consent Request Time Limit

Specify the amount of time, in seconds, for which the consent request JWT sent to the remote consent service should be considered valid.

Default: 180

amster attribute: requestTimeLimit

Save your changes.

The remote consent agent profile is now available for selection in the OAuth 2.0 provider. See Configure the OAuth 2.0 provider to use a remote consent agent profile.

Configure the OAuth 2.0 provider to use a remote consent agent profile

To add the details of the remote consent agent profile to an OAuth 2.0 provider service:

In the AM admin UI, go to Realms > Realm Name > Services > OAuth2 Provider.
On the Consent tab:
- Click Enable Remote Consent.
- In the Remote Consent Service ID drop-down list, select the agent ID of the remote consent agent. For example, myRCSAgent.
If required, modify the supported signing and encryption methods and algorithms used for the consent request and consent response JSON web tokens.

For more information on the available properties, see Consent.

Example

Figure 1. Configure RCS in an OAuth 2.0 provider
Save your changes.

OAuth 2.0 flows by any client in the realm will now use the remote consent service. OAuth 2.0 clients in other realms are unaffected.

Configure the AM example remote consent service

AM includes an example remote consent service that lets you demonstrate and test remote consent.

The example remote consent service is not intended for use in production environments, because the encryption and signing algorithms are not configurable. It is just an example that shows how you can configure AM to use a custom remote consent service.

The following example uses two instances of AM:

One instance that acts as the authorization server. For example, https://openam.example.com:8443/openam.
One instance that acts as the example remote consent service. For example, https://rcs.exampe.com:8443/openam.

Perform the following steps to configure your environment:

As an administrative user, for example, amAdmin log in to the instance that acts as the example remote consent service.
Go to Realms > Realm Name > Services, and click Add a Service.
From the Choose a service type drop-down list, select Remote Consent Service.
Perform the following steps to configure the remote consent service:
- In Client Name, enter the agent ID given to the remote consent agent profile in AM.
  
  In this example, enter myRCSAgent.
- In Authorization Server jwk_uri, enter the URI where the remote consent service will obtain the keys that the authorization service uses to sign and encrypt the consent request. These keys include:
  - The public signing key, used to sign the consent request that is sent to the remote consent server, so that it can be validated on the remote consent server.
  - The public encryption key for the consent response, so that the response can be encrypted (if encryption is enabled).
    
    The default JWKs URI for remote consent clients is /oauth2/consent_agents/jwk_uri.

For example, https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/consent_agents/jwk_uri.

Click Create.
Verify the configuration. For more information about the available properties, see Remote consent service.
1. Configure the secret labels for encrypting the consent request and signing the consent response.
  
  You can use an existing secret store at the global or realm level, or create a new secret store. This step assumes you have a keystore secret store in the realm where the remote consent service is configured:
Go to Realms > Realm Name > Secret Stores, and click the name of the keystore secret store that contains the secrets you will use to sign and encrypt the consent response.

On the Mappings tab, add the following mappings if not already present:

am.services.oauth2.remote.consent.response.signing.RSA: rsajwtsigningkey
am.services.oauth2.remote.consent.request.encryption: test

These keys must match the configuration of the remote consent service agent.

For more information about mapping secrets, refer to Map and rotate secrets.

In the AM admin UI of the instance acting as the OAuth 2.0 provider, configure a remote consent service agent by performing the steps in Configure AM to use a remote consent service.

The example remote consent service provides an /oauth2/consent/jwk_uri path to provide its public keys to the authorization server. In this example, configure https://rcs.example.com:8443/openam/oauth2/consent/jwk_uri in the Json Web Key URI field.

Configure the authorization server to use the remote consent service agent by performing the steps in Configure the OAuth 2.0 provider to use a remote consent agent profile.
Test your configuration.

Performing an OAuth 2.0 flow on the AM instance that is acting as the authorization server will redirect the user to the second instance when user consent is required:

Example remote consent service

Note that the fr-dark-theme has been applied to the AM instance acting as the remote consent service for the purpose of this demonstration.

For more information on customizing the user interface, refer to UI customization.

PingAM 7.5.0

Remote consent

Configure AM to use a remote consent service

Configure the OAuth 2.0 provider to use a remote consent agent profile

Configure the AM example remote consent service