Process Introspection Request - Authlete Documentation

Full description

This API is supposed to be called from within the implementations of protected resource endpoints of the authorization server implementation in order to get information about the access token which was presented by the client application. In general, a client application accesses a protected resource endpoint of a service with an access token, and the implementation of the endpoint checks whether the presented access token has enough privileges (= scopes) to access the protected resource before returning the protected resource to the client application. To achieve this flow, the endpoint implementation has to know detailed information about the access token. Authlete /auth/introspection API can be used to get such information. The response from /auth/introspection API has some parameters. Among them, it is action parameter that the authorization server implementation should check first because it denotes the next action that the authorization server implementation should take. According to the value of action, the authorization server implementation must take the steps described below.

INTERNAL_SERVER_ERROR

When the value of action is INTERNAL_SERVER_ERROR, it means that the request from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from the viewpoint of the client application, it is an error on the server side. Therefore, the service implementation should generate a response to the client application with HTTP status of “500 Internal Server Error”. Authlete recommends application/json as the content type although OAuth 2.0 specification does not mention the format of the error response when the redirect URI is not usable. The value of responseContent is a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage), so if the protected resource of the service implementation wants to return an error response to the client application in the way that complies with RFC 6750 (in other words, if accessTokenType configuration parameter of the service is Bearer), the value of responseContent can be used as the value of WWW-Authenticate header. The following is an example response which complies with RFC 6750.

HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
&#123;responseContent&#125;

BAD_REQUEST

When the value of action is BAD_REQUEST, it means that the request from the client application does not contain an access token (= the request from the authorization server implementation to Authlete does not contain token request parameter). A response with HTTP status of “400 Bad Request” must be returned to the client application and the content type must be application/json. The value of responseContent is a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage), so if the protected resource of the service implementation wants to return an error response to the client application in the way that complies with RFC 6750 (in other words, if accessTokenType configuration parameter of the service is Bearer), the value of responseContent can be used as the value of WWW-Authenticate header. The following is an example response which complies with RFC 6750.

HTTP/1.1 400 Bad Request
WWW-Authenticate: &#123;responseContent&#125;
Cache-Control: no-store
Pragma: no-cache

UNAUTHORIZED

When the value of action is UNAUTHORIZED, it means that the access token does not exist or has expired. The value of responseContent is a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage), so if the protected resource of the service implementation wants to return an error response to the client application in the way that complies with RFC 6750 (in other words, if accessTokenType configuration parameter of the service is Bearer), the value of responseContent can be used as the value of WWW-Authenticate header. The following is an example response which complies with RFC 6750.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: &#123;responseContent&#125;
Cache-Control: no-store
Pragma: no-cache

FORBIDDEN

When the value of action is FORBIDDEN, it means that the access token does not cover the required scopes or that the subject associated with the access token is different from the subject contained in the request. A response with HTTP status of “400 Bad Request” must be returned to the client application and the content type must be application/json. The value of responseContent is a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage), so if the protected resource of the service implementation wants to return an error response to the client application in the way that complies with RFC 6750 (in other words, if accessTokenType configuration parameter of the service is Bearer), the value of responseContent can be used as the value of WWW-Authenticate header. The following is an example response which complies with RFC 6750.

HTTP/1.1 403 Forbidden
WWW-Authenticate: &#123;responseContent&#125;
Cache-Control: no-store
Pragma: no-cache

OK

When the value of action is OK, it means that the access token which the client application presented is valid (= exists and has not expired). The implementation of the protected resource endpoint is supposed to return the protected resource to the client application. When action is OK, the value of responseContent is "Bearer error=\"invalid_request\"". This is the simplest string which can be used as the value of WWW-Authenticate header to indicate “400 Bad Request”. The implementation of the protected resource endpoint may use this string to tell the client application that the request was bad (e.g. in case necessary request parameters for the protected resource endpoint are missing). However, in such a case, the implementation should generate a more informative error message to help developers of client applications. The following is an example error response which complies with RFC 6750.

HTTP/1.1 400 Bad Request
WWW-Authenticate: &#123;responseContent&#125;
Cache-Control: no-store
Pragma: no-cache

