Contact Us 1-800-596-4880
  1. Homepage
  2. Omni Gateway Policy Development Kit (PDK) (1.10)
  3. Developing Custom Policies
  4. Implementing Your Custom Policy Features in Rust

  5. Using OAuth 2.0 Token Introspection Library Functions

Using OAuth 2.0 Token Introspection Library Functions

To view an example policy project that uses Omni Gateway Policy Development Kit (PDK)'s Token Introspection feature, see OAuth 2.0 Token Introspection Policy Example.

Use the Omni Gateway Policy Development Kit (PDK) Token Introspection library functions to validate incoming OAuth 2.0 tokens with an upstream introspection service.

Configure the Token Validator

To access OAuth 2.0 Token Introspection functionality, you must import the token_introspection module from the PDK crate and inject the TokenValidatorBuilder in the configure function.

use pdk::token_introspection::{IntrospectionResult, ParsedToken, ScopesValidator, TokenValidator, TokenValidatorBuilder};

#[entrypoint]
async fn configure(
    launcher: Launcher,
    Configuration(bytes): Configuration,
    validator_builder: TokenValidatorBuilder,
) -> Result<()> {
// [...]
// Create a token validator
let mut validator_instance = validator_builder
        .new("token-cache")
        .with_path("/introspect")
        .with_authorization_value("Basic YWRtaW46YWRtaW4=") //  Choose either authorization value or client ID and secret depending on your service authorization. No authorization header is sent if with_authorization_value() isn't defined.
        .with_client_id("client-id") // Client ID and secret are sent as form params in the body of the request
        .with_client_secret("client-secret")
        .with_expires_in_attribute("exp")
        .with_max_token_ttl(600)
        .with_timeout_ms(10000)
        .with_max_cache_entries(10000)
        .with_scopes_validator(ScopesValidator::all(scopes_vector))
        .with_service(config.my_service)
        .with_protected_resource_metadata(config.auth_server_url) // Choose .with_protected_resource_metadata_with_properties() if additional properties are required

        .build();
// [...]
}

The TokenValidatorBuilder provides these methods to configure the token validator. You must call with_service before build, all other methods are optional:

Method Parameter Default Description

with_path

path (impl Into<String>)

"/"

Sets the introspection endpoint path.

with_authorization_value

value (impl Into<String>)

"" (Auth header with an empty value)

Sets the authorization header value for introspection requests.

with_client_id

value (impl Into<String>)

No default

Sets the client ID credential to talk with the introspection service.

with_client_secret

value (impl Into<String>)

No default

Sets the client secret credential to talk with the introspection service.

with_expires_in_attribute

attr (impl Into<String>)

"exp"

Sets the attribute name for expiration time in the introspection response.

with_max_token_ttl

ttl (i64)

-1 (no cap)

Sets the maximum token TTL in seconds; tokens with a longer TTL are treated as expired. Use -1 for no limit.

with_timeout_ms

timeout (u64)

10000 (10 s)

Sets the timeout for introspection requests in milliseconds.

with_max_cache_entries

max_entries (usize)

1000

Sets the maximum number of entries in the token cache.

with_scopes_validator

validator (ScopesValidator)

No default

Sets the scopes validator for token validation (for example, ScopesValidator::all(scopes_vector)).

with_service

service (Service)

No default (required)

Sets the OAuth2 introspection service endpoint. Required to build the validator.

with_protected_resource_metadata

authorization server url (impl Into<String>)

No default

Enables RFC 9728 protected resource discovery with the given authorization server URL. The well-known endpoint path and resource URL are derived automatically from the API base path extracted from PDK metadata when the policy is applied.

with_protected_resource_metadata_with_properties

authorization server url (impl Into<String>), additional properties (Value)

No default

Enables RFC 9728 protected resource discovery with the given authorization server URL and additional metadata properties (such as scopes_supported or bearer_methods_supported). The well-known endpoint path and resource URL are derived automatically from the API base path extracted from PDK metadata when the policy is applied.
The configure function receives the configuration parameters defined in your policy schema.

Validate a Token

Once configured, the validator provides the validate function, that expects a token string. The validate function sends a request to the introspection endpoint and returns the IntrospectionResult:

// extract token from header
let auth_header = handler.header("Authorization");
let token = auth_header.split_whitespace()[1];

let result = validator
        .validate(&token)
        .await
        .map_err(PolicyError::Introspection)?;

See Also