Invoking the UserInfo Endpoint for OpenID Connect
The UserInfo endpoint returns claims about a user that is authenticated with OpenID Connect authentication.
About this task
To obtain the claims for a user, a client makes a request to the UserInfo endpoint by using an access token as the credential. The access token must be one that was obtained through OpenID Connect authentication. The claims for the user who is represented by the access token are returned as a JSON object that contains a collection of name-value pairs for the claims. The UserInfo endpoint is an OAuth 2.0 protected resource, which means that the credential required to access the endpoint is the access token.
The claims that are returned by the UserInfo endpoint can be customized with the OpenID Connect Provider configuration, see Configuring claims returned by the UserInfo endpoint.
https://server.example.com:443/oidc/endpoint/<provider_name>/userinfo
If you must use a proxy to access the OpenID Connect Provider (OP), the value that you enter for any OP-related URL property must contain the proxy host and port, not the external OP host and port.
In most cases, you can replace the OP host and port with the proxy host and port. The URL that you enter must be visible to both the RP and client (browser or application). For further guidance on how to determine the correct URL to use, contact your proxy administrator.
In this example, the client expects the SSL port to be set to 443.
Procedure
-
Set up authentication with an access token that was obtained through OpenID Connect
authentication. The access token can be provided in the HTTP Basic Authorization header or with the
access_token
request parameter. In either case, the access token does not need to be encoded. -
Send the
GET
orPOST
request to the UserInfo endpoint URL.
Results
For valid requests, the UserInfo endpoint
returns an HTTP 200
response with a JSON object in
application/json
format that includes the claims that are configured for the OpenID
Connect Provider.
Example
The following examples illustrate requests with a valid token and invalid tokens.
- Request that uses the HTTP Bearer Authorization header to pass the access token
- Response for a valid access token
- Invalid access tokens
POST /register HTTP/1.1
Accept: application/x-www-form-urlencoded
Authorization: Bearer fAAdLO1c6QWDbPs9HrWHz5e7nRWVAnxqTTP7i88G
access_token
request
parameter: POST /register HTTP/1.1
Accept: application/x-www-form-urlencoded
access_token=fAAdLO1c6QWDbPs9HrWHz5e7nRWVAnxqTTP7i88G
It is a best practice to use the HTTP Authorization header instead of the
access_token
request parameter because HTTP request parameters, which can include
sensitive information, can be saved in the browser history or cache.
sub
and
groupIds
claims are always returned. The other claims that are shown here are the
default claims for an OpenID Connect Provider. HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
"sub" : "bob",
"groupIds" : [ "bobsdepartment","administrators" ],
"given_name" : "Bob",
"name" : "Bob Smith",
"email" : "bob@mycompany.com",
"phone_number" : "+1 (604) 555-1234;ext5678",
"address" : { "formatted" : "123 Main St., Anytown, TX 77777" },
"picture" : "http://mycompany.com/bob_photo.jpg"
}
WWW-AUTHENTICATE
header. HTTP/1.1 401 Unauthorized
CONTENT-LENGTH : 0
WWW-AUTHENTICATE : Bearer error=invalid_token,
error_description=CWWKS1617E: A userinfo request was made with
an access token that was not recognized. The request URI was
/oidc/endpoint/MyOAuthProvider/userinfo.