Token Introspection Endpoint

1. Inspecting Access Tokens

This specification defines a method for a protected resource to query an OAuth 2.0 authorization server to determine the active state of an OAuth 2.0 token and to determine meta-information about this token.

OAuth 2.0 secured resource servers must check the access token of each client request before carrying on with the actual processing of the request. Access tokens issued by the cidaas server can be inspected at this endpoint, as specified in RFC 7662. If the token is valid and still active (hasn’t expired) the endpoint will return the underlying authorization properties.

2. The Token Introspection URL

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

Introspection URL: https://[your_cidaas_domain_url]token-srv/introspect

3. Prerequisites

Requests to the introspection endpoint must be either authenticated with client credentials or authorised with a bearer access token.

To this end the resource server should be registered as a minimal OAuth 2.0 client for the client_credentials grant type (as a client acting on its own behalf) and a scope value that matches the URI of the introspection endpoint,

3.1 Token Authorization

This approach uses a token to authorise the introspection request.

First, the resource server must first make a request to obtain an access token for the expected scope (represented by the introspection endpoint URI) using its registered client credentials grant.

POST /token-srv/token HTTP/1.1
Host: sampleeshop.cidaas.de
Authorization: Basic eYxphZDdjcXkzNGJnNDoxZnU5c1pFNTZ5ZGp6R21vdkVIaklEZ3JkWURjVDVnZC1ncWdYd2h2bVMw
Content-Type: application/x-www-form-urlencoded

{
   grant_type: client_credentials,
   client_id: d38acbb9-3d19-4f68-89d9-fd*******,
   client_secret: 5c634d6e-e23a-455c-8c4b-4537****
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  {
    "sub": "ANONYMOUS",
    "token_type": "Bearer",
    "expires_in": 86400,
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYwOGU5YjAwLTgyN"
  }
}

The resource server can then pass this access token in the Authorization header of token introspection requests, until the token expires or is about to expire. The resource server can then repeat the previous step to obtain a new access token.

4. Web API Overview

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

4. Resources

4.1 /token-srv/introspect

4.1.1 POST

Inspects an access token. Inspection of refresh tokens is not supported by the cidaas server, although they may be submitted according to the RFC 7662 spec. Here we can validate access token in two way:

  1. Basic Authentication
  2. Authorization bearer token

1. Basic Authentication:

Basic authentication is a simple authentication scheme built into the HTTP protocol. The client sends HTTP requests with the Authorization header that contains the word Basic word followed by a space and a base64-encoded string username:password. For example, to authorize as demo / p@55w0rd the client would send: Authorization: Basic ZGVtbzpwQDU1dzByZA==

Note: Because base64 is easily decoded, Basic authentication should only be used together with other security mechanisms such as HTTPS/SSL.

Header parameters:

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

Here basic auth we should pass the following fields.

  • Username we should pass the client_id.
  • Password we should pass the client_secret.

Body with raw parameters:

  • token The token to inspect.
  • [ token_type_hint ] Optional hint about the type of the submitted token.
    • access_token — the token is an access token
    • id_token — the token is an id token
    • refresh_token — the token is a refresh token (not supported)

Success:

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

Errors:

  • 400 Bad Request
  • 401 Unauthorised
  • 500 Internal Server Error
  • 404 Not Found

Example token introspection request using basic authentication:

POST /token-srv/introspect HTTP/1.1
Host: sampleeshop.cidaas.de
Content-Type: application/json
Authorization: Basic ZGVtbzpwQDU1dzByZAFmQmF0M2JW

Request Body
{

token: eyJhbGciOiJSUzI1NiIsImtpZCI6I******,
token_type_hint: id_token

}

2.Authorization bearer token:

Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The name “Bearer authentication” can be understood as “give access to the bearer of this token.” The bearer token is a cryptic string, usually generated by the server in response to a login request. The client must send this token in the Authorization header when making requests to protected resources:

Authorization: Bearer <token>

The Bearer authentication scheme was originally created as part of OAuth 2.0 in RFC 6750, but is sometimes also used on its own. Similarly to Basic authentication, Bearer authentication should only be used over HTTPS (SSL). Header parameters:

  • [ Authorization ] Used for bearer token authorization.
  • Content-Type Must be set to application/json.

Body with raw parameters:

  • token The token to inspect.
  • [ token_type_hint ] Optional hint about the type of the submitted token:
    • access_token — the token is an access token
    • id_token — the token is an id token
    • refresh_token — the token is a refresh token (not supported)
  • client_id - must be used client_id
  • client_secret - must be used client_secret

