Rate this page

Consent Flow

Schema URN
urn:pingidentity:scim:api:messages:2.0:ConsentApprovalResponse

By default, the Data Governance Broker’s policies require that the end user explicitly grant approval for any scopes requested by an OAuth 2 client. When this consent is required, the Auth API will direct the auth UI to the Consent flow, generally as the last step before the authentication process completes.

Field Type Provided? Description
schemas array always The SCIM schema of the consent flow. Always has the value urn:pingidentity:scim:api:messages:2.0:ConsentApprovalResponse.
meta complex always Will always contain a resourceType sub-attribute with the value approve. Will always contain a location sub-attribute with the current flow URI.
followUp complex always An object indicating the authorization endpoint URI to be retrieved when this flow is complete. Will always contain a type sub-attribute and a $ref sub-attribute; the latter is the URI to be retrieved.
sessionIdentityResource complex If an end user is already logged in, the sub-attributes of this object are attribute values of the user that may be displayed by the auth UI. Examples might include the end user’s username, full name, or icon. The attributes included here are determined by the Session Resource Attribute property of the Broker’s Authentication Service configuration.
client complex always Describes the OAuth 2 client that initiated the current authentication process. Will always contain the name sub-attribute, which is the display name of the client. Will contain a description sub-attribute for the client if one is available.
scopes array always An array of scope objects, described in the table below.
optionalScopes array An array of the names of optional scopes for which the end user wishes to grant consent.
approved boolean always A flag indicating whether or not the end user has approved the scope request. The auth UI is expected to set this to true to indicate the user’s consent.

Fields of a scope object:

Field Type Provided? Description
name string always The scope name, as used by OAuth 2 clients. This is not typically presented to the end user.
description string A description of the scope. As opposed to the consentPromptText field, this may or may not be written with the end user as an audience.
consentPromptText string always A description of the scope intended to be read by an end user. This text (or a localization of it) should be presented to the end user.
granted boolean always A flag indicating whether the user has granted consent to the scope. An auth UI may choose to not display scopes that have already been approved.
optional boolean always A flag indicating whether or not the scope is required for the authorization request as a whole to succeed.

The following is an example of a consent flow message:

{
  "schemas": [
    "urn:pingidentity:scim:api:messages:2.0:ConsentApprovalResponse"
  ],
  "meta": {
    "resourceType": "approve",
    "location": "https://example.com/authentication/approve/ARH5F9B..."
  },
  "followUp": {
    "type": "authorize",
    "$ref": "https://example.com/oauth/authorize/ARH5F9B..."
  },
  "sessionIdentityResource": {
    "name.formatted": "Horselover Fat",
    "userName": "horselover.fat"
  },
  "client": {
    "name": "Example OAuth2 Client",
    "description": "This is the external application that initiated the authentication process."
  },
  "scopes": [
    {
      "name": "address",
      "description": "OpenID Connect address scope",
      "consentPromptText": "View your postal address.",
      "granted": false,
      "optional": true
    },
    {
      "name": "phone",
      "description": "OpenID Connect phone scope",
      "consentPromptText": "View your phone number.",
      "granted": false,
      "optional": true
    },
    {
      "name": "openid",
      "description": "OpenID Connect required scope.",
      "consentPromptText": "Manage your OpenID Connect data.",
      "granted": false,
      "optional": false
    },
    {
      "name": "profile",
      "description": "OpenID Connect profile scope",
      "consentPromptText": "View your profile data.",
      "granted": false,
      "optional": true
    },
    {
      "name": "email",
      "description": "OpenID Connect email scope",
      "consentPromptText": "View your email address.",
      "granted": false,
      "optional": false
    }
  ],
  "approved": false
}

Scope approval

To approve a set of scopes, the auth UI simply sets the approved flag to true and performs a PUT. Unlike other flows, the consent flow does not provide a success flag to indicate that the approval submitted by the auth UI succeeded. After submitting approval, the auth UI should simply move on by requesting the followup URI using GET.

{
  "schemas": [
    "urn:pingidentity:scim:api:messages:2.0:ConsentApprovalResponse"
  ],
  "meta": {
    "resourceType": "approve",
    "location": "https://example.com/authentication/approve/ARH5F9B..."
  },
  "followUp": {
    "type": "authorize",
    "$ref": "https://example.com/oauth/authorize/ARH5F9B..."
  },
  "sessionIdentityResource": {
    "name.formatted": "Horselover Fat",
    "userName": "horselover.fat"
  },
  "client": {
    "name": "Example OAuth2 Client",
    "description": "This is the external application that initiated the authentication process."
  },
  "scopes": [
    {
      "name": "address",
      "description": "OpenID Connect address scope",
      "consentPromptText": "View your postal address.",
      "granted": false,
      "optional": false
    },
    {
      "name": "phone",
      "description": "OpenID Connect phone scope",
      "consentPromptText": "View your phone number.",
      "granted": false,
      "optional": false
    },
    {
      "name": "openid",
      "description": "OpenID Connect required scope.",
      "consentPromptText": "Manage your OpenID Connect data.",
      "granted": false,
      "optional": false
    },
    {
      "name": "profile",
      "description": "OpenID Connect profile scope",
      "consentPromptText": "View your profile data.",
      "granted": false,
      "optional": false
    },
    {
      "name": "email",
      "description": "OpenID Connect email scope",
      "consentPromptText": "View your email address.",
      "granted": false,
      "optional": false
    }
  ],
  "approved": true
}

Approve optional scopes

If a consent request contains optional scopes, then setting the approved flag to true without making any other changes will approve only the required scopes (i.e., the scopes that are not marked as optional).

To approve optional scopes, the auth UI must also provide an array containing the names of the optional scopes to be approved.

{
  "schemas": [
    "urn:pingidentity:scim:api:messages:2.0:ConsentApprovalResponse"
  ],
  "meta": {
    "resourceType": "approve",
    "location": "https://example.com/authentication/approve/ARH5F9B..."
  },
  "followUp": {
    "type": "authorize",
    "$ref": "https://example.com/oauth/authorize/ARH5F9B..."
  },
  "sessionIdentityResource": {
    "name.formatted": "Horselover Fat",
    "userName": "horselover.fat"
  },
  "client": {
    "name": "Example OAuth2 Client",
    "description": "This is the external application that initiated the authentication process."
  },
  "scopes": [
    {
      "name": "address",
      "description": "OpenID Connect address scope",
      "consentPromptText": "View your postal address.",
      "granted": false,
      "optional": true
    },
    {
      "name": "phone",
      "description": "OpenID Connect phone scope",
      "consentPromptText": "View your phone number.",
      "granted": false,
      "optional": true
    },
    {
      "name": "openid",
      "description": "OpenID Connect required scope.",
      "consentPromptText": "Manage your OpenID Connect data.",
      "granted": false,
      "optional": false
    },
    {
      "name": "profile",
      "description": "OpenID Connect profile scope",
      "consentPromptText": "View your profile data.",
      "granted": false,
      "optional": true
    },
    {
      "name": "email",
      "description": "OpenID Connect email scope",
      "consentPromptText": "View your email address.",
      "granted": false,
      "optional": false
    }
  ],
  "approved": true,
  "optionalScopes": [
    "profile", "phone"
  ]
}

In the above example, all of the scopes will be approved except for the ‘address’ scope, because it is marked as optional but is not included in the optionalScopes array.