OAuth 2.0 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 token endpoint of the Connect2id server supports the following grant types:

  • Authorisation code -- the code obtained from the authorisation endpoint which the server uses to look up the permission or consent given by the end-user.

  • Refresh token -- a special token which can be used to retrieve a new ID or access token.

  • Client credentials -- intended for clients acting on their own behalf.

  • Resource owner password credentials -- the client submits a username and password entered by the end-user; use of this grant is not recommended and should be limited to highly-trusted clients and devices.

  • JWT bearer assertion -- a signed JSON Web Token (JWT), issued by a third-party token service (STS) or issued by the client itself, to obtain an access and / or ID token.

  • SAML 2.0 bearer assertion -- a SAML 2.0 assertion, issued by a third-party token service (STS) or issued by the client itself, to obtain an access and / or ID 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 authorisation endpoint.

2. The token endpoint URL

It can be found out from the token_endpoint advertised in the Connect2id server metadata and has this form:

https://[base-server-url]/token

3. Client authentication

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

Basic authentication is the default method when a client is registered.

Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

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

Authentication using PKI or a self-signed certificate 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
Representations Errors

4. Resources

4.1 /token

4.1.1 POST

Requests an ID / access / refresh token.

Clients registered for mutual TLS authentication and / or TLS sender-constrained resource access must also submit their client X.509 certificate with the HTTP request.

Header parameters:

  • [ Authorization ] Used for HTTP basic authentication of the client.

  • [ DPop ] An optional DPoP proof JWT, to trigger a issue of an access token of type DPoP.

  • Content-Type Must be set to application/x-www-form-urlencoded.

  • [ Issuer ] The issuer URL when issuer aliases are configured, or the issuer URL for a tenant (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Tenant-ID header.

  • [ Tenant-ID ] The tenant ID (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Issuer header.

Body:

  • The request parameters for the appropriate OAuth 2.0 grant type:

    • Authorisation code grant:

    • Password grant:

      • grant_type Must be set to password.
      • 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.
      • [ scope ] Optional requested scope values for the access token.
    • Refresh token grant:

      • grant_type Must be set to refresh_token.
      • refresh_token The refresh token issued to the client.
      • [ scope ] Optional requested scope values for the new access token. Must not include any scope values not originally granted by the resource owner, and if omitted is treated as equal to the originally granted scope.
    • JWT bearer assertion grant:

      • grant_type Must be set to urn:ietf:params:oauth:grant-type:jwt-bearer.
      • assertion The JWT assertion.
      • [ scope ] Optional requested scope values for the access token.
    • SAML 2.0 bearer assertion grant:

      • grant_type Must be set to urn:ietf:params:oauth:grant-type:saml2-bearer.
      • assertion The SAML 2.0 assertion, base 64 URL encoded.
      • [ scope ] Optional requested scope values for the access token.

Success:

  • Code: 200

  • Content-Type: application/json

  • Body: {object} The token response.

Errors:

Example token request for a confidential client with a code grant:

POST /token HTTP/1.1
Host: c2id.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

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

POST /token HTTP/1.1
Host: c2id.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=com.example%3A%2F%2F%2Fauth
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

Example token request for a public client with a password grant:

POST /token HTTP/1.1
Host: c2id.com
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=alice&password=secret

Example token request with a client credentials grant:

POST /token HTTP/1.1
Host: c2id.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

Example response with a Bearer access and ID token:

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

{
  "access_token" : "2YotnFZFEjr1zCsicMWpAA",
  "token_type"   : "Bearer",
  "expires_in"   : 3600,
  "scope"        : "openid email profile app:read app:write",
  "id_token"     : "eyJraWQiOiIxZTlnZGs3IiwiYWxnIjoiUl..."
}

5. Representations

5.1 Token response

JSON object with members (see section 5.1 of the OAuth 2.0 standard for more information):

  • access_token The access token issued by the server.

  • token_type Set to Bearer or DPoP.

  • 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.

Additional members may be present if set by a custom token response plugin.

Example token response with a Bearer access and ID token:

{
  "access_token" : "2YotnFZFEjr1zCsicMWpAA",
  "token_type"   : "Bearer",
  "expires_in"   : 3600,
  "scope"        : "openid email profile app:read app:write",
  "id_token"     : "eyJraWQiOiIxZTlnZGs3IiwiYWxnIjoiUl..."
}

5.2 Token error

JSON object with members:

  • error An error code which can take one 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.
    • invalid_dpop_proof -- The request includes an invalid DPoP proof JWT.
  • [ 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.

Additional members may be present if set by a custom token response plugin.

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_grant",
  "error_description" : "Bad request: Invalid or expired authorization code"
}

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: Basic
Content-Type: application/json

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

500 Internal Server Error

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

Example:

HTTP/1.1 500 Internal Server Error