Who’s calling?

Securing APIs with token introspection

Photo by Liam Tucker on Unsplash
  1. Subject/User/Application gets access token from Authorization Server via one of the defined grant types. The token may contain scopes needed to access the Resource Server, like user:read scope.
  2. Application sends a request to Resource Server including the access token as Bearer token. A typical request could be https://api.example.com/users with a HTTP Header like “Authorization: Bearer 2YotnFZFEsicMWpAA”.
  3. Resource Server gets the access token and introspects it by either requesting the Authorization Server directly, or in case of JWT by unpacking the token and verifying the signature of the token.

The introspection specification

POST /introspect HTTP/1.1
Host: server.example.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

token=2YotnFZFEjr1zCsicMWpAA
HTTP/1.1 200 OK
Content-Type: application/json
{
"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
}

Local introspection

Token introspection package

Token introspection as middleware

Token introspection as Lambda Authorizer

  • Unauthorized (HTTP 401) for missing token or other introspection errors,
  • Forbidden (HTTP 403) for valid token but missing the required scope,
  • An allow-execution policy for valid token and correct scope

--

--

Senior Staff Engineer at Schibsted, fringe hipster, father of three

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Joakim Wånggren

Senior Staff Engineer at Schibsted, fringe hipster, father of three