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.

A WebSphere® Application Server traditional server with OpenID Connect enabled has access to the OpenID Connect UserInfo endpoint at the following URL:
https://server.example.com:443/oidc/endpoint/<provider_name>/userinfo
Avoid trouble: If you are using an outbound proxy, note that the OpenID Connect RP does not provide a means to route requests through a proxy host automatically.

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

  1. 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.
  2. Send the GET or POST request to the UserInfo endpoint URL.

Results

After completing these steps you have a valid HTTP request that is being sent to the UserInfo endpoint as shown in the Examples section.

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
An example request that uses the HTTP Bearer Authorization header to pass the access token:
POST /register HTTP/1.1
Accept: application/x-www-form-urlencoded
Authorization: Bearer fAAdLO1c6QWDbPs9HrWHz5e7nRWVAnxqTTP7i88G
The token can also be passed by using the 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.

Here is an example response for a valid access token. The 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"
}
For an invalid access token, the UserInfo endpoint returns an HTTP 401 status code with an error message in the 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.