Struct KeySet

pub struct KeySet { /* private fields */ }

Abstracts a remote Amazon Cognito JWKS key set

The key set represents the public key information for one or more RSA keys that Amazon Cognito uses to sign tokens. To verify a token from Cognito the token’s kid is used to look up the corresponding public key from this set which can be used to verify the token’s signature.

Building on top of the Verifier API from jsonwebtokens, a KeySet provides some helpers for building a Verifier for Cognito Access token claims or ID token claims - referencing the region and pool details used to construct the keyset.

Example:

let keyset = KeySet::new("eu-west-1", "my-user-pool-id")?;
let verifier = keyset.new_id_token_verifier(&["client-id-0", "client-id-1"])
    .string_equals("custom_claim0", "value")
    .string_equals("custom_claim1", "value")
    .build()?;
let claims = keyset.verify(token, &verifier).await?;

Internally a KeySet holds a cache of Algorithm structs (see the jsonwebtokens API for further details) where each Algorithm represents one RSA public key.

Although keyset.verify() can be very convenient, if you need to avoid network I/O when verifying tokens it’s also possible to prefetch the remote JWKS key set ahead of time and try_verify() can be used to verify a token without any network I/O. This can be useful if you don’t have an async context when verifying tokens.

let keyset = KeySet::new("eu-west-1", "my-user-pool-id")?;
keyset.prefetch_jwks().await?;
let verifier = keyset.new_id_token_verifier(&["client-id-0", "client-id-1"])
    .string_equals("custom_claim0", "value")
    .string_equals("custom_claim1", "value")
    .build()?;
let claims = keyset.try_verify(token, &verifier)?;

It’s also possible to perform cache lookups directly to access an Algorithm if you need to use the jsonwebtokens API directly:

let keyset = KeySet::new("eu-west-1", "my-user-pool-id")?;
keyset.prefetch_jwks().await?;

let verifier = keyset.new_id_token_verifier(&["client-id-0", "client-id-1"])
    .string_equals("custom_claim0", "value")
    .string_equals("custom_claim1", "value")
    .build()?;

let header = jwt::raw::decode_header_only(token)?;
if let Some(Value::String(kid)) = header.get("kid") {
    let alg = keyset.try_cache_lookup_algorithm(kid)?;
    let claims = verifier.verify(token, &alg)?;

    // Whoop!
} else {
    Err(jwt::error::Error::MalformedToken(jwt::error::ErrorDetails::new("Missing kid")))?;
};

Implementations

impl KeySet

pub fn new( region: impl Into<String>, pool_id: impl Into<String>, ) -> Result<Self, Error>

Constructs a key set that corresponds to a remote Json Web Key Set published by Amazon for a given region and Cognito User Pool ID.

pub fn new_id_token_verifier(&self, client_ids: &[&str]) -> VerifierBuilder

Returns a VerifierBuilder that has been pre-configured to validate an AWS Cognito ID token. This can be further configured for verifying other custom claims before calling .build() to create a Verifier

pub fn set_min_jwks_fetch_interval(&mut self, interval: Duration)

Set’s the minimum time between attempts to fetch the remote JWKS key set

By default this is one minute, to throttle requests in case there is a transient network problem

pub fn min_jwks_fetch_interval(&mut self) -> Duration

Get’s the minimum time between attempts to fetch the remote JWKS key set

pub fn new_access_token_verifier(&self, client_ids: &[&str]) -> VerifierBuilder

Returns a VerifierBuilder that has been pre-configured to validate an AWS Cognito access token. This can be further configured for verifying other custom claims before calling .build() to create a Verifier

pub fn try_cache_lookup_algorithm( &self, kid: &str, ) -> Result<Arc<Algorithm>, Error>

Looks for a cached Algorithm based on the given JWT token’s key ID (‘kid’)

This is a lower-level API in case you need to use the jsonwebtokens Algorithm API directly.

Returns an Arc<Algorithm> corresponding to the give key ID (kid) or returns a CacheMiss error if the Algorithm / key is not cached.

pub async fn verify( &self, token: &str, verifier: &Verifier, ) -> Result<Value, Error>

Verify a token’s signature and its claims

pub async fn verify_for_time( &self, token: &str, verifier: &Verifier, time_now: u64, ) -> Result<TokenData, Error>

Verify a token’s signature and its claims, given a specific unix epoch timestamp

pub fn try_verify( &self, token: &str, verifier: &Verifier, ) -> Result<Value, Error>

Try and verify a token’s signature and claims without performing any network I/O

To be able to verify a token in a synchronous context (but without blocking) this API lets you try and verify a token, and if the required Algorithm / key has not been cached yet then it will return a CacheMiss error.

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

Ensure the remote Json Web Key Set is downloaded and cached

Trait Implementations

impl Clone for KeySet

fn clone(&self) -> KeySet

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for KeySet

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.