Token introspection

When an application receives an HTI launch, it will contain a JWT token. To ensure that not every application has to build in all the security logic to verify this token, Koppeltaal offers Token Introspection on the authentication server. This eliminates the need for the application to verify the JWT itself.

When Token Introspection approves a token, the extracted body of the JWT token will be returned. If a 200 response code is returned, the application must ALWAYS verify that the active attribute in the response is true.

POST {AUTH_SERVER_URL}/oauth2/introspect

Headers

Name	Type	Description
Content-Type*	String	application/x-www-form-urlencoded
Accept*	String	application/json

Request Body

Name	Type	Description
client_assertion*	String	JWT as composed for the SMART Backend Service
client_assertion_type*	String	Always: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
token*	String	The JWT to be validated

200: OK The token is introspected. The active field displays whether it is valid

Valid Token

{
  "active": true,
  "client_id": "l238j323ds-23ij4",
  "username": "jdoe",
  "scope": "read write dolphin",
  "sub": "Z5O3upPC88QrAjx00dis",
  "aud": "https://protected.example.net/resource",
  "iss": "https://server.example.com/",
  "exp": 1419356238,
  "iat": 1419350238,
  "extension_field": "twenty-seven"
}

Invalid Token

{
  "active": false
}

401: Unauthorized Not authorised to execute introspection

{
    // Response
}

Topics

TOP-KT-007 - Koppeltaal Launch

TOP-KT-021 - Token Introspection