BetterIAM
Rust

axum

Serve the Better IAM API from an axum app with the IamTower layer, read the session with the IamRequest extractor, and guard routes with require_session and authorize.

IamTower from better_iam::middleware (the better-iam-middleware crate) connects a Rust BetterIam instance to an axum application. It is a tower layer, the Rust counterpart of the Express adapter: one layer serves the IAM HTTP API under /api/iam and gives every other request an IamRequest with the caller's , permission checks, and an in-process client. Route guards (require_session, authorize) refuse signed-out callers, callers without a permission, and cross-site form posts. Refusals become the IAM JSON error envelope, or a redirect to your login page for page navigations.

Not on crates.io yet

The Rust crates are installed from a checkout of the repository. See the Rust overview for the current parity status.

Installation

Add the dependency

Cargo.toml
[dependencies]
better-iam = { path = "../better-iam/crates/better-iam", features = ["axum"] }
axum = "0.8"
tokio = { version = "1", features = ["rt-multi-thread", "macros", "net"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"

The umbrella's axum feature turns on its middleware module (better_iam::middleware, the better-iam-middleware crate) with the axum integration, built against axum 0.8. With only the middleware feature, IamTower is still a plain tower layer for hyper or any other tower-based server.

Create the instance

Create the instance once, as in Create the instance, and share it as an Arc<BetterIam>.

src/iam.rs
use std::sync::Arc;

use better_iam::adapter_sqlite::{SqliteAdapterOptions, sqlite_adapter};
use better_iam::{BetterIam, BetterIamOptions, IamError, IamStore, better_iam};

pub async fn create_iam() -> Result<Arc<BetterIam>, IamError> {
    let store: Arc<dyn IamStore> = sqlite_adapter(SqliteAdapterOptions::new("./better-iam.db"))?;
    let secret = std::env::var("BETTER_IAM_SECRET")
        .map_err(|_| IamError::new("MISSING_ENV", "Set BETTER_IAM_SECRET"))?;
    let iam = better_iam(BetterIamOptions::new(store, secret, "http://localhost:3000"))?;
    iam.initialize().await?;
    Ok(Arc::new(iam))
}

Add the layer

IamTower::new(iam, options) takes the instance (an Arc<BetterIam>, or a lazy IamSource) and the options. Install iam_tower.layer() with Router::layer after your routes, so it wraps all of them, and install guards with route_layer, so route parameters are known when they run.

src/main.rs
use std::sync::Arc;

use axum::Router;
use axum::routing::get;
use better_iam::BetterIam;
use better_iam::middleware::layer::{IamLayerOptions, IamTower};

mod iam;
mod routes;

fn app(iam: Arc<BetterIam>) -> Router {
    let iam_tower = IamTower::new(
        iam,
        IamLayerOptions {
            login_path: Some("/login".into()), // signed-out page navigations go here with ?next=
            step_up_path: Some("/verify".into()), // page navigations that must step up go here
            ..IamLayerOptions::default()
        },
    );
    Router::new()
        .route("/me", get(routes::me).route_layer(iam_tower.require_session(None)))
        .layer(iam_tower.layer())
}

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let iam = iam::create_iam().await.expect("Better IAM failed to start");
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await?;
    axum::serve(listener, app(iam)).await
}
  • The API mount. Requests under the base path (/api/iam) are answered by the IAM server through its node transport, before your routes and extractors run. The layer reads the body itself, up to the server's limit.
  • Protocol mounts outside the base path, such as /oauth or /.well-known, need their prefixes in serve: Some(vec!["/api/iam".into(), "/oauth".into(), "/.well-known".into()]) (see Protocol mounts).
  • Cookies. Set-Cookie headers the helpers receive during a request (from sign-in or sign-out) are added to that request's response.

Protect routes

Guards are tower layers built by the IamTower. Each one reads the session, checks when asked, then checks authorization and the CSRF rule, and answers a refusal itself: a 401 or 403 JSON envelope for API calls, or a 303 redirect to login_path or step_up_path for page navigations (a GET with Accept: text/html).

Require a session

src/routes.rs
use axum::Json;
use better_iam::BetterIam;
use better_iam::middleware::{IamRequest, MiddlewareError};
use serde_json::{Value, json};

pub type Iam = IamRequest<BetterIam>;

pub async fn me(iam: Iam) -> Result<Json<Value>, MiddlewareError> {
    let session = iam.require_session(None).await?;
    Ok(Json(json!({
        "email": session["identity"]["email"],
        "tenantId": session["session"]["tenantId"],
        "mfa": session["session"]["mfa"],
    })))
}
Router::new().route("/me", get(me).route_layer(iam_tower.require_session(None)))

A signed-out API call gets 401 with { "error": { "code": "UNAUTHENTICATED", "message": "A session is required" } } and Cache-Control: no-store. A signed-out page navigation to /me?tab=1 is redirected to /login?next=%2Fme%3Ftab%3D1.

IamRequest<T> is an axum extractor. It is available on every route under the layer, guarded or not; a route outside the layer fails with a 500 ("The Better IAM layer is not installed on this route").

Require a permission

iam_tower.authorize(rule, step_up) requires a session allowed to perform the rule's action. AuthorizeRule::new targets the tenant itself (iam/{tenantId}) in the session's tenant; .resource(...) and .tenant_id(...) derive them from the request head and the session. path_param(parts, name) reads a route parameter.

src/main.rs
use axum::Json;
use axum::extract::Path;
use better_iam::middleware::axum::path_param;
use better_iam::middleware::{AuthorizeRule, ResourceRef};
use serde_json::{Value, json};

async fn project(Path(id): Path<String>) -> Json<Value> {
    Json(json!({ "id": id }))
}

let read_project = AuthorizeRule::new("projects:read").resource(|parts, _session| ResourceRef {
    kind: "project".into(),
    id: path_param(parts, "id").unwrap_or_default(),
});

Router::new()
    .route("/projects/{id}", get(project).route_layer(iam_tower.authorize(read_project, None)))
    .route(
        "/admin/people",
        get(people).route_layer(iam_tower.authorize(AuthorizeRule::new("iam:identities:read"), None)),
    )

The check runs through iam.require, so it evaluates the same , , , and as every other check. A denial answers 403 ACCESS_DENIED. For callbacks that must await something, use resource_async and tenant_id_async, which take a ResourceFn or TenantFn returning a boxed future.

ResourceRef here is { kind, id } (serialized as { "type", "id" }); the tenant comes from the rule or the session.

Require step-up

Pass a StepUpRequirement: mfa: Some(StepUpMfa::On) needs a session that completed MFA, StepUpMfa::Fresh also refuses remembered devices, impersonation, assumed roles, and API keys, and max_age_ms needs a recent sign-in.

src/main.rs
use axum::routing::post;
use better_iam::middleware::{AuthorizeRule, StepUpMfa, StepUpRequirement};

let recent_mfa = StepUpRequirement { mfa: Some(StepUpMfa::On), max_age_ms: Some(10.0 * 60.0 * 1000.0) };

Router::new().route(
    "/billing/cancel",
    post(cancel_subscription)
        .route_layer(iam_tower.authorize(AuthorizeRule::new("billing:manage"), Some(recent_mfa))),
)

A session that fails the requirement gets 403 with MFA_REQUIRED, RECENT_AUTH_REQUIRED, or IMPERSONATION_RESTRICTED. Page navigations go to step_up_path?next=...&reason=mfa|recent|impersonation. Inside a handler, the same check is iam.require_session(Some(&requirement)). See Step-up for completing the challenge.

Enforce inside a handler

When the resource is only known after loading data, enforce inside the handler with iam.require(action, resource, tenant_id). It fails with the server's refusal, which the handler returns as a MiddlewareError.

src/routes.rs
use axum::Json;
use axum::extract::Path;
use better_iam::middleware::{MiddlewareError, ResourceRef};
use serde_json::{Value, json};

pub async fn delete_document(iam: Iam, Path(id): Path<String>) -> Result<Json<Value>, MiddlewareError> {
    let document = ResourceRef { kind: "document".into(), id: id.clone() };
    iam.require("documents:delete", Some(document), None).await?;
    Ok(Json(json!({ "deleted": id })))
}

MiddlewareError implements IntoResponse: a refusal becomes the JSON envelope with its status (and, through the layer, a redirect for page navigations), and any other error is logged and answered with a plain 500. It converts from IamError and IamRequestError, so ? works on both.

Cross-site requests

Guards refuse a cookie-authenticated POST, PUT, PATCH, or DELETE whose Origin is not the app itself, the IAM origin, or one of trusted_origins (403 UNTRUSTED_ORIGIN, or 403 CSRF_REJECTED with no Origin). A Sec-Fetch-Site: same-origin request passes, and bearer-token requests skip the check. A state-changing route without a guard can run the same rule with check_request_origin. See The CSRF check for why it matters with SameSite=Lax cookies.

Read the session

IamRequest is created once per request. It memoizes the session lookup, and cookies the in-process client receives count for later calls in the same request. The session is the JSON that auth.getSession returns (a serde_json::Value with identity and session).

Get the session

get_session() returns Ok(None) instead of failing when the request has no usable session: no credential, or the server answers UNAUTHENTICATED, MFA_REQUIRED, EMAIL_UNVERIFIED, TENANT_INACTIVE, or TENANT_UNAVAILABLE. require_session(step_up) returns the session or fails with an IamRequestError (401, or 403 with a reason).

src/routes.rs
use axum::response::{IntoResponse, Redirect, Response};

pub async fn home(iam: Iam) -> Result<Response, MiddlewareError> {
    let Some(session) = iam.get_session().await? else {
        return Ok(Redirect::to("/login").into_response());
    };
    Ok(Json(json!({ "name": session["identity"]["name"] })).into_response())
}

Route: POST /api/iam/auth/getSession

Check permissions for rendering

can(action, resource, tenant_id) returns an boolean. Checks made together share one authorizeMany call, so a page with many buttons costs one round trip.

src/routes.rs
pub async fn toolbar(iam: Iam, Path(id): Path<String>) -> Result<Json<Value>, MiddlewareError> {
    let project = ResourceRef { kind: "project".into(), id };
    let (edit, delete) = tokio::join!(
        iam.can("projects:update", Some(project.clone()), None),
        iam.can("projects:delete", Some(project), None),
    );
    Ok(Json(json!({ "canEdit": edit?, "canDelete": delete? })))
}

authorize(checks, tenant_id) returns an AuthorizeResult (action, resource, allowed, reason) per check. Advisory checks decide what to show; enforce the operation itself with a guard or iam.require.

Filter lists

plan(PlanInput { action, kind, tenant_id }) returns the resources of a type the caller may act on as a filter for your own query (never when signed out); compile it with the filter compilers of better_iam::core, such as filter_to_sql. list_accessible(ListAccessibleInput { .. }) lists registered resources of a managed type. See Data filtering for the plan format.

Sign in and out

iam.client() is an in-process client whose transport is the IAM handler, so the cookies the server issues land on this response. A plain HTML form can sign someone in without client JavaScript.

src/routes.rs
use axum::Form;
use axum::response::Redirect;
use better_iam::middleware::safe_redirect_path;

#[derive(serde::Deserialize)]
pub struct LoginForm {
    tenant_id: String,
    email: String,
    password: String,
    next: Option<String>,
}

pub async fn login(iam: Iam, Form(form): Form<LoginForm>) -> Result<Redirect, MiddlewareError> {
    let result = iam
        .client()
        .call("auth", "signIn", json!({ "tenantId": form.tenant_id, "email": form.email, "password": form.password }))
        .await?;
    if result["mfaRequired"] == json!(true) {
        let challenge = result["challenge"].as_str().unwrap_or_default();
        return Ok(Redirect::to(&format!("/verify?challenge={challenge}")));
    }
    Ok(Redirect::to(&safe_redirect_path(form.next.as_deref(), "/")))
}

pub async fn logout(iam: Iam) -> Result<Redirect, MiddlewareError> {
    iam.sign_out().await?; // ends the session and clears its cookie; never fails for a dead session
    Ok(Redirect::to("/"))
}

Route: POST /api/iam/auth/signIn, POST /api/iam/auth/signOut

The in-process client works on JSON (call(group, method, input) and request(path, input) return a serde_json::Value). safe_redirect_path accepts only same-site paths and falls back to the default you give, so ?next= cannot become an open redirect. A failed sign-in fails with the server's error (for example INVALID_CREDENTIALS or RATE_LIMITED).

Call the server API directly

iam.credential() returns the CredentialInput for direct iam.api.* calls, including cookies set earlier in the same request. Keep the Arc<BetterIam> in axum state, or resolve it from the request with iam_tower.resolve().

src/routes.rs
use std::sync::Arc;

use axum::extract::{Path, State};
use better_iam::server::api::Body;
use better_iam::types::api::identities;

pub async fn members(
    State(server): State<Arc<BetterIam>>,
    iam: Iam,
    Path(tenant_id): Path<String>,
) -> Result<Json<Value>, MiddlewareError> {
    let people = server
        .api
        .identities
        .list(&iam.credential(), Body::typed(&identities::ListInput { tenant_id, ..Default::default() }))
        .await?
        .into_value()?;
    Ok(Json(people))
}

Register it with .route("/orgs/{tenant_id}/members", get(members)).with_state(iam.clone()) before .layer(iam_tower.layer()).

Route: POST /api/iam/identities/list

Options

IamLayerOptions:

FieldTypeDefaultDescription
login_pathOption<String>NoneWhere signed-out page navigations are redirected, with ?next=. Without it they get the JSON 401
step_up_pathOption<String>NoneWhere page navigations go when the session must step up, with ?next= and ?reason=. Without it they get the JSON 403
serveOption<Vec<String>>the base pathPath prefixes the IAM server answers. Add protocol mounts outside the base path, such as /oauth or /.well-known
base_pathOption<String>the instance's endpoint.basePath, else /api/iamWhere the IAM API is served; the default serve prefix and the in-process client's target
trusted_originsVec<String>emptyOrigins besides the request's own and the IAM origin that may send cookie-authenticated unsafe requests to guarded routes
csrfbooltrueCheck the Origin of cookie-authenticated unsafe requests in guards
nowOption<Arc<dyn Fn() -> f64 + Send + Sync>>the system clockThe clock for step-up recency checks, in milliseconds, for tests

IamTower:

MethodWhat it does
layer()The layer that serves the API under the serve prefixes and attaches IamRequest to every other request
require_session(step_up)A guard layer requiring a session, and a step-up when given
authorize(rule, step_up)A guard layer requiring a session allowed to perform rule.action
guard(spec)A guard layer for any GuardSpec { step_up, authorize }
helpers(&mut parts)The per-request helpers of a request head
resolve()Resolves the instance

IamRequest:

MethodReturns
get_session()Option<Value>: the session, or None when signed out
require_session(step_up)The session, or a 401 / 403 refusal
require(action, resource, tenant_id)(), or the server's refusal
can(action, resource, tenant_id)An advisory bool, batched per request
authorize(checks, tenant_id)Vec<AuthorizeResult>
plan(input)The query plan as JSON
list_accessible(input){ resources, total } as JSON
assertion(&input)A short-lived signed assertion about the caller for a downstream service
client()The in-process client
sign_out()Ends the session and clears its cookie
credential(), headers(), url()The request's credential, headers (with cookies set during the request), and URL

Any BetterIam, or a value that borrows one (Arc<BetterIam>, your application state with Borrow<BetterIam>), implements the IamLike trait the layer works with. Another implementation of the trait can stand in for tests.

Errors

CodeStatusWhen
UNAUTHENTICATED401A guard or require_session ran with no usable session
MFA_REQUIRED403step_up.mfa was not met; reason is mfa
RECENT_AUTH_REQUIRED403step_up.max_age_ms was not met; reason is recent
IMPERSONATION_RESTRICTED403An impersonated session met a max_age_ms or Fresh requirement; reason is impersonation
ACCESS_DENIED403authorize or iam.require was denied
UNTRUSTED_ORIGIN403A cookie-authenticated unsafe request came from an untrusted origin
CSRF_REJECTED403A cookie-authenticated unsafe request had no Origin

Was this page helpful?

Better IAM is created by Sean Filimon

Last updated

On this page