Token

The token endpoint, in general terms, is used to get access tokens through grants. The grants are identified through a grant type. The supported grant types are listed in Table 1.

The tokens returned can be in different formats. The supported formats are JWT or Reference.

JWT is a well structured token format using JSON, and it supports signatures and encryption.

Reference is a random string, which is only understood by AuthServer. The content of the token, can be retrieved from the Introspection endpoint.

The client can choose between the two in its metadata, through the field "UseReferenceToken".

If bandwidth of the client is of concern, or you require the content of token is only send through backchannels, then the Reference token is a suitable candidate. It however requires an extra roundtrip at the protected resource, to verify the token at AuthServer.

Finally, it is also possible to sender-constraint a token, irrespective of its structure.

It means the token is cryptographically bound to the client that requested the token, and therefore can only be used by that client.

This is achievable through DPoP.

It is recommended that tokens have a short lifespan, in minutes and at most an hour.

This can be adjusted for each client in its metadata. Each type of token, has a specific field for adjusting its expiration.

It is recommended that tokens are only used at protected resources, which the client requests.

This is done through the "resource" parameter, which is a single protected resource absolute base URI. The parameter can be provided as many times as needed, and the URI is visible in the audience claim.

For example if a protected resource URI is reachable at "https://weather.authserver.dk", then that URI will be provded as the resource parameter.

It is recommended that tokens are only used for what they request.

This is done through the "scope" parameter, which is a space seperated string of scopes that the token is authorized for.

For example if a token must be used to fetch data about the weather, and the scope required for requesting weather is named "weather:read". Then the scope parameter will be set to "weather:read".

Structured access tokens contain payload claims listed in the following table.

Id tokens contain payload claims listed in the following table.

The token endpoint accepts the POST HTTP method, and the content is application/x-www-form-urlencoded.

The endpoint also allows for client authentication, and the parameters are defined in the Client Authentication page.

The content differs by which grant_type is provided, a list of all parameters is seen in the following table.

The token endpoint returns HTTP 200 if successful, and 400 if an error occurred.

The content is application/json, and a list of all parameters is seen in the following table.

HTTP request examples are provided for each grant type, as each request and response differs depending on the grant type used.

However, the error does not differ, and the following request example shows an error scenario.

            
                
POST /connect/token HTTP/1.1
Host: idp.authserver.dk
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

grant_type=invalid_grant_type
        
            
        

The following HTTP example shows the error response.

            
                
HTTP/1.1 400 BadRequest
Content-Type: application/json;charset=UTF-8
Cache-Control: no-cache, no-store

{
  "error":"unsupported_grant_type",
  "error_description":"grant_type is unsupported"
}