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:

well-known URL: https://[your_cidaas_domain_url]/token-srv/token

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.

Authentication using public key bound client X.509 certificates is also supported.

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

4. Web API overview

Resources
  • /token-srv/token [POST]
RepresentationsErrors
  • Token response
  • Token error
  • 400 Bad Request
  • 401 Unauthorized
  • 500 Internal Server Error

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).
    • 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: sampleeshop.cidaas.de
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://sampleeshop.cidaas.de/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: cidaas-management.cidaas.de
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://sampleeshop.cidaas.de/redirect_url",
"code_verifier": "4rnbs78-383r828-yyg233y3"

}

Example token request with a password grant:

POST /token-srv/token HTTP/1.1
Host: sampleeshop.cidaas.de
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: sampleeshop.cidaas.de
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



results matching ""

    No results matching ""