Skip to content
Connect2id

UserInfo

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 may alternatively be registered to receive the claims in a JWT.

{
  "sub"        : "83692",
  "name"       : "Alice Adams",
  "email"      : "alice@example.com",
  "department" : "Engineering",
  "birthdate"  : "1975-12-31"
}

The UserInfo URL can be obtained from the server discovery endpoint and looks like this:

https://[base-server-url]/userinfo

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. Web API overview

Resources
Representations Errors

3. Resources

3.1 /userinfo

3.1.1 GET

Retrieves the consented UserInfo and other claims about the logged-in subject (end-user).

Header parameters:

  • Authorization The bearer access token, scoped to retrieve the consented claims for the subject (end-user).

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 response returning the consented claims as a JSON object:

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

{
 "sub"         : "248289761001",
 "name"        : "Jane Doe"
 "given_name"  : "Jane",
 "family_name" : "Doe",
 "email"       : "janedoe@example.com",
 "picture"     : "http://example.com/janedoe/me.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

4. Representations

4.1 Claims

OpenID Connect specifies a set of standard claims about the end-user, which encompass typical information such as name, contact details, date of birth and locale. The Connect2id server can be set up to provide additional custom claims, such as organisational attributes.

The claims are packed as members in a JSON object, and may be nested.

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.

5. Errors

401 Unauthorized

The request was denied due to an invalid or missing bearer access token. Also used to indicate that the client (registration URI) doesn’t exist on the server.

Example:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer

403 Forbidden

The request was denied due to the bearer access token having insufficient privileges.

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