#jwt #axum #keycloak #oidc #error-response

axum-keycloak-auth

Protect axum routes with a JWT emitted by Keycloak

8 releases (4 breaking)

0.5.0 Feb 2, 2024
0.4.1 Jan 30, 2024
0.3.0 Dec 21, 2023
0.2.0 Oct 20, 2023
0.1.1 Feb 27, 2023

#150 in Authentication

Download history 4/week @ 2023-12-22 50/week @ 2023-12-29 197/week @ 2024-01-05 47/week @ 2024-01-12 36/week @ 2024-01-19 15/week @ 2024-01-26 22/week @ 2024-02-02 17/week @ 2024-02-09 55/week @ 2024-02-16 58/week @ 2024-02-23 40/week @ 2024-03-01 16/week @ 2024-03-08 24/week @ 2024-03-15 18/week @ 2024-03-22 44/week @ 2024-03-29 46/week @ 2024-04-05

132 downloads per month

MIT/Apache

77KB
1K SLoC

axum-keycloak-auth

Protect axum routes with a JWT emitted by Keycloak.

Features

  • Tower layer / service that can be attached to axum routers.
  • Automatic OIDC discovery
  • Forwarding only requests providing a verifiable and non-expired JWT.
  • Ability to allow forwarding a failed authentication attempt to possibly handle the authentication using another middleware.
  • Ability to access the extracted JWT data (including roles, the KC uuid, ...) in route handler function.
  • Tests to check that one or more required or forbidden Keycloak realm or client roles were included in the JWT.
  • Ability to access the JWT's raw claims in a handler, allowing to extract custom attributes.
  • An error type implementing IntoResponse providing exact information about why authentication failed in an error response.
  • Ability to define a custom role type from your application to which all roles are automatically parsed.

Planned

  • Ability to provide a custom type into which the token is parsed, with which non-standard JWT claims can be extracted without overhead.
  • Allowing fine-grained control over how an AuthError is converted into a response. Giving the user control and the ability to add context, roll their own.

Usage

This library provides KeycloakAuthLayer, a tower layer/service implementation that parses and validates a JWT.

See the Documentation for more detailed instructions!

enum Role {
    Administrator,
    Unknown(String),
}

pub fn protected_router(instance: KeycloakAuthInstance) -> Router {
    Router::new()
        .route("/protected", get(protected))
        .layer(
             KeycloakAuthLayer::<Role>::builder()
                 .instance(instance)
                 .passthrough_mode(PassthroughMode::Block)
                 .build(),
        )
}

pub async fn protected(Extension(token): Extension<KeycloakToken<Role>>) -> Response {
    expect_role!(&token, Role::Administrator);

    info!("Token payload is {token:#?}");
    (
        StatusCode::OK,
        format!(
            "Hello {name} ({subject}). Your token is valid for another {valid_for} seconds.",
            name = token.extra.profile.preferred_username,
            subject = token.subject,
            valid_for = (token.expires_at - time::OffsetDateTime::now_utc()).whole_seconds()
        ),
    ).into_response()
}

Axum compatibility

axum axum-keycloak-auth
0.6 0.2
0.7 0.3 - 0.5

Dependencies

~9–24MB
~376K SLoC