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

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.

  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 HMAC shared symmetric key and optional password for the service to authenticate to Advanced Identity Cloud.

Redirect URL

Redirect the resource owner user-agent here to gather consent.

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.