Table of Contents
Use cases for two introspection APIs
Preface
This article describes Authlete’s two kinds of introspection APIs and their use cases.
Introspection APIs provided by Authlete
Authlete provides two APIs to fulfill token introspection.
/auth/introspection API
/auth/introspection API is a proprietary API of Authlete. It is designed to be used by implementation of protected resource endpoint (e.g. Web API) in a resource server (RS).
The API can accept request parameters including an access token and other values expected to be bound to the token such as a scope , a subject and a client certificate , to allow the RS to offload verification of the binding, to Authlete. Thus implementation of the RS would be reduced.
/auth/introspection/standard API
/auth/introspection/standard API is designed to be used by implementation of an RFC 7662 compliant introspection endpoint in an authorization server (AS).
It allows an RS to use the RFC 7662 compliant introspection API. The AS doesn’t have to share Authlete’s API key and secret with the RS.
Which introspection API should be used
The appropriate introspection API would be chosen by degree of “loosely/tightly coupled” among AS / RS / Authlete. This section describes typical use cases and which API is recommended for each case.
RS to talk directly to Authlete
If an RS is permitted to have Authlete’s API key and secret, the most simple architecture would be that the RS itself makes a request to Authlete’s /auth/introspection API using the credential.
API gateway to accept all incoming API requests from clients
If an API gateway is deployed to have both a part of AS’ endpoints (e.g. token endpoint) and RS’ endpoints, it naturally has Authlete’s API key and secret. Thus using /auth/introspection API would be the most simple architecture, as discussed in the previous case.
RS to use RFC 7662 compliant introspection API
If an RS doesn’t (or isn’t permitted to) connect to Authlete, or if you would like to separate an AS and an RS, it would be better for the AS to provide RFC 7662 compliant introspection API to the RS, by using Authlete’s /auth/introspection/standard API.
