okta-jwt-verifier

The purpose of this library is to help with the verification of access and ID tokens issued by Okta. Check the API Docs for more details.

Minimum Supported Rust Version (MSRV)

1.73.0

Install

With cargo add installed :

cargo add okta-jwt-verifier

Examples

Minimal

This example attempts to retrieve the keys from the provided Okta authorization server, decodes the token header to identify the key id, attempts to find a matching key, attempts to decode the token, and finally attempts to deserialize the claims.

This method will attempt to retrieve the keys upon each request unless a cache feature is enabled.

use okta_jwt_verifier::{Verifier, DefaultClaims};

#[async_std::main]
async fn main() -> anyhow::Result<()> {
    let token = "token";
    let issuer = "https://your.domain/oauth2/default";

    Verifier::new(&issuer)
        .await?
        .verify::<DefaultClaims>(&token)
        .await?;
    Ok(())
}

Optional Configurations

This method will attempt to retrieve the keys using the provided endpoint (default: "/v1/keys")

use okta_jwt_verifier::{Config, Verifier, DefaultClaims};

#[async_std::main]
async fn main() -> anyhow::Result<()> {
    let token = "token";
    let issuer = "https://your.domain/oauth2/default";
    let config: Config =
            Config { keys_endpoint: Some("/oauth2/v1/keys".to_owned()) };
    Verifier::new_with_config(&issuer, config)
        .await?
        .verify::<DefaultClaims>(&token)
        .await?;
    Ok(())
}

This example shows the use of optional configurations for validation.

use okta_jwt_verifier::Verifier;
use serde::{Deserialize, Serialize};
use std::collections::HashSet;

// You can provide your own Claims struct or use the provided defaults
// This example matches okta_jwt_verifier::DefaultClaims
#[derive(Serialize, Deserialize)]
pub struct Claims {
    pub iss: String,
    pub sub: String,
    pub scp: Option<Vec<String>>,
    pub cid: Option<String>,
    pub uid: Option<String>,
    pub exp: u64,
    pub iat: u64,
}

let token = "token";
let issuer = "https://your.domain/oauth2/default";
let mut aud = HashSet::new();
aud.insert("api://default");
aud.insert("api://test");

let claims = Verifier::new(&issuer)
    .await?
    // An optional leeway (in seconds) can be provided to account for clock skew (default: 120)
    .leeway(0)
    // Optional audience claims can be provided to validate against
    .audience(aud)
    // Adding a single aud entry without building a HashSet manually
    .add_audience("api://dev")
    // An optional client ID can be provided to match against the cid claim
    .client_id("Bl3hStrINgiD")
    .verify::<Claims>(&token)
    .await?;
dbg!(&claims)

Key Caching

This example matches the basic example but would cache the keys on disk. Requires the cache-reqwest or cache-surf feature to be enabled (disabled by default). Creates an http-cacache directory relative to the working directory where the cache files will reside.

With cargo add installed :

For reqwest:

cargo add okta-jwt-verifier --features cache-reqwest

For surf:

cargo add okta-jwt-verifier --no-default-features  --features client-surf,cache-surf

Tide Middleware

This example implements the basic usage example as tide middleware.

ISSUER="https://your.domain/oauth2/default" cargo run --example tide_middleware_basic

Features

The following features are available. By default client-reqwest is enabled.

• client-reqwest feature that enables the reqwest client for remote requests. This is enabled by default.
• cache-reqwest feature that enables cache on disk to store keys when using the reqwest client (respects cache-control). This is disabled by default.
• client-surf feature that enables the surf client for remote requests. This is disabled by default.
• cache-surf feature that enables cache on disk to store keys when using the surf client (respects cache-control). This is disabled by default.

Documentation

• API Docs

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.