OAuth Metadata

During the OAuth Single-Sign On (SSO) authentication flow, Digital.ai App Management receives an OAuth access token from the Authorization Server. It uses that token to send an access request to the Resource Server, and the Resource Server validates the token and returns information about the user.

This page identifies user attributes that are required and optional during authentication, and shows an example API response from the Resource Server.

User Attributes

Required Attributes

When the Resource Server responds to an access request, its API response needs to include an email and/or userid attribute. Digital.ai App Management uses one or both of these attributes to match the identity with an existing user, or to provision a new user if one does not already exist. If the user information includes email but no userid attribute and the user does not yet exist, Digital.ai App Management will auto-provision a user that specifies the value of email for both userid and email.

The userid attribute must be 200 characters or less, and cannot include spaces. Valid characters include:

• a-z
• A-Z
• 0-9
• /~!$%^&*_=+.@,

Both email and userid must be unique within your organization. If you provide a value for either that is not unique, the SSO login will fail.

Optional Attributes

Digital.ai App Management will also use the following optional attributes if they are included in the API response:

• lastname
• firstname
• groups

The groups attribute can be used to manage the user's group membership (add and remove the user from groups in Digital.ai App Management). Digital.ai App Management will ignore the groups attribute, however, unless your organization is enabled for SSO Group Matching. To enable Group Matching, contact Customer Support. For more information, see Group Assignment During SSO.

Example Authentication API Response

The following example shows the API response to an access request sent from a Ping Identity OAuth resource server. In the groups attribute, the CN (Common Name) portion of the directory information is the name used to match groups in Digital.ai App Management.

(
  'access_token' =>
  array (
    'firstname' => 'Sally',
    'groups' =>
    array (
      0 => 'CN=Engineering,OU=Security Groups,OU=Example,DC=example,DC=cxm',
      1 => 'CN=Testing,OU=Security Groups,OU=Example,DC=example,DC=cxm',
    ),
    'userid' => 'sjones',
    'email' => 'sjones@example.com',
    'lastname' => 'Jones',
  ),
  'scope' => 'test_scope',
  'token_type' => 'urn:pingidentity.com:oauth2:validated_token',
  'expires_in' => 7199,
  'client_id' => 'oauth2_test',
)