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 or POST 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
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.
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"
}
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.