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.
{
"clientId": "myClient",
"iss": "https://openam.example.com:8443/openam/oauth2",
"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.
Tip
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 thesave_consentproperty in the consent response from the RCS must also befalse.-
consentApprovalRedirectUri Specifies the URI to return the resource owner to after they have provided consent. The response JWT must be sent as a
consent_responseform 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" : {
"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
audproperty 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
issproperty 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
trueif consent was provided, orfalseif 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
trueif the user chose to save their consent decision, orfalseif they did not.If
save_consent_enabledwas set tofalsein the request,save_consentmust also befalse.-
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.
Note
If the remote consent service compresses the consent response JWT, note that by default, AM rejects JWTs that expand to a size larger than 32 KiB (32768 bytes).For more information, see "Controlling the Maximum Size of Compressed JWTs".
AM and the remote consent service make their required public keys available fromm two jwk_uris, to enable 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 | "To Configure AM to use a Remote Consent Service" |
| Enable remote consent and specify the agent profile in AM's OAuth 2.0 provider service. | "To Configure the OAuth 2.0 Provider to Use a Remote Consent Agent Profile" |
| Configure the remote consent service with AM's The remote consent service must be able to obtain the required signature and decryption keys from AM. | N/A |
Note
AM includes an example remote consent service. Do not use the example in production environments.
To add the details of the remote consent service as an agent profile:
In the AM console, go to Realms > Realm Name > Applications > OAuth 2.0 > Remote Consent, and select Add Remote Consent Agent.
Enter an Agent ID, for example,
myRCSAgent, and then select Create.(Optional) 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 then configure the properties as required.
- Group
Configure several remote consent agent profiles by assigning them to a group.
Default value:
noneamster 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/consentpath to obtain consent from the user.Example:
https://rcs.example.com:8443/openam/oauth2/consentamster 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 [a] 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 [a] If you select an HMAC algorithm for signing consent requests (
HS256,HS384, orHS512), 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.signingsecret ID.By default, secret IDs are mapped to demo keys contained in the default keystore provided with AM and mapped to the
default-keystorekeystore 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 more information about managing secret stores and mapping secret IDs to aliases, see Configuring Secrets, Certificates, and Keys.
Default value:
RS256amster attribute:
remoteConsentRequestSigningAlgorithm- Enable consent request Encryption
Specify whether to encrypt the consent request JWT sent to the Remote Consent Service.
Default:
trueamster 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-256amster 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, andA256GCM- AES in Galois Counter Mode (GCM) authenticated encryption mode.A128CBC-HS256,A192CBC-HS384, andA256CBC-HS512- AES encryption in CBC mode, with HMAC-SHA-2 for integrity.
Default value:
A128GCMamster 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:
RS256amster 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[a] am.services.oauth2.remote.consent.response.decryption test RSA-OAEP-256 [a] If you select an algorithm other than
RSA-OAEP-256for 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 IDs are mapped to demo keys contained in the default keystore provided with AM and mapped to the
default-keystorekeystore 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 more information about managing secret stores and mapping secret IDs to aliases, see Configuring Secrets, Certificates, and Keys.
Default value:
RSA-OAEP-256amster 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, andA256GCM- AES in Galois Counter Mode (GCM) authenticated encryption mode.A128CBC-HS256,A192CBC-HS384, andA256CBC-HS512- AES encryption in CBC mode, with HMAC-SHA-2 for integrity.
Default value:
A128GCMamster attribute:
remoteConsentResponseEncryptionMethod- Public key selector
Specify whether the remote consent service provides its public keys using a
JWKs_URI, or manually inJWKsformat.If you select
JWKs, enter the keys in the Json Web Key property. Otherwise complete the JWKs URI-related properties.Default:
JWKs_URIamster 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_urito provide its public keys.Example:
http://rcs.example.com:8080/openam/oauth2/consent/jwk_uriamster 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:
3600000amster 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
kidthat 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:
60000amster 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:
180amster attribute:
requestTimeLimit
Save your changes.
The Remote Consent Agent profile is now available for selection in the OAuth 2.0 provider. See "To 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 console, go to Realms > Realm Name > Services, and then select OAuth2 Provider.
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.
(Optional) 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".
Configuring 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.
AM includes an example Remote Consent Service that lets you demonstrate and test remote consent.
Note
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,
amAdminlog in to the instance that acts as the example remote consent service with.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 the Authorization Server jwk_uri field, 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.Select Create.
Verify the configuration. For more information about the available properties, see "Remote Consent Service".
Configure the secret IDs 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 Server is configured:
Go to Realms > Realm Name > Secret Stores, and click on 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:rsajwtsigningkeyam.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, see "Mapping and Rotating Secrets".
In the AM console of the instance acting as the OAuth 2.0 provider, configure a remote consent service agent by performing the steps in "To Configure AM to use a Remote Consent Service".
Note
The example remote consent service provides an
/oauth2/consent/jwk_uripath to provide its public keys to the authorization server. In this example, configurehttps://rcs.example.com:8443/openam/oauth2/consent/jwk_uriin the Json Web Key URI field.Configure the authorization server to use the remote consent service agent by performing the steps in "To 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, see the UI Customization Guide.
