Custom Scope Introspection Endpoint

Overview

The scope introspection is a custom endpoint that Authway supports.

Tokens (both ID token and access token) can become large when they contain many claims and there are good reasons for keeping them small. For access tokens one solution is to use reference token.

Another challenge with tokens is that their content often is static after the creation. This can become a problem especially for long-lived tokens. For user permissions this is often not desirableand the change must take effect before the lifetime of the token has expired.

Authway therefor exposes the scope introspection endpoint that allows an API (or client) to fetch both updated and new claims from the IdP.

Endpoint

The endpoint is advertised in the scope_introspection_endpoint in the metadata exposed by the discovery endpoint and typically is:

GET https://[BASE_URL]/connect/scope/introspect

Parameters (form-encoded)

Parameter Required Description
sub Yes The unique identity of the user sub.
scope Optional Space-delimited list of scopes. If not passed Authway will return claims for the perms scope. Only identity scopes are allowed and not API scopes.
tid Optional The unique identity of the tenant.

Authentication

  • The API (or client) must authenticate (e.g., Basic Auth or in the body, with Api resource and api_resource_secret or client_id and client_secret).

Response

A successful response is a JSON object containing user claims. Example:

{
   "sub": "6b3d5b7b-867b-4e34-98df-f1c8a9af37b9",
   "name": "Alice Adams",
   "given_name": "Alice",
   "family_name": "Adams",
   "preferred_username": "[email protected]",
   "email": "[email protected]",
   "email_verified": true 
}

Usage Example

GET /connect/scope/introspect
Authorization: Basic base64(api_resource:api_resource_secret)

sub=6b3d5b7b-867b-4e34-98df-f1c8a9af37b9&scope=profile perms

Security Considerations

  • APIs and Clients should request only the scopes they need (profile, email, phone, perms) to avoid unnecessary data exposure.
  • Only clients will have configuration for allowed scopes, which effectivly means that an API resource can request any scopes.