Developer Resources

The UserInfo Endpoint

The OpenID Connect UserInfo endpoint is used by an application to retrieve profile information about the Identity that authenticated. Applications can use this endpoint to retrieve profile information, preferences and other user-specific information.

The OpenID Connect profile consists of two components:

  • Claims describing the end-user

  • UserInfo endpoint providing a mechanism to retrieve these claims

The user claims can also be presented inside the id_token to eliminate a call back during authentication time.

User Profile Claims

The UserInfo endpoint will present a set of claims based on the OAuth2 scopes presented in the authentication request.

OpenID Connect defines five scope values that map to a specific set of default claims. PingFederate allows you to extend the "profile" scope via the "OpenID Connect Policy Management" section of the administration console. Multiple policy sets can be created and associated on a per-client basis.

Connect scope Returned Claims

openid

None - Indicates this is an OpenID Connect request

profile

name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, updated_at, *custom attributes

address

address

email

email, email_verified

phone

phone_number, phone_number_verified

  • If a scope is omitted (i.e. the "email" scope is not present), the claim "email" will not be present in the returned claims. For custom profile attributes, prefix the value to avoid clashing with the default claim names.

  • If an OpenID Connect id_token is requested without an OAuth2 access token (i.e. when using the implicit "response_type = id_token" request), the claims will be returned in the id_token rather than the UserInfo endpoint.

Sample UserInfo Endpoint Request

Once the client application has authenticated a user and is in possession of an access token, the client can then make a request to the UserInfo endpoint to retrieve the requested attributes about a user. The request will include the access token presented using a method described in RFC6750.

The UserInfo endpoint provided by PingFederate is located at: https://<pingfederate_base_url>/idp/userinfo.openidNOTE: The UserInfo endpoint can also be determined by querying the OpenID Connect configuration information endpoint: https://<pingfederate_base_url>/.well-known/openid-configuration.

An example HTTP client request to the UserInfo endpoint:

GET https://pf.company.com:9031/idp/userinfo.openid HTTP/1.1

Authorization: Bearer

A successful response will return a HTTP 200 OK response and the users claims in JSON format:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "sub":"mpavlich",
  "family_name":"Pavlich",
  "given_name":"Matthew",
  "nickname":"Pav",
  ...[additional claims]...
}

Before the client application can trust the values returned from the UserInfo endpoint (i.e. as a check for token substitution attack), the client must verify that the "sub" claim returned from the UserInfo endpoint request matches the subject from the id_token.