UserInfo

The UserInfo feature in Unit4 Identity Services (U4IDS) provides a way to get additional identity information (claims) about a user. This is about requesting against the userinfo endpoint with an access token (defined by OAuth 2.0 specification and inherited by OpenID Connect). It is also about using scopes to request access to claims about user.

UserInfo endpoint

The UserInfo endpoint can be used to retrieve identity information about a subject/user. It requires a valid access token with at least the openid scope, additional scopes will dictate what claims are returned form the endpoint.

UserInfo request example

GET /identity/userinfo
Authorization: Bearer <access_token>
Host: server.example.com
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
   "sub": "248289761001",
   "name": "Bob Smith",
   "given_name": "Bob",
   "family_name": "Smith"
}

Standard claims

The OpenID connect specification defines a set of standard claims. Upon request, they can be returned either in the UserInfo response or in the ID token. U4IDS is configured to return these claims via the UserInfo endpoint. If these standard claims should be returned in the ID token, additional scopes need to be registered with U4IDS.

An overview of standard claims can be found here.

Requesting claims using scope

U4IDS uses scope values to specify what access privileges are being requested for Access Tokens. The scopes associated with Access Tokens determine what resources will be available when they are used to access the UserInfo endpoint. Scopes can be used to request that specific sets of information be made available as claim values. OpenID connect defines the following scope values that are used to request claims:

• profile - This scope value requests access to the End-User's default profile claims, which are:
  • name
  • family_name
  • given_name
  • middle_name
  • nickname
  • preferred_username
  • profile
  • picture
  • website
  • gender
  • birthdate
  • zoneinfo
  • locale
  • updated_at
• email - This scope value requests access to the email and email_verified Claims.
• address - This scope value requests access to the address Claim.
• phone - This scope value requests access to the phone_number and phone_number_verified claims.

The Claims requested by the profile, email, address, and phone scope values are returned from the UserInfo endpoint. If an authorization request is made including one or more of these scopes, the call will be granted access to these claims via the UserInfo endpoint. The associated claims will not be included in the ID token.

Note

U4IDS is by default configured with the profile, email, address and phone scope.

Scope configuration

To get a better understanding on how scopes relate to the UserInfo features, an understanding on how scopes are registered and configured with U4IDS is required. When a scope is registered with U4IDS you have the option to associate claims with tha scope. The default profile scope is shown below:

{
    "Name": "profile",
    "Type": "identity",
    "Claims": [
        { "name": "name" },
        { "name": "family_name" },
        { "name": "given_name" },
        { "name": "middle_name" },
        { "name": "nickname" },
        { "name": "preferred_username" },
        { "name": "profile" },
        { "name": "picture" },
        { "name": "website" },
        { "name": "gender" },
        { "name": "birthdate" },
        { "name": "zoneinfo" },
        { "name": "locale" },
        { "name": "updated_at" }
    ]
}

Note

The profile is by default supported by U4IDS and cannot be maintained using the ADMIN API. The same applies to email, address and phone.

The profile scope defines a set of claims associated with the identity scope. When a request is made to the UserInfo endpoint with an access token that includes the profile scope, U4IDS will resolve the scope values and return them to the caller.

If the profile scope is configured to always include the claims:

{
    "Name": "profile",
    "Type": "identity",
    "Claims": [
        { "name": "name", "AlwaysIncludeInIdToken": "true" },
        { "name": "family_name", "AlwaysIncludeInIdToken": "true" },
        { "name": "given_name", "AlwaysIncludeInIdToken": "true" },
        { "name": "middle_name", "AlwaysIncludeInIdToken": "true" },
        { "name": "nickname", "AlwaysIncludeInIdToken": "true" },
        { "name": "preferred_username", "AlwaysIncludeInIdToken": "true" },
        { "name": "profile", "AlwaysIncludeInIdToken": "true" },
        { "name": "picture", "AlwaysIncludeInIdToken": "true" },
        { "name": "website", "AlwaysIncludeInIdToken": "true" },
        { "name": "gender", "AlwaysIncludeInIdToken": "true" },
        { "name": "birthdate", "AlwaysIncludeInIdToken": "true" },
        { "name": "zoneinfo", "AlwaysIncludeInIdToken": "true" },
        { "name": "locale", "AlwaysIncludeInIdToken": "true" },
        { "name": "updated_at", "AlwaysIncludeInIdToken": "true" }
    ]
}

The ID token will include all profile claims if access to the profile scopes is requested in the authorization request. By default U4IDS is not configured to always include profile claims in the ID token.

ID token only request

If an authorization request is made using the implicit flow and the response type is set to id_token only, U4IDS will return any requested identity scope claims in the ID token. This is because an access token was not requested and thereby the caller would not be able to call the UserInfo endpoint.

Limitations

As U4IDS acts as an gateway to external identity providers using the protocols OpenID Connect, WS-Federation or SAML2.0, there might be restricted support for the standard claims defined by the OpenID Connect specification. U4IDS implementation of the UserInfo concept is based on the assumption that the external identity providers (IdP) can return standard identity claims. If the exernal IdP does not provide these claims, you can still call the UserInfo endpoint but you might get a subset of the requested claims.