OAuth2 Introspection Authentication

# Introduction

OAuth2 Introspection authentication is used to verify the validity of an access token (such as a JWT). It allows the resource server to ask the authentication server for the validity of the token when it receives a request from a client. The authentication server validates the token and returns detailed information about the token, such as the owner, expiration date, and scope.

The purpose of OAuth2 Introspection authentication is to ensure that tokens circulate securely and that only authenticated clients can access protected resources. It is an effective token authentication technique suitable for protecting private and sensitive data.

The corresponding page rule actions are provided in OpenResty Edge to implement this functionality.

This action has the following parameters.

• Endpoint: API endpoint to verify token validity. It can receive the token and return detailed information about the token, such as whether it is valid, the associated user, and its permissions. This endpoint can be used to help verify that the token is legitimate to ensure that the requester has sufficient permissions to access a particular resource.
• Client ID: A unique identifier for the client application, which is used by the authorization server to identify the client.
• Client Secret: A shared password used to authenticate the client application. It is confidential and is used to prove the identity of the client application when a request is made to the authorization server. It is used to prevent unauthorized access to protected resources.
• SSL Verify: Specifies whether SSL verify is enabled when accessing the endpoint.

# Example

# Creating an endpoint

Since we need a endpoint, we create a new application on Edge to emulate the endpoint.

For this application, we check “Load application by IP addresses (no Host request header, no HTTPS support)” to avoid the need to bind a domain name and use the IP to access the application.

Then a new page rule is created, and when the prefix in the URI matches /oauth2-introspect, the correct information is returned:

Create another page rule that returns an error message intended to make OAuth2 Introspection authentication fail:

# Enable OAuth2 Introspection authentication

• The endpoint uses http://192.168.50.220/bad-oauth2-introspect, where 192.168.50.220 (for example only) is the IP of the Edge Node used in the example.
  • Note: The URI used here is /bad-oauth2-introspect, which means that it will hit the second-page rule of the endpoint and return the wrong token information.
• Both the client ID and the client secret key are used: openresty (for example only).
• SSL Verify: the demo uses HTTP instead of HTTPS, so this option can be turned off.

Then we send a test request.

$ curl http://test.com/anything -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmb28iOiJiYXIifQ._ FOTfoCTzKHWcBDYf1rfRkg-g6D_Mg8dnccLR_geCH0' -v
...
< HTTP/1.1 403 Forbidden
...

You can see that a 403 status code is returned, indicating that the endpoint did not pass the authentication.

Then modify the page rules to use the correct URI /oauth2-introspect:

Send the test request again.

$ curl http://test.com/anything -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmb28iOiJiYXIifQ._ FOTfoCTzKHWcBDYf1rfRkg-g6D_Mg8dnccLR_geCH0' -v
...
< HTTP/1.1 404 Not Found
...

404 was returned instead of 403, indicating that authentication was passed, but the request accessed a non-existent resource (/anything).