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.88.0

The cache-reqwest feature requires 1.90.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.

The keys will be retrieved from the issuer when the Verifier is constructed, and will be retrieved again if a token presents a key id that was not found. See Key Caching to cache the keys on disk.

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,rust_crypto

Axum Middleware

This example implements the basic usage example as axum middleware.

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

Multiple Issuers

This example verifies a token against multiple issuers.

ISSUERS="https://your.domain/oauth2/default,https://other.domain/oauth2/default" TOKEN="token" cargo run --example multi_issuer

Features

The following features are available. By default client-reqwest and rust_crypto are 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.
• rust_crypto feature that enables the rust_crypto backend of jsonwebtoken for verifying tokens. This is enabled by default.
• aws_lc_rs feature that enables the aws_lc_rs backend of jsonwebtoken for verifying tokens. This is disabled by default.

Note the reqwest client is compiled without a TLS backend. To connect to an issuer over https a TLS feature must be enabled on the reqwest dependency used by your project, such as rustls or native-tls: cargo add reqwest --features rustls.

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.