PingOne Advanced Identity Cloud

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.

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 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 on the remote consent agent to enable this option.

The front channel flow is the default. It’s used when the Pushed Consent Request URL is not configured on the remote consent agent.

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.

    Example request body 
    {
  "aud": "rcs",
  "claims": {},
  "clientId": "myClient",
  "client_description": "<optional-description>",
  "client_name": "My Client",
  "consentApprovalRedirectUri": "https://<tenant-env-fqdn>/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://<tenant-env-fqdn>/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.

    Find more information in 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.

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.

Example response body 
{
  "consent_response" : {
      "aud": "https://<tenant-env-fqdn>/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": "<optional-description>",
      "client_name": "My Client",
      "consentApprovalRedirectUri": "https://<tenant-env-fqdn>/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>",
      "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:

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

  • 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).

The backchannel flow applies when a 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.

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.

  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:

    {
    "consent_request_uri": "consent-FVaTaZTWuQGZkQX"
}

    This response has an 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.

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.

Find information on configuring this flow in Use backchannel pushed consent requests.

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.

  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.

  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.

Metadata URL

The URL from which the authorization server retrieves the RCS’s metadata.

This URL must return an HTTP 200 status code and a JSON array of supported authorization detail types in the metadata parameter authorization_details_types_supported. For example:

{
   "authorization_details_types_supported":[
      "payment_initiation",
      "account_information"
   ]
}
The RCS must ensure that the returned authorization_details_types_supported array accurately reflects the authorization detail types it supports.
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) 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.

  • 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:

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

The following use cases build on the Front channel.

Advanced Identity Cloud can send additional runtime context to the RCS from the resource owner’s session to render a better consent experience or apply consent policy. This additional runtime context can include the Advanced Identity Cloud tenant URL, organization, risk level, or authentication context.

You might want to send additional runtime context if you need to do any of the following:

  • Provide the RCS with additional context about the current user’s session.

  • Customize consent screens for different organizations, brands, or user populations.

  • Let the RCS make consent decisions without making extra runtime calls back to Advanced Identity Cloud.

  • Reduce custom integration work by having Advanced Identity Cloud send a selected set of session values automatically.

  • Keep consent decisions aligned with the session that was used for authentication.

This capability is especially useful when the consent experience depends on information that already exists in the session, but is not otherwise present in scopes, claims, or authorization_details.

How it works

When Advanced Identity Cloud determines that remote consent is required, it builds a consent_request JWT for the RCS. If you configure Resource Owner Session Properties on the remote consent agent, Advanced Identity Cloud reads the configured session property mappings, looks up matching values in the authenticated user’s session, and includes them in the resourceOwnerSessionProperties claim of the consent_request. Only properties that exist in the current session are included. If none of the configured properties are present, Advanced Identity Cloud omits the claim.

Configure sending session context to the RCS

  1. Make sure the relevant session properties are available in the authenticated user’s session.

    If you use custom session properties, you must expose them at runtime. To do this, configure the session property allowlist and specify any properties to be included in a query response.

    1. Under Native Consoles > Access Management, go to Realms > realm name > Services, and click Add a Service.

    2. Select Session Property Whitelist Service and click Create.

    3. In the Allowlisted Session Property Names, enter the session properties you want to obtain.

    4. Click Save Changes.

  2. In the remote consent agent configuration, add entries to the Resource Owner Session Properties field.

    Each entry maps a session property name (key) to the claim name used in the consent_request JWT (value).

    Example mapping
    Session property in Advanced Identity Cloud Claim name in consent_request

    tenant

    tenant

    authLevel

    authentication_level

    brand

    brand

  3. Save your changes.

Advanced Identity Cloud now includes the configured session properties in the resourceOwnerSessionProperties claim when it builds the consent request. For example:

{
  "resourceOwnerSessionProperties": {
    "tenant": "alpha",
    "authentication_level": "2",
    "brand": "banking"
  }
}

The RCS can read these values from the incoming consent_request to tailor the consent experience, for example, by selecting the correct branding, displaying organization-specific text, or applying consent policy based on session context.

Use data minimization. Configure only the session properties the RCS actually needs. Avoid exposing sensitive session data unless it’s required for the consent use case.

If the authorization request includes rich or verbose data, such as detailed authorization_details, many requested claims, or extensive scope metadata, the consent_request sent to the RCS can become too large for a browser redirect.

You might also want to reduce the amount of consent data exposed through the front channel.

With backchannel pushed consent requests, instead of passing the full consent request JWT to the resource owner’s browser, Advanced Identity Cloud sends it directly to the RCS over a server-to-server HTTP POST before redirecting the resource owner. The RCS stores the request and returns an opaque consent_request_uri. Advanced Identity Cloud then redirects the resource owner to the RCS with only this token.

  1. Make sure your RCS exposes a backchannel endpoint that does the following:

    • Accepts an HTTP POST with a JSON body containing consent_request.

    • Validates the incoming JWT.

    • Returns 201 Created with a JSON body containing consent_request_uri.

    Example pushed consent request
    POST /pcr
Content-Type: application/json
Authorization: Basic credentials

{
  "consent_request": "jwt"
}
    Example successful response
    {
  "consent_request_uri": "consent-FVaTaZTWuQGZkQX"
}

    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.

  2. In the remote consent agent configuration:

    1. Set the Pushed Consent Request URL to the backchannel endpoint on the RCS.

    2. Set the Pushed Consent Authentication Method to the authentication method required by your RCS endpoint.

      If you select Basic, make sure the Pushed Consent Request URL uses HTTPS.

  3. Save your changes.

Advanced Identity Cloud now sends the consent request JWT directly to the RCS before redirecting the resource owner. The resource owner’s browser receives only the opaque consent_request_uri. For example:

https://rcs.example.com/consent?consent_request_uri=consent-FVaTaZTWuQGZkQX