Process OAuth 2.0 Introspection Request

Typescript (SDK)

import { Authlete } from "@authlete/typescript-sdk";

const authlete = new Authlete({
  serviceId: "<id>",
  bearer: process.env["AUTHLETE_BEARER"] ?? "",
});

async function run() {
  const result = await authlete.introspection.standardProcess({
    standardIntrospectionRequest: {
      parameters: "token=VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token",
    },
  });

  console.log(result);
}

run();

require 'authlete_ruby_sdk'

Models = ::Authlete::Models
s = ::Authlete::Client.new(
  service_id: '<id>',
  bearer: '<YOUR_BEARER_TOKEN_HERE>'
)
res = s.introspection.standard_process(standard_introspection_request: Models::Components::StandardIntrospectionRequest.new(
  parameters: 'token=VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token'
))

unless res.standard_introspection_response.nil?
  # handle response
end

package main

import(
	"context"
	"os"
	authlete "github.com/authlete/authlete-go-sdk"
	"github.com/authlete/authlete-go-sdk/models/components"
	"github.com/authlete/authlete-go-sdk/models/operations"
	"log"
)

func main() {
    ctx := context.Background()

    s := authlete.New(
        authlete.WithServiceID("<id>"),
        authlete.WithSecurity(os.Getenv("AUTHLETE_BEARER")),
    )

    res, err := s.Introspection.StandardProcess(ctx, operations.AuthIntrospectionStandardAPIRequest{
        Body: components.StandardIntrospectionRequest{
            Parameters: "token=VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token",
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.StandardIntrospectionResponse != nil {
        // handle response
    }
}

curl --request POST \
  --url https://us.authlete.com/api/{serviceId}/auth/introspection/standard \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "parameters": "token=VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token"
}
'

{
  "resultCode": "A145001",
  "resultMessage": "[A145001] Introspection was performed successfully (type=access_token, active=true).",
  "action": "OK",
  "responseContent": "{\\\"sub\\\":\\\"john\\\",\\\"scope\\\":\\\"history.read timeline.read\\\",\\\"iss\\\":\\\"https://my-service.example.com\\\",\\\"active\\\":true,\\\"token_type\\\":\\\"Bearer\\\",\\\"exp\\\":1640416873,\\\"client_id\\\":\\\"26478243745571\\\"}"
}

{
  "resultCode": "A001201",
  "resultMessage": "[A001201] /auth/authorization, TLS must be used."
}

{
  "resultCode": "A001202",
  "resultMessage": "[A001202] /auth/authorization, Authorization header is missing."
}

{
  "resultCode": "A001215",
  "resultMessage": "[A001215] /auth/authorization, The client (ID = 26837717140341) is locked."
}

{
  "resultCode": "A001311",
  "resultMessage": "[A001311] /auth/authorization,  Too many requests, retry after 1 seconds. (Entity: 23769878923/87122303)"
}

{
  "resultCode": "A001101",
  "resultMessage": "[A001101] /auth/authorization, Authlete Server error."
}

POST

api

{serviceId}

auth

introspection

standard

Typescript (SDK)

import { Authlete } from "@authlete/typescript-sdk";

const authlete = new Authlete({
  serviceId: "<id>",
  bearer: process.env["AUTHLETE_BEARER"] ?? "",
});

async function run() {
  const result = await authlete.introspection.standardProcess({
    standardIntrospectionRequest: {
      parameters: "token=VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token",
    },
  });

  console.log(result);
}

run();

require 'authlete_ruby_sdk'

Models = ::Authlete::Models
s = ::Authlete::Client.new(
  service_id: '<id>',
  bearer: '<YOUR_BEARER_TOKEN_HERE>'
)
res = s.introspection.standard_process(standard_introspection_request: Models::Components::StandardIntrospectionRequest.new(
  parameters: 'token=VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token'
))

unless res.standard_introspection_response.nil?
  # handle response
end

package main

import(
	"context"
	"os"
	authlete "github.com/authlete/authlete-go-sdk"
	"github.com/authlete/authlete-go-sdk/models/components"
	"github.com/authlete/authlete-go-sdk/models/operations"
	"log"
)

func main() {
    ctx := context.Background()

    s := authlete.New(
        authlete.WithServiceID("<id>"),
        authlete.WithSecurity(os.Getenv("AUTHLETE_BEARER")),
    )

    res, err := s.Introspection.StandardProcess(ctx, operations.AuthIntrospectionStandardAPIRequest{
        Body: components.StandardIntrospectionRequest{
            Parameters: "token=VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token",
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.StandardIntrospectionResponse != nil {
        // handle response
    }
}

curl --request POST \
  --url https://us.authlete.com/api/{serviceId}/auth/introspection/standard \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "parameters": "token=VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token"
}
'

{
  "resultCode": "A145001",
  "resultMessage": "[A145001] Introspection was performed successfully (type=access_token, active=true).",
  "action": "OK",
  "responseContent": "{\\\"sub\\\":\\\"john\\\",\\\"scope\\\":\\\"history.read timeline.read\\\",\\\"iss\\\":\\\"https://my-service.example.com\\\",\\\"active\\\":true,\\\"token_type\\\":\\\"Bearer\\\",\\\"exp\\\":1640416873,\\\"client_id\\\":\\\"26478243745571\\\"}"
}

{
  "resultCode": "A001201",
  "resultMessage": "[A001201] /auth/authorization, TLS must be used."
}

{
  "resultCode": "A001202",
  "resultMessage": "[A001202] /auth/authorization, Authorization header is missing."
}

{
  "resultCode": "A001215",
  "resultMessage": "[A001215] /auth/authorization, The client (ID = 26837717140341) is locked."
}

{
  "resultCode": "A001311",
  "resultMessage": "[A001311] /auth/authorization,  Too many requests, retry after 1 seconds. (Entity: 23769878923/87122303)"
}

{
  "resultCode": "A001101",
  "resultMessage": "[A001101] /auth/authorization, Authlete Server error."
}

Full description

This API is supposed to be called from within the implementations of the introspection endpoint of your service. The authorization server implementation should retrieve the value of action from the response and take the following steps according to the value. 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”. The value of responseContent is a JSON string which describes the error, so it can be used as the entity body of the response if you want. Note that, however, RFC 7662 does not mention anything about the response body of error responses.

The following illustrates an example response which the introspection endpoint of the authorization server implementation generates and returns to the client application.

HTTP/1.1 500 Internal Server Error
Content-Type: application/json
&#123;responseContent&#125;

BAD_REQUEST

When the value of action is BAD_REQUEST, it means that the request from the client application is invalid. This happens when the request from the client did not include the token request parameter. See “2.1. Introspection Request” in RFC 7662 for details about requirements for introspection requests. The HTTP status of the response returned to the client application should be “400 Bad Request”. The value of responseContent is a JSON string which describes the error, so it can be used as the entity body of the response if you want. Note that, however, RFC 7662 does not mention anything about the response body of error responses. The following illustrates an example response which the introspection endpoint of the authorization server implementation generates and returns to the client application.

HTTP/1.1 400 Bad Request
Content-Type: application/json
&#123;responseContent&#125;

OK

When the value of action is OK, the request from the client application is valid. The HTTP status of the response returned to the client application must be “200 OK” and its content type must be application/json. The value of responseContent is a JSON string which complies with the introspection response defined in “2.2. Introspection Response” in RFC7662.

The following illustrates the response which the introspection endpoint of your authorization server implementation should generate and return to the client application.

HTTP/1.1 200 OK
Content-Type: application/json
&#123;responseContent&#125;

Note that RFC 7662 says “To prevent token scanning attacks, the endpoint MUST also require some form of authorization to access this endpoint”. This means that you have to protect your introspection endpoint in some way or other. Authlete does not care about how your introspection endpoint is protected. In most cases, as mentioned in RFC 7662, “401 Unauthorized” is a proper response when an introspection request does not satisfy authorization requirements imposed by your introspection endpoint.

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

parameters

string

required

Request parameters which comply with the introspection request defined in "2.1. Introspection Request" in RFC 7662.

The implementation of the introspection endpoint of your authorization server will receive an HTTP POST [RFC 7231] request with parameters in the application/x-www-form-urlencoded format. It is the entity body of the request that Authlete's /api/auth/introspection/standard API expects as the value of parameters.

withHiddenProperties

boolean

Flag indicating whether to include hidden properties in the output.

Authlete has a mechanism whereby to associate arbitrary key-value pairs with an access token. Each key-value pair has a hidden attribute. By default, key-value pairs whose hidden attribute is set to true are not embedded in the standard introspection output.

If the withHiddenProperties request parameter is given and its value is true, `/api/auth/introspection/standard API includes all the associated key-value pairs into the output regardless of the value of the hidden attribute.

rsUri

string

The URI of the resource server making the introspection request.

If the rsUri request parameter is given and the token has audience values, Authlete checks if the value of the rsUri request parameter is contained in the audience values. If not contained, Authlete generates an introspection response with the active property set to false.

The rsUri request parameter is required when the resource server requests a JWT introspection response, i.e., when the value of the httpAcceptHeader request parameter is set to "application/token-introspection+jwt".

httpAcceptHeader

string

The value of the HTTP Accept header in the introspection request.

If the value of the httpAcceptHeader request parameter is "application/token-introspection+jwt", Authlete generates a JWT introspection response. See "4. Requesting a JWT Response" of "RFC 9701: JWT Response for OAuth Token Introspection" for more details.

introspectionSignAlg

string

The JWS alg algorithm for signing the introspection response. This parameter corresponds to introspection_signed_response_alg defined in "6. Client Metadata" of "RFC 9701: JWT Response for OAuth Token Introspection".

The default value is RS256.

introspectionEncryptionAlg

string

The JWE alg algorithm for encrypting the introspection response. This parameter corresponds to introspection_encrypted_response_alg defined in "6. Client Metadata" of "RFC 9701: JWT Response for OAuth Token Introspection".

If the introspectionEncryptionAlg request parameter is specified, Authlete generates a JWT introspection response encrypted with the algorithm by this property and the algorithm specified by the introspectionEncryptionEnc request parameter.

introspectionEncryptionEnc

string

The JWE enc algorithm for encrypting the introspection response. This parameter corresponds to introspection_encrypted_response_enc defined in "6. Client Metadata" of "RFC 9701: JWT Response for OAuth Token Introspection".

The default value is A128CBC_HS256.

sharedKeyForSign

string

The shared key for signing the introspection response with a symmetric algorithm.

The sharedKeyForSign request parameter is required when the introspection response is requested to be signed with a symmetric algorithm.

sharedKeyForEncryption

string

The shared key for encrypting the introspection response with a symmetric algorithm.

The sharedKeyForEncryption request parameter is required when the introspection response is requested to be encrypted with a symmetric algorithm.

publicKeyForEncryption

string

The public key for signing the introspection response with an asymmetric algorithm.

The publicKeyForEncryption request parameter is required when the introspection response is requested to be encrypted with an asymmetric algorithm.

Response

Token introspection completed successfully

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,

OK,

JWT

responseContent

string

The content that the authorization server implementation is to return to the client application.

​INTERNAL_SERVER_ERROR

​BAD_REQUEST

​OK

Authorizations

Path Parameters

Body

Response

INTERNAL_SERVER_ERROR

BAD_REQUEST

OK