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 Liberty profile 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
Note: In this example, the SSL port of the OP is expected to be 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.

Icon that indicates the type of topic Task topic



Timestamp icon Last updated: Saturday, 3 December 2016
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twlp_oidc_userinfo_endpoint
File name: twlp_oidc_userinfo_endpoint.html