Struct RemoteJwksDecoder

Source

pub struct RemoteJwksDecoder { /* private fields */ }

Expand description

JWT decoder that fetches and caches keys from a remote JWKS endpoint.

Automatically fetches JWKS from the specified URL, caches keys by their kid (key ID), and periodically refreshes them in the background. Includes retry logic for robustness.

§Example

use axum_jwt_auth::RemoteJwksDecoder;
use jsonwebtoken::{Algorithm, Validation};

let decoder = RemoteJwksDecoder::builder()
    .jwks_url("https://example.com/.well-known/jwks.json".to_string())
    .validation(Validation::new(Algorithm::RS256))
    .build()
    .unwrap();

// Initialize: fetch keys and start background refresh task
decoder.initialize().await.unwrap();

Implementations§

Source §

impl RemoteJwksDecoder

Source

pub fn new(jwks_url: String) -> Result<Self, Error>

Creates a new RemoteJwksDecoder with the given JWKS URL and default settings.

§Errors

Returns Error::Configuration if the builder fails to construct the decoder.

Source

pub fn builder() -> RemoteJwksDecoderBuilder

Creates a new builder for configuring a remote JWKS decoder.

Source

pub async fn initialize(&self) -> Result<CancellationToken, Error>

Performs an initial fetch of JWKS keys and starts the background refresh task.

This method should be called once after construction. It will:

Immediately fetch keys from the JWKS endpoint
Spawn a background task to periodically refresh keys

Returns a CancellationToken that can be used to gracefully stop the background refresh task.

§Errors

Returns an error if the initial fetch fails after all retry attempts.

§Example

let decoder = RemoteJwksDecoder::builder()
    .jwks_url("https://example.com/.well-known/jwks.json".to_string())
    .validation(Validation::new(Algorithm::RS256))
    .build()?;

// Fetch keys and start background refresh
let shutdown_token = decoder.initialize().await?;

// Later, during application shutdown:
shutdown_token.cancel();

Source

pub async fn refresh(&self) -> Result<(), Error>

Manually triggers a JWKS refresh with retry logic.

Useful for forcing an update outside the normal refresh cycle.

§Errors

Returns an error if the refresh fails after all retry attempts.

Source

pub async fn refresh_keys_periodically(&self, shutdown_token: CancellationToken)

Runs a loop that periodically refreshes the JWKS cache until cancelled.

This method should be spawned in a background task using tokio::spawn. Refresh failures are logged, and the decoder continues using stale keys until the next successful refresh.

The loop will exit gracefully when the shutdown_token is cancelled.

§Example

use tokio_util::sync::CancellationToken;

let decoder = RemoteJwksDecoder::builder()
    .jwks_url("https://example.com/.well-known/jwks.json".to_string())
    .build()
    .unwrap();

let shutdown_token = CancellationToken::new();
let decoder_clone = decoder.clone();
let token_clone = shutdown_token.clone();

tokio::spawn(async move {
    decoder_clone.refresh_keys_periodically(token_clone).await;
});

// Later, to stop the refresh task:
shutdown_token.cancel();