Token procedures - Userinfo

An OpenID Connect UserInfo procedure returns a set of Claims about a user authenticated by a given access token.

The openid scope is required to access endpoints of this type. The claims returned to the requesting client depend on the scope of the access token.

Claims

OpenID Connect defines a set of Standard Claims returned by the UserInfo endpoint:

Claim Type Scope Description
sub string   Subject - Identifier for the End-User at the Issuer.
name string profile End-User’s full name in displayable form.
given_name string profile Given name(s) or first name(s) of the End-User.
family_name string profile Surname(s) or last name(s) of the End-User.
middle_name string profile Middle name(s) of the End-User.
nickname string profile Casual name of the End-User.
preferred_username string profile Shorthand name by which the End-User wishes to be referred to at the RP.
profile string profile URL of the End-User’s profile page.
picture string profile URL of the End-User’s profile picture.
website string profile URL of the End-User’s Web page or blog.
gender string profile End-User’s gender.
birthdate string profile End-User’s birthday, represented as in ISO 8601:2004 YYYY-MM-DD format.
zoneinfo string profile The End-User’s time zone.
locale string profile End-User’s locale, represented as a BCP47. language tag.
updated_at number profile Time (seconds since epoch) the End-User’s information was last updated.
email string email End-User’s preferred (RFC 5322 conformant) e-mail address.
email_verified boolean email True if the End-User’s e-mail address has been verified; otherwise false.
phone_number string phone End-User’s preferred telephone number.
phone_number_verified boolean phone True if the End-User’s phone number has been verified; otherwise false.
address JSON object address End-User’s preferred postal address (see below).

Attributes of the address claim:

Name Type Description
formatted string Full mailing address.
street_address string Full street address component.
locality string City or locality component.
region string State, province, prefecture, or region component.
postal_code string Zip code or postal code component.
country string Country name component.

For a more detailed description of each claim, please consult Section 5. of the OpenID Connect Core specification.

The returned claims are filtered based on the scopes of the access token before they are passed to the requesting client. The sub claim is not covered by a scope and is always returned.

Claims returned by a procedure that are unknown (i.e. not mentioned in the above tables) are filtered out, and not passed to the requesting client. This default behavior can be overridden by setting the passthrough-unscoped-claims flag to true on the openid configuration; which will allow unknown claims not covered by a scope to be passed to the client. Known claims covered by a scope returned by the procedure are always filtered, regardless of this setting.

A note on the email_verified and phone_number_verified claims. These are currently mapped to true only if the type attribute on the e-mail address in the account attributes is set to “verified”. This is currently not set automatically by the system (for example when registering through the e-mail authenticator) but is planned for a future release.

Examples

The trivial procedure

Listing 288 A procedure returning the default set of claims
1
2
3
4
function result(context) {
  var responseData = context.getDefaultResponseData();
  return responseData;
}

Claims filtering

Listing 289 A procedure returning claims mapped from the authenticated user´s account
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
function result(context) {

  var defaultData = context.getDefaultResponseData();

  var responseData = {
    sub: defaultData.sub,
    preferred_username: context.accountAttributes.userName,
    zoneinfo: context.accountAttributes.timezone,
    email: getPrimarySignificantValue(context.accountAttributes.emails),
    phone_number: getPrimarySignificantValue(context.accountAttributes.phoneNumbers),
    extra: 'bonus'
  };
  return responseData;
}

function getPrimarySignificantValue(multivalued) {
  var primary = null;
  if (multivalued && multivalued.length > 0) {
    multivalued.forEach(function(element) {
      if (primary == null || !!element.primary) {
        primary = (typeof element === 'object' ? element.value : element);
      }
    });
  }
  return primary;
}

The claims returned by the procedure are filtered based on the scope of the access token before sent to the requesting client:

  • Scope openid gives the claims: sub
  • Scope openid profile gives the claims: sub, name, given_name, family_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, updated_at.
  • Scope openid email gives the claims: sub, email, email_verified.
  • Scope openid phone gives the claims: sub, phone_number, phone_number_verified.
  • Scope openid profile phone gives the claims: sub, name, given_name, family_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, updated_at, phone_number, phone_number_verified.

Notice that the sub claim is always returned, and the extra claim is never returned. If the configuration flag passthrough-unscoped-claims is set to true, the extra claim would always be returned, regardless of the scope of the access token.