Crate axum_security_oauth2

Expand description

A minimal OAuth2 client for the authorization code flow (RFC 6749), written for the axum-security family but usable on its own.

Compared to the oauth2 crate this one has no typestate and no type parameters: configuration is validated once at build(), so client calls only fail for reasons that can occur at request time. PKCE (RFC 7636) is on for the default start_login/ finish_login pair; explicit _non_pkce variants exist for providers that reject the PKCE parameters. Values are plain String, url::Url or std::time::Duration, with one wrapper: CsrfToken, whose == compares in constant time. Secrets stay out of logs because every crate type that holds one (the client, Login, Tokens, CsrfToken, errors) redacts it in its Debug output — but a secret you store is a plain string, so keep it out of your own Debug/Display impls.

§Features

reqwest (default) — the reqwest backend for the HttpClient enum, plus a default client (no redirects, 10s timeout). Without any backend feature try_build fails with ConfigError::NoHttpClient.
rustls (default) — TLS for the reqwest backend via rustls.
native-tls — TLS for the reqwest backend via the platform’s native TLS library.

§Example

use axum_security_oauth2::OAuth2Client;

// Provider shortcuts (github, google, microsoft, gitlab, discord, spotify, twitch)
// preset the endpoints; OAuth2Client::builder() takes them explicitly.
let client = OAuth2Client::github()
    .client_id("my-client-id")
    .client_secret("my-client-secret")
    .redirect_url("https://my-app.example/callback")
    .scopes(&["read:user"])
    .build(); // or try_build() to handle ConfigError

// Leg 1: redirect the user to `login.url`; persist the CSRF token
// and PKCE verifier (e.g. in a signed cookie) for the callback.
let login = client.start_login();
// Fields are owned and public — move them out, no clone needed.
let (url, csrf_token, pkce_verifier) = (login.url, login.csrf_token, login.pkce_verifier);

// Leg 2 (on the callback route): compare `csrf_token` with the `state`
// query parameter (constant-time via `==`), then exchange the code.
let state = "state-from-the-query-string";
assert!(csrf_token == state); // reject the callback if this fails
let code = "code-from-the-query-string";
let tokens = client.finish_login(code, &pkce_verifier).await?;
let _access_token = &tokens.access_token;

// Later: trade the refresh token for fresh tokens (RFC 6749 §6).
if let Some(refresh_token) = &tokens.refresh_token {
    let fresh = client.refresh_tokens(refresh_token).await?;
    let _fresh_access_token = &fresh.access_token;
}

Per-login extras (an oidc nonce, prompt, …) go through start_login_with; providers that only take credentials in the request body are served by AuthType::RequestBody.

Structs§

CsrfToken: The CSRF token embedded in the authorization URL’s state parameter.
HttpError: A transport-level failure; source returns the backend’s error.
HttpResponse: The response from HttpClient::get: the HTTP status and the raw body.
Login: The first leg of the authorization code flow, created by start_login.
LoginNonPkce: The first leg of the authorization code flow without PKCE, created by start_login_non_pkce.
LoginOptions: Per-login options for start_login_with and start_login_non_pkce_with.
OAuth2Client: An OAuth2 client for the authorization code flow with PKCE (RFC 6749 §4.1 + RFC 7636).
OAuth2ClientBuilder: Builds an OAuth2Client. Created with OAuth2Client::builder() or a provider shortcut (OAuth2Client::github(), google(), …) that presets the endpoints.
ParseError: A response body that could not be parsed.
ServerError: A well-formed OAuth2 error body from the server (RFC 6749 §5.2), plus the HTTP status it arrived with.
Tokens: A successful token-endpoint response (RFC 6749 §5.1).

Enums§

AuthType: How the client authenticates to the token endpoint (RFC 6749 §2.3.1).
ConfigError: Errors from OAuth2ClientBuilder::try_build.
Error: Errors returned by OAuth2Client calls.
ErrorCode: The error code of an RFC 6749 §5.2 error body.
HttpClient: The HTTP backend used for token requests.

Functions§

random_token: A cryptographically random token: 32 bytes from the OS CSPRNG, base64url-nopad encoded (43 characters).