--- title: Remote consent service description: Advanced Identity Cloud supports OAuth 2.0 remote consent, which hands off the consent-gathering part of an OAuth 2.0 flow to a separate service. component: pingoneaic page_id: pingoneaic:am-oauth2:oauth2-remote-consent canonical_url: https://docs.pingidentity.com/pingoneaic/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_flows: Remote consent flows remote-consent-front-channel-flow: Front channel the_consent_request: The consent request the_consent_response: The consent response remote-consent-backchannel-flow: Backchannel the_consent_request_2: The consent request the_consent_response_2: The consent response configuration: Configuration proc-oauth2-rcs-agent: Remote consent agent profile proc-oauth2-provider-rcs: Use the profile --- # Remote consent service Advanced Identity Cloud 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) gathers resource owner consent separately from the authorization server (Advanced Identity Cloud). The 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 Advanced Identity Cloud needs to gather consent, it sends a consent request JWT to the RCS. You can choose how to deliver this JWT: * Front channel Advanced Identity Cloud 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) Advanced Identity Cloud 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. Advanced Identity Cloud 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) #### The consent request During an OAuth 2.0 flow that requires user consent: 1. Advanced Identity Cloud creates a *consent request* JSON Web Token (JWT). The JWT contains the necessary information to render a consent gathering page. > **Collapse: Example request body** > > ```json > { > "aud": "rcs", > "claims": {}, > "clientId": "myClient", > "client_description": "", > "client_name": "My Client", > "consentApprovalRedirectUri": "https:///am/oauth2/realms/root/realms/alpha/authorizeWithConsent?client_id=myClient&response_type=code&redirect_uri=redirect-uri&scope=write&state=1234zy", > "csrf": "opaque-csrf-string", > "resourceOwnerSessionProperties": { > "myProperty": "myValue" > }, > "exp": 1678800541, > "iat": 1678800361, > "iss": "https:///am/oauth2/realms/root/realms/alpha", > "save_consent_enabled": true, > "authorization_details": [{ > "type": "account_information", > "actions": [ > "list_accounts", > "read_balances", > "read_transactions" > ], > "locations": [ > "https://example.com/accounts" > ] > }], > "scopes": { > "write": null > }, > "username": "a0325ea4-9d9b-4056-931b-ab64704cc3da" > } > ``` > > The consent request body includes these fields: > > * `aud` > > 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. Include any additional information required for display on the remote consent page to help the resource owner determine whether to grant consent. For example, Open Banking OAuth 2.0 flows include identifiers for money transactions. > > * `client_description` > > A description of the OAuth 2.0 client making the request. > > * `clientId` > > 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` > > Where to redirect the resource owner after they have provided consent. The RCS must send the response JWT as a `consent_response` form parameter in a POST operation to this URI. > > * `csrf` > > A unique string to return in the response to help prevent cross-site request forgery (CSRF) attacks. > > Advanced Identity Cloud generates this string from a hash of the user's session ID. > > * `exp` > > The expiration time of the JWT. Use short expiration times such as 180 seconds. The JWT is intended for machine-to-machine interactions. > > * `iat` > > Creation time of the JWT. > > * `iss` > > The name of the issuer configured for the OAuth 2.0 provider service (under Native Consoles > Access Management). > > * `save_consent_enabled` > > Whether to let the resource owner choose 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 authenticated resource owner's identifier. Encrypt the JWT if the username is considered personally identifiable information. 2. Acting as the authorization server, Advanced Identity Cloud 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. #### The consent response After the RCS gathers the resource owner's consent, it creates a *consent response* JWT. The RCS encrypts and signs the consent response JWT and returns it to Advanced Identity Cloud. > **Collapse: Example response body** > > ```json > { > "consent_response" : { > "aud": "https:///am/oauth2/realms/root/realms/alpha", > "authorization_details": [{ > "type": "account_information", > "actions": [ > "list_accounts", > "read_balances", > "read_transactions" > ], > "locations": [ > "https://example.com/accounts" > ] > }], > "claims": {}, > "clientId": "myClient", > "client_description": "", > "client_name": "My Client", > "consentApprovalRedirectUri": "https:///am/oauth2/realms/root/realms/alpha/authorizeWithConsent?client_id=myClient&response_type=code&redirect_uri=&scope=write&state=1234zy", > "csrf": "", > "decision": true, > "exp": 1678810581, > "iat": 1678810401, > "iss": "rcs", > "save_consent": true, > "scopes": "[write]", > "username": "a0325ea4-9d9b-4056-931b-ab64704cc3da" > } > } > ``` > > The consent response body includes these fields: > > * `aud` > > The expected recipient of the JWT; must match the `iss` of the request. > > * `authorization_details` > > The fine-grained authorization requirements sent to the RCS. Currently, if these details are valid, Advanced Identity Cloud 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. Advanced Identity Cloud 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 Advanced Identity Cloud 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`, Advanced Identity Cloud ignores the `error_description` and `error_uri` properties. | > > * `claims` > > The claims the request made. > > * `client_description` > > A description of the OAuth 2.0 client making the request. > > * `clientId` > > Must match the `clientId` of the request. > > * `client_name` > > The display name of the OAuth 2.0 client making the request. > > * `consentApprovalRedirectUri` > > Where to redirect the resource owner after they have provided consent. > > * `csrf` > > A unique string to return in the response to help prevent cross-site request forgery (CSRF) attacks. > > * `decision` > > `true` means the resource owner granted consent; `false` means the resource owner withheld consent. > > * `exp` > > The expiration time of the JWT. Use short expiration times such as 180 seconds. The JWT is intended for machine-to-machine interactions. > > * `iat` > > Creation time of the JWT. > > * `iss` > > The name of the issuer; must match the `aud` of the request. > > * `save_consent` > > `true` if the resource owner chose to save their consent decision. If the request had `save_consent_enabled: false`, this must also be `false`. > > * `scopes` > > The requested scopes; must be equivalent to or a subset of the `scopes` in the request. > > * `username` > > The authenticated resource owner's identifier. When it receives the response, Advanced Identity Cloud: * Decrypts the JWT. * Verifies the signature. * Verifies the validity of the `aud`, `iss` and `exp` fields. * Processes the response, for example, to save the resource owner's consent. | | | | - | ----------------------------------------------------------------------------------------------------------------- | | | Advanced Identity Cloud rejects compressed response JWTs whose expanded size is larger than 32 KiB (32768 bytes). | ### 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. ![Advanced Identity Cloud sending a consent request JWT to the RCS over a backchannel before redirecting the resource owner.](_images/oauth2-remote-consent-backchannel-flow.svg) #### The consent request During an OAuth 2.0 flow that requires user consent, the backchannel flow proceeds as follows: 1. Advanced Identity Cloud 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, Advanced Identity Cloud 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 Advanced Identity Cloud in a `consent_request_uri` parameter, for example: ```json { "consent_request_uri": "consent-FVaTaZTWuQGZkQX" } ``` This response has a HTTP 201 status code. 4. Advanced Identity Cloud 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. #### The consent response After the RCS gathers the resource owner's consent, it creates a consent response JWT. The RCS encrypts and signs the consent response JWT and returns it to Advanced Identity Cloud. When it receives the response, Advanced Identity Cloud: * Decrypts the JWT. * Verifies the signature. * Verifies the validity of the `aud`, `iss` and `exp` fields. * Processes the response, for example, to save the resource owner's consent. ## Configuration For asymmetric (public key/private key) encryption, Advanced Identity Cloud and the RCS supply their public keys as JSON Web Keys (JWKs). This lets each of them verify signatures and decrypt JWTs. Complete these tasks to configure Advanced Identity Cloud to use an RCS: 1. Add the details of the RCS to an application profile (under Native Consoles > Access Management). Each realm can have a single RCS, configured as a remote consent agent profile. Find more information in [Remote consent agent profile](#proc-oauth2-rcs-agent). 2. Enable remote consent and specify the profile in the OAuth 2.0 provider service for the realm. Find more information in [Use the profile](#proc-oauth2-provider-rcs). 3. Configure the RCS to access the Advanced Identity Cloud `jwk_uri`. ### Remote consent agent profile 1. Under Native Consoles > Access Management, go to Realms > *realm name* > Applications > OAuth 2.0 > Remote Consent and click Add Remote Consent Agent. 2. Set the Agent ID, such as `myRemoteConsentAgent`. 3. If the RCS uses an HMAC algorithm to sign JWTs, set Remote Consent Service secret to the shared symmetric key. 4. Click Create. 5. Configure the profile settings as required and save your work. The remote consent agent profile has the following settings: * Group Configure several remote consent agent profiles by assigning them to a group. Default: Unassigned * 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`. * Redirect URL Redirect the resource owner user-agent here to gather consent. - Pushed Consent Request URL The RCS URL to which Advanced Identity Cloud sends pushed consent requests. Advanced Identity Cloud 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 Advanced Identity Cloud in a `consent_request_uri` parameter as a response to the request. For example: ```json { "consent_request_uri":"consent-FVaTaZTWuQGZkQX" } ``` Advanced Identity Cloud 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. | * Pushed Consent Authentication Method The authentication method, which determines whether to send credentials to the RCS for pushed consent requests. Options are: * `None` (default): Advanced Identity Cloud sends no client credentials with the pushed consent request. * `Basic`: Advanced Identity Cloud 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. | * Enable consent request Encryption Whether to encrypt the consent request JWT. Default: Enabled * Consent request Encryption Algorithm The algorithm to encrypt the consent request JWT: * `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: `RSA-OAEP-256` * Consent request Encryption Method The method to encrypt the consent request JWT: * `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: `A128GCM` * Consent response signing algorithm The [JSON Web Algorithm (JWA)](https://www.rfc-editor.org/rfc/rfc7518.html#section-3.1) to verify a signed consent response JWT: * `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: `RS256` * Consent response encryption algorithm The algorithm to decrypt the consent response JWT: * `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 depends on the algorithm: * For `RSA-OAEP-256`, Advanced Identity Cloud uses the key mapped to the `am.services.oauth2.remote.consent.response.decryption` [secret label](../am-reference/secret-id-mappings.html). * For the other (symmetric encryption) options, Advanced Identity Cloud uses the RCS secret. Default: `RSA-OAEP-256` * Consent Request Signing Algorithm The algorithm to sign the consent request JWT: The signing key depends on the algorithm: * For asymmetric options, Advanced Identity Cloud uses the key mapped to the secret labels shown in the following table: | Secret label | Algorithms | | ------------------------------------------------------------- | ----------------------------------- | | `am.applications.agents.remote.consent.request.signing.ES256` | ES256 | | `am.applications.agents.remote.consent.request.signing.ES384` | ES384 | | `am.applications.agents.remote.consent.request.signing.ES512` | ES512 | | `am.applications.agents.remote.consent.request.signing.RSA` | PS256 PS384 PS512 RS256 RS384 RS512 | * For symmetric options, Advanced Identity Cloud uses the RCS secret. As Advanced Identity Cloud and the remote consent client share the HMAC secret, a malicious actor with the secret could potentially create trusted JWTs. To protect against misuse, Advanced Identity Cloud also signs the JWT with the non-shared signing key mapped to the `am.services.oauth2.jwt.authenticity.signing` secret label. Default: `RS256` * Consent response encryption method The method to decrypt the consent response JWT: * `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: `A128GCM` * Public key selector How the RCS provides its public keys: * `JWKs_URI`: published online * `JWKs`: provided as JWKs Default: `JWKs_URI` * Json Web Key URI The URI for the RCS JWKs. * JWKs URI content cache timeout in ms The duration to cache the JWKs after reading them from the URI. Default: `3600000` (milliseconds) * JWKs URI content cache miss cache time The duration to wait to fetch the JWKs again when a key ID (`kid`) is missing in the cached JWKs. Use this property as a rate limit to prevent denial-of-service attacks against the URI. Advanced Identity Cloud rejects responses requiring unknown key IDs newer than the configured duration. Default: `60000` (milliseconds) * Json Web Key The RCS keys; for 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" }] } ``` * Consent Request Time Limit A consent request JWT expires after this duration. Default: `180` (seconds) - 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. ### Use the profile To use the RCS for *all OAuth 2.0 flows and client applications in the realm*: 1. Under Native Consoles > Access Management, go to Realms > *Realm Name* > Services > OAuth2 Provider and switch to the Consent tab. 2. Select Enable Remote Consent. 3. Select the profile in the Remote Consent Service ID list. 4. If necessary, update the settings for signing and encryption. 5. Save your work. To use the RCS for *a single OAuth 2.0 client application*: 1. Under Native Consoles > Access Management, go to Realms > *Realm Name* > Applications > OAuth 2.0 > Clients > *Client ID* and switch to the OAuth2 Provider Overrides tab. 2. Select Enable OAuth2 Provider Overrides. 3. Select Enable Remote Consent. 4. Select the profile in the Remote Consent Service ID list. 5. Save your work.