OpenID Connect Scopes and Claims

Scopes and claims represent the user information that a Hosted Login client requests from a server. For our purposes, each claim is equivalent to one piece of user information: the user’s first name is a claim, the user’s middle name is a claim, and the user’s last name is a claim. (And, of course, the user’s full name – Karim J. Nafir – is yet another claim.) As we’ll see in the section Mapping Hosted Login Claims to User Profile Attributes, each claim typically maps to a single user profile attribute.

Note. We say “typically” because, well, that’s typically what we mean when we use the word “claim.” Technically, however, pretty much any name/value pair in OpenID Connect (OIDC) is referred to as a claim. Because of that, there will be times when you’ll see the word claim even though we’re obviously not talking about user information. For example, the iss claim in an access token is the URL of your authorization endpoint, something not directly associated with user information.

Scopes, in turn, are nothing more than collections of claims: scopes a provide a shortcut method for returning multiple pieces of user information. For example, instead of returning three separate claims – first name, middle name, and last name – you might have a single scope (e.g., userNames) that returns all three names.

OIDC defines several standard scopes, all of which are supported by Hosted Login (albeit with some slight variations here and there):

  • openid. Identifies your request as an OIDC request. This scope must be included in all your authentication requests.
     
  • profile. Requests access to the following attributes (note that these are OIDC attribute names and not Akamai Identity Cloud attribute names): 
    • name
    • family_name
    • given_name
    • middle_name
    • nickname
    • preferred_username
    • gender
    • birthdate
    • updated_at
       
  • email. Requests access to the following attributes:
    • email
      email_verified 

       
  • address. Requests access to the user's mailing address.
     
  • phone. Requests access to the following attributes:
    • phone_number
    • phone_number_verified

Note that you can include multiple scopes in your API calls simply by separating the scopes with a blank space. For example, this call requests three scopes:

scope=openid email phone

Supported scopes and supported claims are both included in your discovery document. Keep in mind, however, that scopes and claims do not represent the only information you can retrieve for a user; instead, they simply represent the information automatically made available when you carry out a specific action. For example, if your login policy includes only the default openid scope and the email scope, then any time you log on you’ll get back the user’s email address and little beyond that. But what if you also need the user’s phone number? That’s fine: you can either add that scope to your login policy, or just make another API call to get retrieve that information.

Custom Claims

At this point in time Hosted Login does not support the use of custom scopes; instead, you’re limited to the predefined scopes (openidprofileemailaddress, and phone). However, you can create as many custom claims as you might need. For example, suppose you have created three custom attributes in your user profile schema:

  • email_marketing_optIn
  • ui_preferences_optIn
  • personalized_ads_optIn

Let’s further suppose that you’d like to make these attributes available any time a user logs on. To do that, all you have to do is add a customClaims section to your login policy. For example:

{
  "customClaims":
    {"id_token": 
      {
        "consent_email_marketing": "email_marketing_optIn",
        "consent_ui_preferences": "ui_preferences_optIn",
        "consent_personalized_ads": "personalized_ads_optIn"
      }
    }
}

Note. For now, you will need to work with your Akamai representative to modify your login policies.

When creating custom claims, these claims must be added either to the identity token (id_token) or to the user profile information that can be retrieved from the userinfo endpoint. As the name implies, id_token claims are attached to the identity token and can be retrieved directly from that token. By comparison, to return userinfo claims you must contact and retrieve the information from the userinfo endpoint.

Each custom claim must also include a unique name mapped to a single user profile attribute. For example, this syntax maps the claim consent_email_marketing to the user attribute email_marketing_optIn:

"consent_email_marketing": "email_marketing_optIn"

Note that the custom claim names simply have to be unique; otherwise there are no special restrictions. For example, we could just as easily map consent_email_marketing to a claim named marketing:

"marketing": "email_marketing_optIn"

Or even to a claim named x:

"x": "email_marketing_optIn"

However, your attribute names (as opposed to your claim names) can’t be arbitrary: you must use the exact name and the exact letter casing employed in your user profile schema. For example, this syntax, which uses all uppercase letters for the attribute name, will fail:

 "consent_email_marketing": "EMAIL_MARKETING_OPTIN"

You can create as many custom claims as you need, but you cannot collect those claims into a custom scope. To return the consent attributes used in this example, you must request each claim separately; you cannot create a custom scope (e.g., consents) and request all those claims in a single operation. Contact your Akamai representative for more information.

Mapping Hosted Login Claims to User Profile Attributes

By default, Hosted Login supports 16 claims, most of which map directly to an Identity Cloud user profile attribute. These claims are summarized in the following table:

Claim

Scope

Datatype

User Profile Attribute

sub

Subject. Unique identifier for the end user. This will always be the user’s Identity Cloud UUID.

openid

string

uuid

iss

Issuer Identifier. URL of your login server. For example: 

https://v1.api.us.janrain.com/00000000-0000-3000-8000-000000000000/login

openid

string

--

auth_time

Authentication time. Indicates the last time that the user was authenticated. The auth_time claim is formatted using Unix epoch time, which represents the number of seconds that have elapsed since 00:00:00 Coordinated Universal Time (UTC) on January 1, 1970 For example, the value 1553405263 represents Saturday, March 23, 2019 at 22:27:43 Pacific Daylight Time.

openid

number

lastLogon

name
 

User’s full name, including titles and suffixes, ordered according to the user’s locale and preferences. For example: Dr. Toni Ng.

profile

string

--

given_name

Given name (first name) of the user. 

profile

string

givenName

family_name

Surname (last name) of the user. 

profile

string

familyName

middle_name

Middle name of the user. 

profile

string

middleName

preferred_username

Name by which the user wishes to be referred, such as Karim NafirK. Nafir or karim_n

profile

string

displayName

gender

User’s gender. 

profile

string

gender

birthdate

The user’s birthday, represented in ISO8601‑2004 format (e.g., 1967-07-12, or YYYY-MM-DD). If the year is set to 0000 (0000-07-12) that indicates that the user chose to enter the month and day, but not the year, of their birth.

profile

string

birthday

updated_at

Indicates the last time that the user profile was updated. The updated_at claim is formatted using Unix epoch time, which represents the number of seconds that have elapsed since 00:00:00 Coordinated Universal Time (UTC) on January 1, 1970 For example, the value 1553405263 represents Saturday, March 23, 2019 at 22:27:43 Pacific Daylight Time.

profile

number

lastUpdated

address

User’s preferred mailing address. The JSON format for the address claim looks like this:

{
  "address": {
    "country": "country",
    "formatted": "address1 address2\ncity, zip\ncountry",
    "locality": "city",
    "postal_code": "zip",
    "region": "",
    "street_address": "address1 address2"
    }
}

In the preceding JSON value, the \n indicates a line break.

address

string

Derived from primaryAddress

phone_number

User’s preferred cell phone (mobile) number. I

phone

string

mobileNumber

phone_number_verified

Set to true if the user’s phone number has been verified. When this value is true, it means that steps were taken steps to ensure that the phone number was controlled by the user at the time the verification was performed.

phone

boolean

Derived from mobileNumberVerified

email

User’s preferred email address. 

email

string

email

email_verified

Set to true if the user’s email address has been verified. When this value is true, it means that steps were taken steps to ensure that the email address was controlled by the user at the time the verification was performed. This is typically done by having the user respond to a “Verify Email Address” email.

email

boolean

Derived from emailVerified