Userinfo procedures

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.

Common API

UserInfo procedures have access to all of the Common Procedure API.

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.

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.

Common API

Userinfo procedures have access to all of the Common Procedure API.

Function

The result function takes one argument, the context object which provides it with all information and helpers it may require.

The context object has type OpenIdConnectUserinfoTokenProcedureContext.

result(context)

The main function of a transformation procedure

Arguments:
  • context – The context object for transformations.
Returns:

claims to be returned to the client.

Return Value

The procedure must return the claims that it wants to be returned to the client.

These are filtered by Curity based on the scopes of the access token before they are actually returned to the client.

Examples

The trivial procedure

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

Claims filtering

Listing 246 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.
  • Other scopes are looked up for claims that are mapped to the userinfo sink in the claims mapper.