Basically, The value of responseContent is a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage). So, if the service has selected Bearer as the value of accessTokenType configuration parameter, the value of responseContent can be used directly as the value of WWW-Authenticate header. However, if the service has selected another different token type, the service has to generate error messages for itself. JWT-based access token Since version 2.1, Authlete provides a feature to issue access tokens in JWT format. This feature can be enabled by setting a non-null value to the accessTokenSignAlg property of the service (see the description of the Service class for details). /api/auth/introspection API can accept access tokens in JWT format. However, note that the API does not return information contained in a given JWT-based access token but returns information stored in the database record which corresponds to the given JWT-based access token. Because attributes of the database record can be modified after the access token is issued (for example, by using /api/auth/token/update API), information returned by /api/auth/introspection API and information the given JWT-based access token holds may be different.

Authorizations

Authorization

string

header

required

Authenticate every request with a Service Access Token or Organization Token. Set the token value in the Authorization: Bearer <token> header.

Service Access Token: Scoped to a single service. Use when automating service-level configuration or runtime flows.

Organization Token: Scoped to the organization; inherits permissions across services. Use for org-wide automation or when managing multiple services programmatically.

Both token types are issued by the Authlete console or provisioning APIs.

Path Parameters

serviceId

string

required

A service ID.

Body

token

string

required

An access token to introspect.

scopes

string[]

A string array listing names of scopes which the caller (= a protected resource endpoint of the service) requires. When the content type of the request from the service is application/x-www-form-urlencoded, the format of scopes is a space-separated list of scope names.

If this parameter is a non-empty array and if it contains a scope which is not covered by the access token,action=FORBIDDEN with error=insufficient_scope is returned from Authlete.

subject

string

A subject (= a user account managed by the service) whom the caller (= a protected resource endpoint of the service) requires.

If this parameter is not null and if the value does not match the subject who is associated with the access token, action=FORBIDDEN with error=invalid_request is returned from Authlete.

clientCertificate

string

Client certificate in PEM format, used to validate binding against access tokens using the TLS client certificate confirmation method.

dpop

string

DPoP header presented by the client during the request to the resource server.

The header contains a signed JWT which includes the public key that is paired with the private key used to sign the JWT. See OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP) for details.

htm

string

HTTP method of the request from the client to the protected resource endpoint. This field is used to validate the DPoP header.

See OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP) for details.

htu

string

URL of the protected resource endpoint. This field is used to validate the DPoP header.

See OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP) for details.

resources

string[]

The resources specified by the resource request parameters in the token request. See "Resource Indicators for OAuth 2.0" for details.

acrValues

string[]

Authentication Context Class Reference values one of which the user authentication performed during the course of issuing the access token must satisfy.

maxAge

integer<int64>

The maximum authentication age which is the maximum allowable elapsed time since the user authentication was performed during the course of issuing the access token.

requiredComponents

string[]

HTTP Message Components required to be in the signature. If absent, defaults to [ "@method", "@target-uri", "authorization" ].

uri

string

The full URL of the userinfo endpoint.

message

string

The HTTP message body of the request, if present.

headers

object[]

HTTP headers to be included in processing the signature. If this is a signed request, this must include the Signature and Signature-Input headers, as well as any additional headers covered by the signature.

Show child attributes

targetUri

string

The target URI of the resource request, including the query part, if any.

dpopNonceRequired

boolean

The flag indicating whether to check if the DPoP proof JWT includes the expected nonce value.

If this request parameter is set to true or if the service's dpopNonceRequired property is set to true, the /auth/introspection API checks if the DPoP proof JWT includes the expected nonce value. In this case, the response from the /auth/introspection API will include the dpopNonce response parameter, which should be used as the value of the DPoP-Nonce HTTP header.

requestBodyContained

boolean

The flag indicating whether the resource request contains a request body.

When the resource request must comply with the HTTP message signing requirements defined in the FAPI 2.0 Message Signing specification, the "content-digest" component identifier must be included in the signature base of the HTTP message signature (see RFC 9421 HTTP Message Signatures) if the resource request contains a request body.

When this requestBodyContained parameter is set to true, Authlete checks whether "content-digest" is included in the signature base, if the FAPI profile applies to the resource request.

Response

resultCode

string

The code which represents the result of the API call.

resultMessage

string

A short message which explains the result of the API call.

action

enum<string>

The next action that the authorization server implementation should take.

Available options:

INTERNAL_SERVER_ERROR,

BAD_REQUEST,

UNAUTHORIZED,

FORBIDDEN,

OK

responseContent

string

The content that the authorization server implementation can use as the value of WWW-Authenticate header on errors.

clientId

integer<int64>

The client ID.

clientIdAlias

string

