Token Endpoint

1. Requesting tokens with a grant

Clients obtain identity and access tokens from the token endpoint in exchange for an OAuth 2.0 grant. The grant is a recognized credential which lets the client access the requested resource (web API) or user identity.

The token endpoint of the cidaas server accepts the following grant types:

• Authorization code — the code obtained from the authorisation endpoint which the server uses to look up the granted permission or consent.
• Resource owner password credentials — the client obtains the end-user username and password and passes them to the token endpoint; use of this grant should be limited to highly-trusted clients or devices.
• Client credentials — the client ID and secret obtained from [client-registration]; this grant is intended for clients acting on their own behalf.
• Refresh token — a special token which can be used to retrieve a new ID / refresh token.

The implicit grant (or flow) is the only one which doesn’t involve the token endpoint; with it the requested ID / access tokens are returned from the authorization endpoint.

2. The token endpoint URL

The token endpoint URL can be obtained from the server discovery endpoint:

3. Client authentication

Confidential clients must explicitly authenticate themselves to the cidaas server with their registered credentials in order to make a token request, unless a self-issued JWT bearer assertion grant is submitted (where the assertion itself serves as implicit client authentication).

Client secret basic is the default authentication method.

Authorization: Basic eyJhbGciOiJSUzI1NiIsImtpZCI6ImVm...

Clients may register an alternative authentication method, such as client secret POST, client secret JWT or private key JWT.

Public clients (that have not been issued a credential) should identify themselves with the client_id parameter.

4. Web API overview

4. Resources

4.1 /token-srv/token

4.1.1 POST

Requests an ID / access / refresh token.

Header parameters:

• [ Authorization ] Used for HTTP basic authentication of the client.
• Content-Type Must be set to application/x-www-form-urlencoded.

Body:

The request parameters for the appropriate OAuth 2.0 grant type:

• Authorization code grant:
  • grant type Must be set to authorization_code.
  • client_id
  • client_secret
  • codeThe code received with the authentication response.
  • redirect uri The value of the redirect_uri parameter included in the original authentication request.
  • [ code_verifier ] The code verifier if Proof Key of Code Exchange (PKCE) is employed (for public OAuth clients).
• Password grant:
  • grant_type Must be set to password.
  • client_id.
  • client_secret.
  • username The resource owner username.
  • password The resource owner password.
  • [ scope ] Optional requested scope values for the access token.
• Client credentials grant
  • grant type Must be set to client_credentials.
  • client_id
  • client_secret
• Refresh token grant:
  • grant type Must be set to refresh_token.
  • refresh_token The refresh token issued to the client.
  • client_id
  • client_secret

Success:

• Code: 200
• Content-Type: application/json
• Body: {object} The token response.

Errors:

• 400 Bad Request with a [token error code]
• 401 Unauthorised with a [token error code]
• 500 Internal Server Error

Example token request with a code grant:

POST: /token-srv/token HTTP/1.1
Host: <span class="baseurl"></span>
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6ImVm
Content-Type: application/x-www-form-urlencoded

Request Body
{
"grant_type": "authorization_code",
"code": "3d442cc5-8775-4574-9460-cdf2a97bda2b",
"redirect_uri": "https://<span class="baseurl"></span>/redirect_url",
"client_id": "378abf89-f861-41d9-a7f6-0b38d22fbf98",
"scope": "openid email"
}

Example token request with a code grant for a public client with PKCE:

POST /token-srv/token HTTP/1.1
Host: <span class="baseurl"></span>
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6ImVm
Content-Type: application/x-www-form-urlencoded

Request Body
{

"grant_type": "authorization_code",
"code": "3d442cc5-8775-4574-9460-cdf2a97bda2b",
"redirect_uri": "https://<span class="baseurl"></span>/redirect_url",
"code_verifier": "4rnbs78-383r828-yyg233y3"

}

Example token request with a password grant:

POST /token-srv/token HTTP/1.1
Host: <span class="baseurl"></span>
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6ImVm
Content-Type: application/x-www-form-urlencoded
Request Body
{

"grant_type": "password",
"username": "williambrown",
"password": "******"

}

Example token request with a client credentials grant:

POST /token-srv/token HTTP/1.1
Host: <span class="baseurl"></span>
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6ImVm
Content-Type: application/x-www-form-urlencoded

Request Body
{

"grant_type": "client_credentials",
"client_id": "4832970d-ea18-4c86-a959-fb72*****",
"client_secret": "7f99c292-4763-457b-bdaa-e1*****"

}

Example response with an access and ID token:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "sub"          : "a0907b7b-f178-410a-9db9-44cf95943c53",
  "access_token" : "eyJhbGciOiJSUzI1NiIsImtpZCI6ImVmYmRmNmQ...",
  "token_type"   : "Bearer",
  "expires_in"   :  86400,
  "scope"        : "openid email profile phone address",
  "id_token"     : "eyJraWQiOiIxZTlnZGs3IiwiYWxnIjoiUl..."
}

5. Representations

5.1 Token response

The authorization server issues an access token and optional refreh token, and constructs the response by adding the following parameters to the entity-body of the HTTP response with a 200 (OK) status code:

• access_token The access token issued by the server.
• token_type Set to bearer.
• expires_in The lifetime of the access token, in seconds.
• [ id_token ] Optional identity token, issued for the code and password grants. Not provided for client credentials grants.
• [ refresh_token ] Optional refresh token, which can be used to obtain new access tokens. Issued only for long-lived authorisations that permit it.
• scope The scope of the access token.

Example token response with an access token and ID token:

{
  "sub"          : "3d442cc5-8775-4574-9460-cdf2a97bda2b",
  "access_token" : "eyJhbGciOiJSUzI1NiIsImtpZCI6ImVmYmRmNmQ...",
  "token_type"   : "Bearer",
  "expires_in"   : 86400,
  "scope"        : "openid email profile phone address",
  "id_token"     : "eyJraWQiOiIxZTlnZGs3IiwiYWxnIjoiUl..."  
}

5.2 Token error

JSON object with members:

• error An error code which can take on of the following values:
• invalid_request The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, or is otherwise malformed.
• invalid_client Client authentication failed, due to missing or invalid client credentials.
• invalid_grant The provided OAuth 2.0 grant is invalid, expired or has been revoked. May also indicate the redirect_uri parameter doesn’t match (for a code grant).
• unauthorized_client The client is successfully authenticated, but it’s not registered to use the submitted grant type.
• unsupported_grant_type The grant type is not supported by the server.
• invalid_scope The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.
• [ error_description ] Optional text providing additional information about the error that occurred.
• [ error_uri ] Optional URI for a web page with information about the error that occurred.

Example token error:

{
  "error" : "invalid_request"
}

Example token error with additional information:

{
  "error"             : "invalid_request",
  "error_description" : "Missing required grant type parameters"
}

6. Errors

400 Bad Request

Invalid or denied request, see token error codes for more information.

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "invalid_client",
    "error_description": "Client authentication failed : Unknown client"
}

401 Unauthorized

The request was denied due to an invalid or missing client authentication, see token error codes for more information.

Example:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
Content-Type: application/json

{
  "error"             : "invalid_client",
  "error_description" : "Missing client authentication"
}

500 Internal Server Error

An internal server error has occurred. Check the cidaas server logs for details.

Example:

HTTP/1.1 500 Internal Server Error