Success:

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

Errors:

  • 400 Bad Request
  • 401 Unauthorised
  • 500 Internal Server Error
  • 404 Not Found

Example token introspection request using bearer token authorization:

POST /token-srv/introspect HTTP/1.1
Host: sampleeshop.cidaas.de
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6InMxIn0.eyJzY3AiOlsiaHR0...

Request Body

{

token: eyJhbGciOiJSUzI1NiIsImtpZCI6ImVmYmRmNmQ,
token_type_hint: id_token / access_token,
client_id: "66j3bv73h742****",
client_secret: "jkseiu3242bkj***"

}

The server will return a 200 status regardless of whether the submitted token was valid or not (required by the specification):

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "active": true,
    "aud": "ca0b93ec-1fbd-4146-98d1-6915c806c3b6",
    "client_id": "ca0b93ec-1fbd-4146-98d1-6915******",
    "exp": 1525590060,
    "iat": 1525503660,
    "iss": "https://[your_cidaas_domain_url]",
    "jti": "fd9c0ce1-897b-4af8-9119-ebd453c8dfe5",
    "scopes": [
        "cidaas:login",
        "cidaas:userinfo",
        "cidaas:userupdate",
        "cidaas:admin_read",
        "cidaas:admin_write",
        "cidaas:admin_delete"
    ],
    "sub": "ANONYMOUS",
    "token_type": "Bearer",
    "scope": "cidaas:login cidaas:userinfo cidaas:userupdate cidaas:admin_read cidaas:admin_write cidaas:admin_delete"
}

For an invalid token:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "active" : false
}

5. Representations

5.1 Token Introspection Response

The token introspection result is represented as a JSON object. The only required member according to RFC 7662 is active which indicates the token’s validity.

  • If the token is valid the cidaas server will include the available token details in the response.
  • If the token is invalid or has expired **active** will be set to **false** and no other details will be included.
  • active {true|false} If true the token is valid and active. If false the token is either invalid or has expired.
  • [ scope ] {string} The scope values for the token. The cidaas server will always set this value.
  • client_id {string} The identifier of the OAuth 2.0 client that requested the token. The cidaas server will always set this value.
  • token_type {string} Type of the token, set to Bearer. The cidaas will always set this value.
  • exp {number} The token expiration time, as number of seconds since the Unix epoch (1970-01-01T0:0:0Z) as measured in UTC until the date/time. Has the same semantics as the JWT claim name. The cidaas server will always set this value.
  • iat {number} The token issue time, as number of seconds since the Unix epoch (1970-01-01T0:0:0Z) as measured in UTC until the date/time. Has the same semantics as the JWT claim name.
  • sub {string} The subject of the token. Typically the user identifier of the resource owner who authorised the token. Has the same semantics as the JWT claim name. The cidaas server will always set this value.
  • aud {string array} Audience values for the token. Has the same semantics as the JWT claim name.
  • iss {string} The token issuer (the OpenID provider issuer identifier). Has the same semantics as the JWT claim name.
  • jti {string} Identifier for the token. Has the same semantics as the JWT claim name.

Example: introspection response for a valid token:

{
    "active": true,
    "aud": "ca0b93ec-1fbd-4146-98d1-6915c806c3b6",
    "client_id": "ca0b93ec-1fbd-4146-98d1-691******",
    "exp": 1525590060,
    "iat": 1525503660,
    "iss": "https://[your_cidaas_domain_url]",
    "jti": "fd9c0ce1-897b-4af8-9119-ebd453c8dfe5",
    "scopes": [
        "cidaas:login",
        "cidaas:userinfo",
        "cidaas:userupdate",
        "cidaas:admin_read",
        "cidaas:admin_write",
        "cidaas:admin_delete"
    ],
    "sub": "ANONYMOUS",
    "token_type": "Bearer",
    "scope": "cidaas:login cidaas:userinfo cidaas:userupdate cidaas:admin_read cidaas:admin_write cidaas:admin_delete"
}

Example: introspection response for an invalid or expired token:

{ 
  "active" : false
}

5. Errors

400 Bad Request

Invalid or malformed request.

Example:

HTTP/1.1 400 Bad Request

{
  "error"             : "invalid_request",
  "error_description" : "Invalid request: Missing required client_id and client_secret"
}
401 Unauthorized

The request was denied due to an invalid or missing client authentication / authorization.

Example:

HTTP/1.1 401 Unauthorized

{
  "error"             : "invalid_client",
  "error_description" : "Client authentication failed : Unknown client"
}
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 ""