The userinfo endpoint is described in the OIDC specification:

Userinfo endpoint

The userInfo endpoint is a protected resource that returns claims about the authenticated end-user. The separation of claims from the userinfo endpoint as an alternative to filling the Access and ID Tokens with claims is an important architectural concept that increases privacy and security. This separation allows the system to better control the flow of information/claims related to an end-user, and what the difference clients can access.

The client makes a request to the userInfo endpoint using an Access Token obtained through OIDC authentication. The Access Token must be sent as a Bearer Token.

The claims are represented by a JSON object that contains a collection of name and value pairs for the claims.

Note that the number of attributes/claims as well as the claim values are dependent on the context, the Security Domain the userinfo service belong to.

Endpoint URL

The userinfo endpoint URL can be found by looking at the value of the "userinfo_endpoint" key in the openid-configuration.

Typical format of the URL is:

Userinfo Endpoint URL - Example format

https://auth.buypass.no/auth/realms/SECURITYDOMAIN/protocol/openid-connect/userinfo

Userinfo Request

The request should be done using HTTP GET and with the Access Token sent using the Authorization header field.

Clients can use 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 and what claims to be returned from the protected endpoints. See Using scope values and "claims" request parameters for details on requesting claims.

Example request using curl

BASEURL="https://auth.buypass.no/auth/realms/SECURITYDOMAIN/protocol/openid-connect";
CLIENT_ID="oidc-client"
CLIENT_SECRET="mysecret"
BASIC_AUTH=`echo -n "${CLIENT_ID}:${CLIENT_SECRET}"| base64`
SCOPE="openid profile email phone"

USERID="someuser"
USERPWD="somepassword"

# Get the tokens using the Resource Owner Password Credentials Grant  
TOKENS_JSON=$(curl \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Basic ${BASIC_AUTH}" \
-X POST "${BASEURL}/token" \
-d "grant_type=password"\
"&username=${USERID}"\
"&password=${USERPWD}"\
"&scope=${SCOPE}" \
2>/dev/null)

# Get the Access Token (using the jq tool)
ACCESS_TOKEN=$(jq -r '.access_token' <<<"${TOKENS_JSON}")

# Get the Userinfo using Access Token
curl -i -w "\n" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-X GET "${BASEURL}/userinfo"

Userinfo Response

The userInfo claims are returned as the members of a JSON object. For privacy reasons, the OpenID Provider may elect to not return values for some requested claims. Another reason can be that the claim requested is not registered on the user or not valid for the domain.

Note that the number of attributes/claims as well as the claim values are dependent on the context, the Security Domain.

Userinfo respons example

{
   "sub": "d6cccb1c-4390-41c1-b956-184ac9213a64",
   "name": "Jane Doe",
   "given_name": "Jane",
   "family_name": "Doe",
   "preferred_username": "j.doe",
   "email": "janedoe@example.com",
   "picture": "http://example.com/janedoe/me.jpg"
}