Invoking the Token Endpoint for OpenID Connect

In the OpenID Connect Authorization Code Flow, the token endpoint is used by a client to obtain an ID token, access token, and refresh token.

Before you begin

When starting the token endpoint from an in-browser client application or a client application implemented in a scripting language such as Javascript, for example, no configuration of a Liberty server as an OpenID Connect Client is necessary.

About this task

The token endpoint accepts a request from the client that includes an authorization code that is issued to the client by the authorization endpoint. When the authorization code is validated, the appropriate tokens are returned in a response to the client.

The token endpoint is not used in the OpenID Connect Implicit Flow.

A Liberty server with OpenID Connect enabled has access to the OpenID Connect token endpoint at the following URL:

https://server.example.com:443/oidc/endpoint/<provider_name>/token
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. Prepare an HTTP POST request with the following parameters.
    • grant_type: The value of this parameter must be authorization_code.
    • code: The authorization code received from the authorization endpoint.

    The parameters must be added by using the application/x-www-form-urlencoded format.

  2. POST the request to the token endpoint URL.

Results

After completing these steps you have a valid HTTP POST request that is being sent to the token endpoint. The token endpoint returns a response as described in the Examples section.

When the OpenID Connect Provider validates the token request that is received from the client, the OpenID Connect Provider returns an HTTP 200 response back to the client with a JSON object in application/json format. The response includes the ID token, access token, and refresh token, along with the following additional parameters:

  • token_type: OAuth 2.0 Token Type. For OpenID Connect, this value is Bearer.
  • expires_in: Expiration time of the access token in seconds since the response was generated.

All responses from the token endpoint that contain tokens, secrets, or other sensitive information have their Cache-Control header value set to no-store and Pragma header value set to no-cache.

Example

The following shows examples of an HTTP POST request and response

An example request is shown here:

 POST /token HTTP/1.1
 Content-Type: application/x-www-form-urlencoded
 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
     grant_type=authorization_code
     &code=SplxlOBeZQQYbYS6WxSbIA 		
     &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb

An example response is shown here:

 HTTP/1.1 200 OK
 Content-Type: application/json
 Cache-Control: no-store
 Pragma: no-cache
 {
     "access_token": "SlAV32hkKG",
     "token_type": "Bearer",
     "refresh_token": "8xLOxBtZp8",
     "expires_in": 3600,
     "id_token": "eyJ ... zcifQ.ewo ... NzAKfQ.ggW8h ... Mzqg"
 }