Introspect

The introspection endpoint in OpenID Connect (OIDC) allows clients to validate the current state of a token. This includes checking if a token is active, its expiration, the associated scopes, and other metadata. The introspection endpoint helps ensure that tokens are valid and have not been revoked or expired.

Endpoint Details

In the provided configuration, the introspection endpoint is:

"introspection_endpoint": "https://ed.link/api/authentication/oidc/introspect"

How to Use the Introspection Endpoint

The following steps outline how to use the introspection endpoint to validate tokens:

1. Prepare the Introspection Request

To use the introspection endpoint, you need to send a POST request with the necessary parameters. Here’s a breakdown of the required parameters:

• token: The token that you want to introspect (access token or refresh token).
• Authorization: Basic authentication header containing the base64 encoded client_id and client_secret.

2. Construct the Introspection Request

Here is an example of how to construct the introspection request using axios in Node.js:

const axios = require('axios');
const qs = require('qs');

// Construct the request data
let data = qs.stringify({
    token: 'YOUR_TOKEN',
    token_type_hint: 'refresh_token' // Use 'access_token' if you are introspecting an access token
});

// Set up the request configuration
let config = {
    method: 'post',
    url: 'https://ed.link/api/authentication/oidc/introspect',
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        Authorization: 'Basic ' + Buffer.from('YOUR_CLIENT_ID:YOUR_CLIENT_SECRET').toString('base64')
    },
    data: data
};

// Send the request
axios
    .request(config)
    .then((response) => {
        console.log(JSON.stringify(response.data));
    })
    .catch((error) => {
        console.log(error);
    });

Replace the placeholders with your actual values:

• YOUR_TOKEN: The token you want to introspect.
• YOUR_CLIENT_ID: Your registered client ID.
• YOUR_CLIENT_SECRET: Your client secret.

3. Send the Introspection Request

The request above sends a POST request to the introspection endpoint with the required parameters and authorization header.

4. Handle the Introspection Response

Based on the code provided, the introspection response will look like this:

{
    "iss": "https://ed.link/api/authentication/oidc",
    "client_id": "YOUR_CLIENT_ID",
    "active": true,
    "scope": "openid profile email",
    "sub": "1234567890",
    "iat": 1629476400,
    "exp": 1629480000
}

• iss: The issuer of the token.
• client_id: The client ID associated with the token.
• active: Indicates whether the token is currently active.
• scope: The scopes associated with the token.
• sub: The subject identifier for the token's owner.
• iat: The time the token was issued (in seconds since epoch).
• exp: The expiration time of the token (in seconds since epoch).

If the token is inactive or invalid, the response will indicate that the token is inactive:

{
    "active": false
}

5. Use the Token Information

Based on the introspection response, you can decide whether to accept the token. If the token is active and valid, you can proceed with your application's logic. If the token is inactive, you may need to reject the request and prompt the user to reauthenticate.

Error Handling

If an error occurs during the introspection process, the endpoint will handle it as follows:

1. Invalid Token: If the token is invalid, expired, or revoked, the response will indicate that the token is inactive:

   {
       "active": false
   }
   

2. Server Error: If there is an error, the response will indicate the error:

   {
       "$error": "There was an error introspecting your token."
   }
   

Example Flow

1. Receive a Request: Your application receives a request that includes an access token.
2. Introspect the Token: Send the token to the introspection endpoint to check its validity.
3. Handle the Response: Based on the introspection response, determine if the token is active and valid.
4. Proceed or Reject: If the token is valid, proceed with the request. If the token is invalid, reject the request and handle it accordingly (e.g., prompt for reauthentication).

Conclusion

Using the introspection endpoint involves sending a POST request with the token and client credentials, and then interpreting the response to determine the token's validity. This helps ensure that tokens used in your application are active and authorized.