usso 0.4.0

The usso provides a universal single sign-on (SSO) integration for microservices, making it easy to add secure, scalable authentication across different frameworks. This client simplifies the process of connecting any microservice to the USSO service.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

//! JWKS (JSON Web Key Set) fetching and caching.
//!
//! Provides both synchronous and asynchronous functions to fetch JWKS from a
//! remote URL. Keys are cached globally in a [`OnceLock`] so that multiple
//! token validations reuse the same key set without redundant HTTP calls.
//!
//! # Example
//!
//! ```rust,no_run
//! use usso::jwks::init_jwks_sync;
//!
//! init_jwks_sync("https://sso.usso.io/website/jwks.json").unwrap();
//! let keys = usso::jwks::get_jwk_keys().unwrap();
//! println!("Loaded {} keys", keys.keys.len());
//! ```

use crate::{exceptions::JwksError, schemas::Jwks};
use reqwest::header::{HeaderMap, HeaderValue, USER_AGENT};
use std::sync::OnceLock;

static JWKS_CACHE: OnceLock<Jwks> = OnceLock::new();

/// Fetch JWKS from a URL and store it in the global cache (blocking).
///
/// Must be called before [`get_jwk_keys`] or [`decode_token_with_jwks`](crate::core::decode_token_with_jwks).
pub fn init_jwks_sync(jwk_url: &str) -> Result<(), JwksError> {
    let jwks = fetch_jwks_sync(jwk_url)?;
    JWKS_CACHE
        .set(jwks)
        .map_err(|_| JwksError::InvalidJwksData("Failed to set JWKS cache".into()))?;
    Ok(())
}

/// Fetch JWKS from the given URL (blocking) without caching.
///
/// Sets a `User-Agent` header identifying the crate name, version, and repository.
pub fn fetch_jwks_sync(jwk_url: &str) -> Result<Jwks, JwksError> {
    let user_agent = format!(
        "{}/{} (+{})",
        env!("CARGO_PKG_NAME"),
        env!("CARGO_PKG_VERSION"),
        env!("CARGO_PKG_REPOSITORY")
    );

    let mut headers = HeaderMap::new();
    headers.insert(
        USER_AGENT,
        HeaderValue::from_str(&user_agent).expect("Invalid user agent header"),
    );

    // Build a blocking client.
    let client = reqwest::blocking::Client::builder()
        .default_headers(headers)
        .build()?;

    let response = client.get(jwk_url).send()?.error_for_status()?; // Ensures that non-200 responses are treated as errors

    let jwks: Jwks = response.json()?;

    if jwks.keys.is_empty() {
        return Err(JwksError::InvalidJwksData("No keys found in JWKS".into()));
    }

    Ok(jwks)
}

/// Fetch JWKS from a URL and store it in the global cache (async).
///
/// Must be called before [`get_jwk_keys`] or [`decode_token_with_jwks`](crate::core::decode_token_with_jwks).
pub async fn init_jwks_async(jwk_url: &str) -> Result<(), JwksError> {
    let jwks = fetch_jwks_async(jwk_url).await?;
    JWKS_CACHE
        .set(jwks)
        .map_err(|_| JwksError::InvalidJwksData("Failed to set JWKS cache".into()))?;
    Ok(())
}

/// Fetch JWKS from the given URL (async) without caching.
///
/// Sets a `User-Agent` header identifying the crate name, version, and repository.
pub async fn fetch_jwks_async(jwk_url: &str) -> Result<Jwks, JwksError> {
    let user_agent = format!(
        "{}/{} (+{})",
        env!("CARGO_PKG_NAME"),
        env!("CARGO_PKG_VERSION"),
        env!("CARGO_PKG_REPOSITORY")
    );

    let mut headers = HeaderMap::new();
    headers.insert(
        USER_AGENT,
        HeaderValue::from_str(&user_agent).expect("Invalid user agent header"),
    );

    let client = reqwest::Client::builder()
        .default_headers(headers)
        .build()?;

    let response = client.get(jwk_url).send().await?.error_for_status()?;

    let jwks: Jwks = response.json().await?;

    if jwks.keys.is_empty() {
        return Err(JwksError::InvalidJwksData("No keys found in JWKS".into()));
    }

    Ok(jwks)
}

/// Get a reference to the globally cached JWKS key set.
///
/// Returns `JwksError::NotInitialized` if [`init_jwks_sync`] or
/// [`init_jwks_async`] has not been called yet.
pub fn get_jwk_keys() -> Result<&'static Jwks, JwksError> {
    JWKS_CACHE.get().ok_or(JwksError::NotInitialized)
}