--- title: Remote consent description: AM supports OAuth 2.0 remote consent, which hands off the consent-gathering part of an OAuth 2.0 flow to a separate service. component: pingam version: 8.1 page_id: pingam:am-oauth2:oauth2-remote-consent canonical_url: https://docs.pingidentity.com/pingam/8.1/am-oauth2/oauth2-remote-consent.html keywords: ["OAuth 2.0", "OpenID Connect (OIDC)", "JWT", "Authorization", "Setup & Configuration"] page_aliases: ["oauth2-guide:oauth2-remote-consent.adoc"] section_ids: remote-consent-channel: Choose a consent request channel remote-consent-flow: Remote consent flows remote-consent-front-channel-flow: Front channel remote-consent-backchannel-flow: Backchannel rcs-configuration-overview: RCS configuration overview proc-oauth2-rcs-agent: Configure AM to use an RCS proc-oauth2-provider-rcs: Add RCS agent to the OAuth 2.0 provider proc-oauth2-rcs-example: Test the example RCS --- # Remote consent AM supports OAuth 2.0 *remote consent*, which hands off the consent-gathering part of an OAuth 2.0 flow to a separate service. A remote consent service (RCS) renders a consent page, gathers the result, signs and encrypts the result, and returns it to the authorization server. ## Choose a consent request channel When AM needs to gather consent, it sends a consent request JWT to the RCS. You can choose how to deliver this JWT: * Front channel AM redirects the resource owner's browser to the RCS, passing the consent request JWT as a URL parameter. This is the default behavior when no [Pushed Consent Request URL](#pushed-consent-request-url) is configured on the remote consent agent. * Backchannel (pushed consent) AM sends the consent request JWT directly to the RCS over a server-to-server HTTP POST (backchannel), before redirecting the resource owner. The RCS stores the request and returns an opaque `consent_request_uri` token. AM then redirects the resource owner to the RCS using this token instead of the full JWT. This approach keeps the consent request JWT out of the browser and reduces exposure in URL logs. Configure the [Pushed Consent Request URL](#pushed-consent-request-url) on the remote consent agent to enable this option. ## Remote consent flows ### Front channel The front channel flow is the default. It's used when the [Pushed Consent Request URL](#pushed-consent-request-url) is not configured on the remote consent agent. ![The front channel remote consent service flow](_images/oauth2-remote-consent-flow.svg) During an OAuth 2.0 flow that requires user consent: 1. AM creates a *consent request* JWT that contains the necessary information to render a consent gathering page. | | | | - | ---------------------------------------------------------- | | | AM doesn't send the actual values of the requested scopes. | > **Collapse: Consent request JWT example and properties** > > ```json > { > "clientId": "myClient", > "iss": "https://am.example.com:8443/am/oauth2/realms/root/realms/alpha", > "csrf": "gjeH2C43nFJwW+Ir1zL3hl8kux9oatSZRso7aCzI0vk=", > "resourceOwnerSessionProperties": { > "myProperty": "myValue" > }, > "client_description": "", > "aud": "rcs", > "save_consent_enabled": true, > "authorization_details": [{ > "type": "account_information", > "actions": [ > "list_accounts", > "read_balances", > "read_transactions" > ], > "locations": [ > "https://example.com/accounts" > ] > }], > "claims": {}, > "scopes": { > "write": null > }, > "exp": 1536229486, > "iat": 1536229306, > "client_name": "My Client", > "consentApprovalRedirectUri": "https://am.example.com:8443/am/oauth2/authorizeWithConsent?client_id=MyClient&response_type=code&redirect_uri=https://application.example.com:8443/callback&scope=write&state=1234zy", > "username": "bjensen" > } > ``` > > * `aud` > > The name of the expected recipient of the JWT, in this case, the RCS. > > * `authorization_details` > > Additional fine-grained authorization requirements, as specified in [RFC 9396: OAuth 2.0 Rich Authorization Requests](https://www.rfc-editor.org/rfc/rfc9396.html). > > Find more information in [authorization\_details](oauth2-parameters.html#authorization_details). > > * `claims` > > The claims the request makes. > > Use the `claims` field for additional information to display on the remote consent page. This information can help the user determine if they should grant consent. For example, Open Banking OAuth 2.0 flows might include identifiers for a money transaction. > > * `client_description` > > A description of the OAuth 2.0 client making the request. > > * `client_id` > > The ID of the OAuth 2.0 client making the request. > > * `client_name` > > The display name of the OAuth 2.0 client making the request. > > * `consentApprovalRedirectUri` > > The URI to which AM directs the resource owner after they've provided consent. The response JWT must be sent as a `consent_response` form parameter in a POST request to this URI. > > * `csrf` > > 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. > > * `exp` > > The expiration time of the JWT. > > Use short expiration times (180 seconds, for example) because the JWT is intended for use in machine-to-machine interactions. > > * `iat` > > The creation time of the JWT. > > * `iss` > > The name of the issuer, configured in the [OAuth 2.0 provider service](oauth2-configure-authz.html). > > * `resourceOwnerSessionProperties` > > Custom properties from the resource owner's session to include in the remote consent request. To configure the properties to send, map session properties in the [Resource Owner Session Properties](#resource-owner-session-properties) field in the RCS agent configuration. > > * `save_consent_enabled` > > Whether to give 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`. | > > * `scopes` > > The requested scopes. > > * `username` > > The username of the authenticated user. > > | | | > | - | ----------------------------------------------------------------------------------------------------- | > | | If the username could be considered personally identifiable information, you must *encrypt* the JWT . | 2. Acting as the authorization server, AM signs and encrypts the JWT. 3. The RCS does the following: 1. Decrypts the JWT. 2. Verifies the signature and other details, such as the validity of the `aud`, `iss`, and `exp` properties, and any specified `authorization_details`. 3. Renders the consent page to the resource owner. 4. Gathers the user's consent. 5. Creates a *consent response* JWT. 6. Encrypts and signs the response. 7. Returns the response to AM for processing. > **Collapse: Consent response JWT example and properties** > > ```json > { > "consent_response" : { > "clientId": "myClient", > "iss": "rcs", > "csrf": "gjeH2C43nFJwW+Ir1zL3hl8kux9oatSZRso7aCzI0vk=", > "client_description": "", > "aud": "https://am.example.com:8443/am/oauth2", > "save_consent": true, > "authorization_details": [{ > "type": "account_information", > "actions": [ > "list_accounts", > "read_balances", > "read_transactions" > ], > "locations": [ > "https://example.com/accounts" > ] > }], > "claims": {}, > "scopes": "[write]", > "exp": 1536229430, > "iat": 1536229250, > "client_name": "My Client", > "consentApprovalRedirectUri": "https://am.example.com:8443/am/oauth2/authorizeWithConsent?client_id=MyClient&response_type=code&redirect_uri=https://application.example.com:8443/callback&scope=write&state=1234zy", > "username": "bjensen", > "decision": true > }, > > } > ``` > > * `iat` > > The creation time of the JWT. > > * `iss` > > The name of the RCS. > > Must match the value of the `aud` property received from AM. > > * `aud` > > The name of the expected recipient of the JWT, in this case, AM acting as the authorization server. > > Must match the value of the `iss` property received from AM. > > * `authorization_details` > > The fine-grained authorization requirements sent to the RCS. Currently, if these details are valid, AM doesn't process them in the response. There's no way to allow the RCS to augment the `authorization_details` in such a way as to have them become part of the authorization grant. > > | | | > | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | | If the authorization details are invalid, the RCS can return an `invalid_authorization_details` error as part of the consent response JWT. AM forwards this error, along with the provided `error_description` and `error_uri`, to the client. For example:```json > { > "iss": "rcs", > "aud": "{amExampleUrl}/oauth2", > "exp": 1739181167, > ... > "error": "invalid_authorization_details", > "error_description": "The authorization details are invalid.", > "error_uri": "https://docs.example.com/errors/invalid_authorization_details", > "state": "xyz123" > } > ```For AM to forward the error:- There *must* be an `error` parameter and its value *must* be `invalid_authorization_details`. > > - The `error_description` and `error_uri` parameters are optional. If included, their values must conform with [RFC 6749: The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749.html). > > - If the value of `error` is not `invalid_authorization_details`, AM ignores the `error_description` and `error_uri` properties. | > > * `exp` > > The expiration time of the JWT. > > The JWT is intended for use in machine-to-machine interactions. Use short expiration times, for example, 180 seconds. > > * `decision` > > `true` if consent was provided, or `false` if consent was withheld. > > * `client_id` > > The ID of the OAuth 2.0 client making the request, matching the value provided in the request. > > * `client_name` > > The display name of the OAuth 2.0 client making the request. > > * `client_description` > > A description of the OAuth 2.0 client making the request. > > * `scopes` > > An array of allowed scopes. > > Must be equal to, or a subset of, the array of scopes in the request. > > * `save_consent` > > `true` if the user chose to save their consent decision, or `false` if they didn't. > > If `save_consent_enabled` was set to `false` in the request, `save_consent` must also be `false`. > > * `consentApprovalRedirectUri` > > The URI to which AM returns the resource owner after they've provided consent. 4. AM then does the following: 1. Decrypts and verifies the signature of the consent response and other details, such as the validity of the `aud`, `iss` and `exp` properties. 2. Processes the response. For example, it could save the consent decision if configured to do so. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If the RCS compresses the consent response JWT, AM rejects JWTs that expand to a size larger than 32 KiB (32768 bytes). Find more information in [Control the size of compressed JWTs](../security/control-maximum-size-decompressed-JWT.html). | ### Backchannel The backchannel flow applies when a [Pushed Consent Request URL](#pushed-consent-request-url) is configured on the remote consent agent. Use it to keep the consent request JWT out of the browser and reduce exposure in URL logs. ![AM sending a consent request JWT to the RCS over a backchannel before redirecting the resource owner.](_images/oauth2-remote-consent-backchannel-flow.svg) During an OAuth 2.0 flow that requires user consent, the backchannel flow proceeds as follows: 1. AM creates a consent request JWT and signs and encrypts it, as in the front channel flow. 2. Instead of passing the JWT to the resource owner's browser, AM sends it directly to the RCS in a POST request to the [Pushed Consent Request URL](#pushed-consent-request-url). 3. The RCS verifies the JWT and stores the details of the consent request against an opaque token. It returns the opaque token to AM in a `consent_request_uri` parameter, for example: ```json { "consent_request_uri": "consent-FVaTaZTWuQGZkQX" } ``` This response has a HTTP 201 status code. 4. AM redirects the resource owner's browser to the RCS, passing the `consent_request_uri` token instead of the consent request JWT. 5. The RCS does the following: 1. Retrieves the stored consent request using the token. 2. Decrypts the consent request JWT if it was encrypted. 3. Renders the consent page to the resource owner. 4. Gathers the user's consent. 5. Creates a consent response JWT. 6. Encrypts and signs the response. 7. Returns the response to AM for processing. 6. AM decrypts, verifies, and processes the consent response as in the front channel flow. ## RCS configuration overview Configuring an RCS in AM includes the following high-level tasks: | Task | Resources | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Add the details of the RCS as an agent profile in AM**You can configure a single RCS 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 RCS. | [Configure AM to use an RCS](#proc-oauth2-rcs-agent) Both AM and the RCS make their required public keys available from a jwk\_uri to enable signing and encryption between the two servers. | | **Enable remote consent and specify the agent profile in AM's OAuth 2.0 provider service.** | [Add RCS agent to the OAuth 2.0 provider](#proc-oauth2-provider-rcs) | | **Configure the RCS with AM's `jwk_uri` URI details.**The RCS must be able to obtain the required signature and decryption keys from AM. | AM includes an example RCS for testing purposes. Don't use the example in production environments.Find more information in [Test the example RCS](#proc-oauth2-rcs-example). | ## Configure AM to use an RCS To add the details of the RCS as an agent profile: 1. In the AM admin UI, go to Realms > *realm name* > Applications > OAuth 2.0 > Remote Consent. 2. Click + Add Remote Consent Agent. 3. Enter an agent ID, for example, `myRCSAgent`. 4. If you'll use an HMAC algorithm for signing the JWTs, enter the shared symmetric key in the Remote Consent Service secret field. This step isn't required when using other algorithms. 5. Click Create. 6. Select the Remote Consent Agent, and configure the properties as required. > **Collapse: 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 > > The shared secret for the RCS. This value is used as the symmetric key when you select HMAC signing or symmetric encryption for consent JWTs, or as the HTTP Basic password when pushed consent authentication is set to `Basic`. > > `amster` attribute: `userpassword` > > * Redirect URL > > The URL to which the user should be redirected during the OAuth 2.0 flow to obtain their consent. > > The AM example RCS provides an `/oauth2/consent` path to obtain consent from the user. > > Example: `https://rcs.example.com:8443/am/oauth2/consent` > > `amster` attribute: `remoteConsentRedirectUrl` > > - Pushed Consent Request URL > > The RCS URL to which AM sends pushed consent requests. > > AM sends a POST request to this endpoint containing the remote consent request JWT, for example: > > ```json > { > "consent_request":"request JWT" > } > ``` > > The RCS verifies the consent request JWT and stores the details of the consent request against an opaque token. It returns the opaque token to AM in a `consent_request_uri` parameter as a response to the request. For example: > > ```json > { > "consent_request_uri":"consent-FVaTaZTWuQGZkQX" > } > ``` > > AM proceeds with the usual remote consent flow, but the OAuth 2.0 client is redirected to the RCS with the `consent_request_uri` parameter instead of the remote consent request JWT. > > | | | > | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | | For security reasons, the `consent_request_uri`:- Should contain a random element that can't be guessed. > > - Should have a short expiry time, for example, two minutes. > > - Must be used only once. | > > `amster` attribute: `pushedConsentRequestUrl` > > * Pushed Consent Authentication Method > > The authentication method, which determines whether to send credentials to the RCS for pushed consent requests. > > Options are: > > * `None` (default): AM sends no client credentials with the pushed consent request. > > * `Basic`: AM sends client credentials in an HTTP Basic authentication header with the pushed consent request. > > | | | > | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | | The Basic authentication header exposes the agent's credentials in an unencrypted form. If you select this option, make sure your [Pushed Consent Request URL](#pushed-consent-request-url) uses HTTPS to avoid exposing unencrypted credentials over insecure network channels. | > > `amster` attribute: `pushedConsentAuthenticationMethod` > > * Enable consent request Encryption > > Whether to encrypt the consent request JWT sent to the RCS. > > Default: `true` > > `amster` attribute: `remoteConsentRequestEncryptionEnabled` > > * Consent request Encryption Algorithm > > The encryption algorithm used to encrypt the consent request JWT sent to the RCS. > > 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 > > The encryption method used to encrypt the consent request JWT sent to the RCS. > > 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 > > The algorithm used to verify a signed consent response JWT received from the RCS. > > AM supports signing algorithms listed in JSON Web Algorithms (JWA): ["alg" (Algorithm) Header Parameter Values for JWS](https://datatracker.ietf.org/doc/html/draft-ietf-jose-json-web-algorithms#section-3.1): > > * `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 > > The encryption algorithm used to decrypt the consent response JWT received from the RCS. > > 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(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, AM uses the value of the Remote Consent Service secret property 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](../security/secrets-certs-keys.html). > > Default value: `RSA-OAEP-256` > > `amster` attribute: `remoteConsentResponseEncryptionAlgorithm` > > * Consent request Signing Algorithm > > The algorithm used to sign the consent request JWT sent to the RCS. > > 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(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`), AM uses the value of the `Remote Consent Service secret` property 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. 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.For information about managing secret stores and mapping secret labels to aliases, refer to [Secrets, certificates, and keys](../security/secrets-certs-keys.html). | > > Default value: `RS256` > > `amster` attribute: `remoteConsentRequestSigningAlgorithm` > > * Consent response encryption method > > The encryption method used to decrypt the consent response JWT received from the RCS. > > 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 > > Whether the RCS 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. If you select `JWKs_URI`, complete the JWKs URI-related properties. > > Default: `JWKs_URI` > > `amster` attribute: `remoteConsentRedirectUrl` > > * Json Web Key URI > > The URI from which AM can obtain the RCS's public keys. > > The example RCS uses the URI `/oauth2/consent/jwk_uri` to provide its public keys. > > Example: `https://rcs.example.com:8443/am/oauth2/consent/jwk_uri` > > `amster` attribute: `jwksUri` > > * JWKs URI content cache timeout in ms > > The period of time, in milliseconds, that the content of the JWKs' URI is cached 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 > > The period of time, in milliseconds, that AM waits before fetching the URI's content again when a key ID (`kid`) isn't in the JWKs that are already cached. > > For example, if a request comes in with a `kid` that isn't in the cached JWKs, AM checks the value of JWKs' URI content cache miss cache time. If the period 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 RCS's public keys, in JSON Web Key format. > > Example: > > ```json > { > "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 > > The period of time, in seconds, for which the consent request JWT sent to the RCS should be considered valid. > > Default: `180` > > `amster` attribute: `requestTimeLimit` > > - Resource Owner Session Properties > > Properties to include in the remote consent request, if available in the resource owner's session. Each entry maps a session property name to the name of the claim for that property in the request. > > `Key` is the name of the property in the session and `Value` is the name of the property in the RCS JWT. > > Properties appear in the remote consent request JWT nested under the `resourceOwnerSessionProperties` field. If you don't configure any mappings here, the remote consent request JWT won't contain a `resourceOwnerSessionProperties` field. > > `amster` attribute: `resourceOwnerSessionProperties` 7. Save your changes. The remote consent agent profile is now available for selection in the OAuth 2.0 provider. Find more information in [Add RCS agent to the OAuth 2.0 provider](#proc-oauth2-provider-rcs). ## Add RCS agent to the OAuth 2.0 provider 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 > OAuth2 Provider. 2. 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`. 3. If required, modify the supported signing and encryption methods and algorithms used for the consent request and consent response JSON web tokens. Find more information on the RCS configuration properties in [Consent](../setup/services-configuration.html#global-oauth-oidc-consent). 4. Save your changes. OAuth 2.0 flows by any client in the realm will now use the RCS. OAuth 2.0 clients in other realms are unaffected. ## Test the example RCS AM includes an example RCS that lets you demonstrate and test remote consent. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | The example RCS isn't intended for use in production environments because you can't configure the encryption and signing algorithms. The example is intended only to demonstrate how you can configure AM to use a custom RCS. | The following example uses two instances of AM: * One instance acts as the authorization server. For example, `https://am.example.com:8443/am`. * One instance acts as the example RCS. For example, `https://rcs.example.com:8443/am`. Perform the following steps to configure your environment: 1. As an administrative user, for example, `amAdmin` log in to the instance that acts as the example RCS. 2. Go to Realms > *realm name* > Services, and click Add a Service. 3. From the Choose a service type drop-down list, select Remote Consent Service. 4. Perform the following steps to configure the RCS: 1. In Client Name, enter the agent ID given to the remote consent agent profile in AM. In this example, enter `myRCSAgent`. 2. In Authorization Server jwk\_uri, enter the URI where the RCS will obtain the keys that the authorization service uses to sign and encrypt the consent request. These keys include: * The public signing key the RCS uses to verify the signature of the consent request. * 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://am.example.com:8443/am/oauth2/realms/root/realms/alpha/consent_agents/jwk_uri`. 3. Click Create. 4. Verify the configuration. Find more information about the available properties in [Remote consent service](../setup/services-configuration.html#global-remoteconsentservice). 5. 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 RCS is configured: * Go to Realms > *realm name* > Secret Stores, and click the name of the keystore secret store that contains the secrets you'll 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 [RCS agent](#proc-oauth2-rcs-agent). Find more information about mapping secrets in [Map and rotate secrets](../security/secret-mapping.html). 6. In the AM admin UI of the instance acting as the OAuth 2.0 provider, configure an RCS agent by performing the steps in [Configure AM to use an RCS](#proc-oauth2-rcs-agent). | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The example RCS 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/am/oauth2/consent/jwk_uri` in the Json Web Key URI field. | 7. Configure the authorization server to use the RCS agent by performing the steps in [Add RCS agent to the OAuth 2.0 provider](#proc-oauth2-provider-rcs). 8. Test your configuration. Performing an OAuth 2.0 flow on the AM instance that's acting as the authorization server redirects the user to the second instance when user consent is required. The remote consent service renders the consent page, using the decrypted information received from AM acting as the authorization server.