PingOne Advanced Identity Cloud

Remote consent service

PingOne Advanced Identity Cloud supports OAuth 2.0 remote consent services. A remote consent service gathers resource owner consent separately from an authorization server such as PingOne Advanced Identity Cloud.

The remote consent service displays a consent page, gathers the result, signs and encrypts the result, and returns it to the authorization server.

For an OAuth 2.0 flow requiring user consent, PingOne 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>",
  "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 remote consent service.

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 remote consent service 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.

PingOne 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 remote consent service 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.

Acting as the authorization server, PingOne Advanced Identity Cloud signs and encrypts the JWT.

When it receives the request, the remote consent service:

  • Decrypts the JWT.

  • Verifies the signature.

  • Verifies the validity of the aud, iss and exp fields.

  • Renders the consent page to present to the resource owner.

After the remote consent service gathers the resource owner’s consent, it creates a consent response JWT. The remote consent service encrypts and signs the consent response JWT and returns it to PingOne 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, PingOne 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.

PingOne 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, PingOne Advanced Identity Cloud and the remote consent service supply their public keys as JSON Web Keys (JWKs). This lets each of them verify signatures and decrypt JWTs.

Complete these tasks to configure PingOne Advanced Identity Cloud to use a remote consent service:

  1. Add the details of the remote consent service to an application profile (under Native Consoles > Access Management).

    Each realm can have a single remote consent service, configured as a remote consent agent profile.

    For details, refer to Remote consent agent profile.

  2. Enable remote consent and specify the profile in the OAuth 2.0 provider service for the realm.

    For details, refer to Use the profile.

  3. Configure the remote consent service to access the PingOne 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 remote consent service 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 PingOne Advanced Identity Cloud.

Redirect URL

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

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, PingOne Advanced Identity Cloud uses the key mapped to the am.services.oauth2.remote.consent.response.decryption secret label.

  • For the other (symmetric encryption) options, PingOne Advanced Identity Cloud uses the remote consent service 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, PingOne 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, PingOne Advanced Identity Cloud uses the remote consent service secret.

    As PingOne 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, PingOne 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 remote consent service provides its public keys:

  • JWKs_URI: published online

  • JWKs: provided as JWKs

Default: JWKs_URI

Json Web Key URI

The URI for the remote consent service 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. PingOne Advanced Identity Cloud rejects responses requiring unknown key IDs newer than the configured duration.

Default: 60000 (milliseconds)

Json Web Key

The remote consent service 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)

Use the profile

To use the remote consent service 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 remote consent service 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.