The client ID alias when the token request was made. If the client did not have an alias, this parameter is null. Also, if the token request was invalid and it failed to identify a client, this parameter is null.

clientIdAliasUsed

boolean

The flag which indicates whether the client ID alias was used when the token request was made. true if the client ID alias was used when the token request was made.

expiresAt

integer<int64>

The time at which the access token expires. The value is represented in milliseconds since the Unix epoch (1970-01-01).

subject

string

The subject who is associated with the access token. The value of this property is null if the access token was issued using the flow of Client Credentials Grant.

scopes

string[]

The scopes covered by the access token.

existent

boolean

true if the access token exists.

usable

boolean

true` if the access token is usable (= exists and has not expired).

sufficient

boolean

true if the access token exists.

refreshable

boolean

true if the access token can be refreshed using the associated refresh token which had been issued along with the access token. false if the refresh token for the access token has expired or the access token has no associated refresh token.

properties

object[]

The extra properties associated with the access token.

Show child attributes

certificateThumbprint

string

The client certificate thumbprint used to validate the access token.

resources

string[]

The target resources. This represents the resources specified by the resource request parameters or by the resource property in the request object.

See "Resource Indicators for OAuth 2.0" for details.

accessTokenResources

string[]

The target resources this proeprty holds may be the same as or different from the ones resource property holds.

authorizationDetails

object

The authorization details. This represents the value of the authorization_details request parameter in the preceding device authorization request which is defined in "OAuth 2.0 Rich Authorization Requests".

Show child attributes

serviceAttributes

object[]

The attributes of this service that the client application belongs to.

Show child attributes

clientAttributes

object[]

The attributes of the client.

Show child attributes

scopeDetails

object[]

The scopes property of this class is a list of scope names. The property does not hold information about scope attributes. This scopeDetails property was newly created to convey information about scope attributes.

Show child attributes

grantId

string

The value of the grant_id request parameter of the device authorization request.

The grant_id request parameter is defined in Grant Management for OAuth 2.0 , which is supported by Authlete 2.3 and newer versions.

grant

object

Show child attributes

forExternalAttachment

boolean

the flag which indicates whether the access token is for an external attachment.

consentedClaims

string[]

the claims that the user has consented for the client application to know.

grantType

enum<string>

The grant type of the access token when the access token was created.

Available options:

AUTHORIZATION_CODE,

IMPLICIT,

PASSWORD,

CLIENT_CREDENTIALS,

REFRESH_TOKEN,

CIBA,

DEVICE_CODE,

TOKEN_EXCHANGE,

JWT_BEARER,

PRE_AUTHORIZED_CODE

acr

string

The Authentication Context Class Reference of the user authentication that the authorization server performed during the course of issuing the access token.

authTime

integer<int64>

The time when the user authentication was performed during the course of issuing the access token.

clientEntityId

string

The entity ID of the client.

clientEntityIdUsed

boolean

Flag which indicates whether the entity ID of the client was used when the request for the access token was made.

forCredentialIssuance

boolean

The flag indicating whether the token is for credential issuance.

cnonce

string

The c_nonce

cnonceExpiresAt

integer<int64>

The time at which the c_nonce expires.

issuableCredentials

string

The credentials that can be obtained by presenting the access token.

dpopNonce

string

The expected nonce value for DPoP proof JWT, which should be used as the value of the DPoP-Nonce HTTP header.

responseSigningRequired

boolean

The flag indicating whether the HTTP response from the protected resource endpoint must include an HTTP message signature (RFC 9421 HTTP Message Signatures) in compliance with FAPI 2.0 Message Signing.

When this response parameter is true, the HTTP response from the protected resource endpoint must include the Signature and Signature-Input HTTP fields.

metadataDocumentLocation

string<uri>

The location of the client's metadata document that was used to resolve client metadata.

This property is set when client metadata was retrieved via the OAuth Client ID Metadata Document (CIMD) mechanism.

metadataDocumentUsed

boolean

Flag indicating whether a metadata document was used to resolve client metadata for this request.

When true, the client metadata was retrieved via the CIMD mechanism rather than from the Authlete database.

Authlete

​INTERNAL_SERVER_ERROR

​BAD_REQUEST

​UNAUTHORIZED

​FORBIDDEN

​OK

Authorizations

Path Parameters

Body

Response

INTERNAL_SERVER_ERROR

BAD_REQUEST

UNAUTHORIZED

FORBIDDEN

OK