The 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.
{
"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 server 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".
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 | "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 from AM the required signature and decryption keys. | 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, select Realms, and then select the realm that you are working with.
Navigate to Applications > 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
JWKsis selected, you must 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 AM example remote consent service provides an
/oauth2/consent/jwk_uripath to provide the 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, select Realms, and then select the realm that you are working with.
Navigate to 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".
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 to demonstrate and test AM's remote consent feature.
Note
The Remote Consent Service in AM is not intended for use in production environments, since the encryption and signing algorithms are not configurable. It serves as an example of configuring 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:
Log in to the instance that acts as the example remote consent service with an administrative user, for example,
amAdmin.Navigate to Realms > Realm Name > Services, and then select 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 Signing Key Alias, enter the alias of key that will sign the consent response. Ensure the selected key matches the supported signing methods and algorithms configured for the remote consent service in the OAuth 2.0 provider in AM.
For this example, enter
rsajwtsigningkey. This test key alias will work with the default signing settings, and is provided by default in AM's default key store.In Encryption Key Alias, enter the alias of key that will encrypt the consent response. Ensure the selected key matches the supported encryption methods and algorithms configured for the remote consent service in the OAuth 2.0 provider in AM.
For this example, enter
test. This test key alias will work with the default encryption settings, and is provided by default in AM's default key store.In Authorization Server jwk_uri, enter the URI where the remote consent service can obtain the keys that the instance acting as the authorization service uses to sign and encrypt the consent request.
For this example, enter
https://openam.example.com:8443/openam/oauth2/connect/jwk_uri.Select Create.
Verify the configuration. For more information about the available properties, see "Remote Consent Service".
Log in to the instance acting as the authorization server as an administrative user, for example,
amAdmin.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:
Note that the fr-dark-theme has been applied to 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.
