Products » Connect2id server » Documentation » Standard endpoints »

OpenID Connect UserInfo endpoint

1. Retrieving details about the logged-in user

The UserInfo endpoint is an OAuth 2.0 protected resource of the Connect2id server where client applications can retrieve consented claims, or assertions, about the logged in end-user. The claims are typically packaged in a JSON object where the sub member denotes the subject (end-user) identifier. Clients can alternatively be registered to receive the claims in a JWT.

{
  "sub"                                   : "83692",
  "name"                                  : "Alice Adams",
  "email"                                 : "[email protected]",
  "birthdate"                             : "1975-12-31",
  "https://claims.example.com/department" : "engineering"
}

Clients must present a valid access token (of type bearer) to retrieve the UserInfo claims. Only those claims that are scoped by the token will be made available to the client.

The UserInfo endpoint is described in the OpenID Connect Core 1.0 specification.

2. The UserInfo endpoint URL

It is advertised in the userinfo_endpoint server metadata and has this form:

[issuer-url]/userinfo

3. Web API overview

Resources
Representations Errors

4. Resources

4.1 /userinfo

4.1.1 GET

Retrieves the consented OpenID claims about the logged-in subject (end-user). The subject (end-user) must have a present session for the retrieval to proceed, unless the access token has the offline_access scope in which case the presence of a session is not required.

Clients registered for TLS sender-constrained resource access must submit their client X.509 certificate with the HTTP request.

Header parameters:

  • Authorization The access token of type Bearer or DPoP, scoped to retrieve the consented claims for the subject (end-user).

  • [ DPop ] The DPoP proof JWT, for an access token of type DPoP (optional). Note, the JWT must include an ath claim representing the BASE64URL encoded SHA-256 hash of the DPoP access token value.

  • [ Issuer ] The issuer URL when issuer aliases are configured, or the issuer URL for a tenant (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Tenant-ID header.

  • [ Tenant-ID ] The tenant ID (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Issuer header.

Success:

  • Code: 200

  • Content-Type: application/json or application/jwt.

  • Body: {object|jwt} The consented claims, packaged in a JSON object or a JSON Web Token (JWT) (depending the registered client setting).

Errors:

Example request to get the claims for a logged-in user:

GET /userinfo HTTP/1.1
Host: c2id.com
Authorization: Bearer Gp7b5hiURKpWzEXgMJP38EnYimgxlBC1PpS2zGXUqe

Example request with a DPoP access token:

GET /userinfo HTTP/1.1
Host: c2id.com
Authorization: DPoP vaeNge3lee2eeth2baH1la8iishoochuup2eev5Ohsh

Example response returning the consented claims as a JSON object:

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

{
  "sub"         : "83692",
  "name"        : "Alice Adams",
  "given_name"  : "Alice",
  "family_name" : "Adams",
  "email"       : "[email protected]",
  "picture"     : "https://example.com/83692/photo.jpg"
}

Example response returning the consented claims as a signed JWT, which can be verified with the server's public RSA key:

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

eyJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ.eyJzdWIiOiJhbGljZSIsImVtYWlsIjoiYWxpY2VAd29u
ZGVybGFuZC5uZXQiLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwibmFtZSI6IkFsaWNlIEFkYW1zIiwiYXV
kIjoiMDAwMTIzIiwiaXNzIjoiaHR0cDpcL1wvbG9jYWxob3N0OjgwODBcL2MyaWQiLCJmYW1pbHlfbm
FtZSI6IkFkYW1zIiwiaWF0IjoxNDEzOTg1NDAyLCJncm91cHMiOlsiYWRtaW4iLCJhdWRpdCJdfQ.FJ
v9UnxvQxYvlc2F_v657SIyZkjQ382Bc108O--UFh3cvkjxiO5P2sJyvcqfuGrlzgvU7gCKzTIqqrV74
EcHwGb_xyBUPOKuIJGaDKirBdnPbIXMDGpSqmBQes4tc6L8pkhZfRENIlmkP-KphI3wPd4jtko2HXAd
DFVjzK-FPic

Example error response when the subject (end-user) has no present session with the OpenID provider and the submitted access token has no offline_access scope:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope" error_description="Insufficient scope: The end-user is not present (no session)" scope="offline_access"

5. Representations

5.1 Claims

OpenID Connect specifies a set of standard claims about the end-user, which cover common profile information such as name, contact details, date of birth and locale.

The Connect2id server can be set up to provide additional custom claims, for example to represent roles and permissions.

The claims are packed as members in a JSON object and their value can be any JSON entity.

Claims that are considered verified according to the eKYC / Identity Assurance extension will be returned in a dedicated verified_claims container. This is done to separate them from regular claims.

Standard OpenID Connect claims:

  • sub {string} The subject (end-user) identifier. This member is always present in a claims set.
  • [ name ] {string} The full name of the end-user, with optional language tag.
  • [ given_name ] {string} The given or first name of the end-user, with optional language tag.
  • [ family_name ] {string} The surname(s) or last name(s) of the end-user, with optional language tag.
  • [ middle_name ] {string} The middle name of the end-user, with optional language tag.
  • [ nickname ] {string} The casual name of the end-user, with optional language tag.
  • [ preferred_username ] {string} The username by which the end-user wants to be referred to at the client application.
  • [ profile ] {string} The URL of the profile page for the end-user, with optional language tag.
  • [ picture ] {string} The URL of the profile picture for the end-user.
  • [ website ] {string} The URL of the end-user's web page or blog.
  • [ email ] {string} The end-user's preferred email address.
  • [ email_verified ] {true|false} True if the end-user's email address has been verified, else false.
  • [ gender ] {"male"|"female"|?} The end-user's gender.
  • [ birthdate ] {string} The end-user's birthday, represented in ISO 8601:2004 YYYY-MM-DD format. The year may be 0000, indicating that it is omitted. To represent only the year, YYYY format is allowed.
  • [ zoneinfo ] {string} The end-user's time zone, e.g. Europe/Paris or America/Los_Angeles.
  • [ locale ] {string} The end-user's locale, represented as a BCP47 language tag. This is typically an ISO 639-1 Alpha-2 language code in lowercase and an ISO 3166-1 Alpha-2 country code in uppercase, separated by a dash. For example, en-US or fr-CA.
  • [ phone_number ] {string} The end-user's preferred telephone number, typically in E.164 format, for example +1 (425) 555-1212 or +56 (2) 687 2400.
  • [ phone_number_verified ] {true|false} True if the end-user's telephone number has been verified, else false.
  • [ address ] {object} A JSON object describing the end-user's preferred postal address with any of the following members:
    • [ formatted ] {string} The full mailing address, with multiple lines if necessary. Newlines can be represented either as a \r\n or as a \n.
    • [ street_address ] {string} The street address component, which may include house number, stree name, post office box, and other multi-line information. Newlines can be represented either as a \r\n or as a \n.
    • [ 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.
  • [ updated_at ] {number} Time the end-user's information was last updated, as number of seconds since the Unix epoch (1970-01-01T0:0:0Z) as measured in UTC until the date/time.

6. Errors

401 Unauthorized

The request was denied due to an invalid or missing access token. Also used to indicate that the client (registration URI) doesn't exist on the server. The WWW-Authenticate header may be present and include additional error information.

Example:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer

403 Forbidden

The request was denied due to the bearer access token having insufficient privileges. The WWW-Authenticate header may be present and include additional error information.

Example:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope" error_description="Bearer access token has insufficient privileges"

500 Internal Server Error

An internal server error has occurred. Check the Connect2id server logs for details.

Example:

HTTP/1.1 500 Internal Server Error