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.

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/authorize?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,
  "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.

    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.

    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",
      "claims": {},
      "clientId": "myClient",
      "client_description": "<optional-description>",
      "client_name": "My Client",
      "consentApprovalRedirectUri": "https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/authorize?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.

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

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.