Remote Consent Service

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.

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
{
  "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.

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

Should 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 server compresses the consent response JWT, note that by default, AM rejects JWTs that expand to a size larger than 32 KiB (32768 bytes).

Both AM and the remote consent service make the required public keys available from a jwk_uri URI, enabling the signing and encryption between the two servers.

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

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.

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

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

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

N/A

Configure AM to use a Remote Consent Service

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

  1. In the AM Admin UI, go to Realms > Realm Name > Applications > Remote Consent, and select Add Remote Consent Agent.

  2. Enter an Agent ID, for example, myRCSAgent, and then select Create.

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

  4. Select the Remote Consent Agent, and then 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. Reenter the password in the Remote Consent Service secret (confirm) property.

    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

    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 algorithm chosen. The relevant secret IDs and the default signing key aliases are shown in the table below:

    The following table shows the secret ID mappings used to sign remote consent requests:

    Secret ID Default Alias Algorithms(1)

    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

    (1) 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.

    Since the HMAC secret is shared between AM and the remote consent client, 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 ID.

    Default value: RS256

    amster attribute: remoteConsentRequestSigningAlgorithm

    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 algorithm chosen. The relevant secret IDs and the default decryption key aliases are shown in the table below: The following table shows the secret ID mapping used to decrypt remote consent responses:

    Secret ID Default Alias Algorithms(1)

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

    test

    RSA-OAEP-256

    (1) 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.

    Default value: RSA-OAEP-256

    amster attribute: remoteConsentResponseEncryptionAlgorithm

    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 JWKs is selected, you must 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 AM example remote consent service provides an /oauth2/consent/jwk_uri path to provide the 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

  5. 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:

  1. In the AM Admin UI, go to Realms > Realm Name > Services, and then select OAuth2 Provider.

  2. On the Consent tab:

    • Select Enable Remote Consent.

    • In the Remote Consent Service ID drop-down list, select the Agent ID of the Remote Consent Agent. For example, myRCSAgent.

  3. 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
    Configure the service ID, and encryption and signing properties.
    Figure 1. Configuring RCS in an OAuth 2.0 Provider
  4. 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.