actix-web
Serve the Better IAM API from an actix-web app with IamActix, read the session with the IamRequest extractor, and guard resources with require_session and authorize.
IamActix from better_iam::middleware (the better-iam-middleware crate) connects a
Rust BetterIam instance to an
actix-web application. Its middleware serves the IAM HTTP API under /api/iam and gives every other request an
IamRequest extractor with the caller's , permission checks, and an in-process
client. Its guards (require_session, authorize) wrap resources and scopes. It is the same integration as the
axum adapter, with actix-web types: the helpers, options, refusals, and error codes are
identical, so this page covers what differs and links there for the rest.
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
[dependencies]
better-iam = { path = "../better-iam/crates/better-iam", features = ["actix-web"] }
actix-web = "4"
futures = "0.3"
serde_json = "1"The umbrella's actix-web feature turns on its middleware module (better_iam::middleware, the
better-iam-middleware crate) with the actix-web integration.
Wrap the app
IamActix::new(iam, options) takes the instance (an Arc<BetterIam>, or a lazy IamSource) and the same
IamLayerOptions as the axum adapter. Register iam_actix.middleware() with App::wrap, so it runs before every
route, and wrap individual resources with guards.
use actix_web::{App, HttpServer, web};
use better_iam::middleware::actix::IamActix;
use better_iam::middleware::layer::IamLayerOptions;
mod iam; // create_iam() from the Rust overview
mod routes;
#[actix_web::main]
async fn main() -> std::io::Result<()> {
let iam = iam::create_iam().await.expect("Better IAM failed to start");
let iam_actix = IamActix::new(
iam,
IamLayerOptions { login_path: Some("/login".into()), ..IamLayerOptions::default() },
);
HttpServer::new(move || {
App::new()
.wrap(iam_actix.middleware())
.service(
web::resource("/me")
.wrap(iam_actix.require_session(None))
.route(web::get().to(routes::me)),
)
})
.bind(("127.0.0.1", 3000))?
.run()
.await
}- The API mount. Requests under the base path (
/api/iam) are answered by the IAM server through its node transport before any route matches, including the protocol mounts listed inserve. - Cookies.
Set-Cookieheaders the helpers receive during a request (from sign-in or sign-out) are added to that request's response. - Order. Guards read the helpers the middleware attached, so register
iam_actix.middleware()on theApp, not only on a scope.
Protect routes
Require a session
use actix_web::HttpResponse;
use better_iam::BetterIam;
use better_iam::middleware::{IamRequest, MiddlewareError};
use serde_json::json;
pub type Iam = IamRequest<BetterIam>;
pub async fn me(iam: Iam) -> Result<HttpResponse, MiddlewareError> {
let session = iam.require_session(None).await?;
Ok(HttpResponse::Ok().json(json!({
"email": session["identity"]["email"],
"tenantId": session["session"]["tenantId"],
})))
}A signed-out API call gets 401 with { "error": { "code": "UNAUTHENTICATED", "message": "A session is required" } };
a signed-out page navigation to /me?tab=1 is redirected to /login?next=%2Fme%3Ftab%3D1.
Require a permission
iam_actix.authorize(rule, step_up) takes an AuthorizeRule<HttpRequest>: its resource and tenant_id callbacks
receive the actix HttpRequest, so route parameters come from request.match_info().
use actix_web::{HttpRequest, HttpResponse, web};
use better_iam::middleware::{AuthorizeRule, ResourceRef};
use serde_json::json;
async fn project(path: web::Path<String>) -> HttpResponse {
HttpResponse::Ok().json(json!({ "id": path.into_inner() }))
}
// inside HttpServer::new(move || { ... })
let read_project = AuthorizeRule::<HttpRequest>::new("projects:read").resource(|request, _session| ResourceRef {
kind: "project".into(),
id: request.match_info().get("id").unwrap_or_default().to_owned(),
});
App::new()
.wrap(iam_actix.middleware())
.service(
web::resource("/projects/{id}")
.wrap(iam_actix.authorize(read_project, None))
.route(web::get().to(project)),
)A denial answers 403 ACCESS_DENIED. Step-up works as in axum: pass
Some(StepUpRequirement { mfa: Some(StepUpMfa::On), max_age_ms: Some(600_000.0) }) as the second argument (see
Require step-up).
Enforce inside a handler
use actix_web::{HttpResponse, web};
use better_iam::middleware::{MiddlewareError, ResourceRef};
pub async fn delete_document(iam: Iam, path: web::Path<String>) -> Result<HttpResponse, MiddlewareError> {
let id = path.into_inner();
iam.require("documents:delete", Some(ResourceRef { kind: "document".into(), id }), None)
.await?;
Ok(HttpResponse::NoContent().finish())
}MiddlewareError and IamRequestError implement actix-web's ResponseError: a refusal becomes the IAM JSON
envelope with its status (the middleware turns it into a redirect for page navigations), and any other error is logged
and answered with a plain 500.
Cross-site requests
Guards refuse a cookie-authenticated POST, PUT, PATCH, or DELETE from an untrusted Origin
(403 UNTRUSTED_ORIGIN, or 403 CSRF_REJECTED with no Origin), exactly as the axum guards do. Add other front-end
origins to trusted_origins.
Read the session
The IamRequest extractor gives handlers the same per-request helpers as in axum: get_session, require_session,
require, can (batched into one authorizeMany call per request), authorize, plan, list_accessible,
assertion, client() (the in-process client, whose cookies land on this response), sign_out, and credential()
for direct iam.api.* calls. See Read the session for each one.
use actix_web::{HttpResponse, web};
use better_iam::middleware::{MiddlewareError, ResourceRef};
use serde_json::json;
pub async fn toolbar(iam: Iam, path: web::Path<String>) -> Result<HttpResponse, MiddlewareError> {
let project = ResourceRef { kind: "project".into(), id: path.into_inner() };
let (edit, delete) = futures::join!(
iam.can("projects:update", Some(project.clone()), None),
iam.can("projects:delete", Some(project), None),
);
Ok(HttpResponse::Ok().json(json!({ "canEdit": edit?, "canDelete": delete? })))
}
pub async fn logout(iam: Iam) -> Result<HttpResponse, MiddlewareError> {
iam.sign_out().await?;
Ok(HttpResponse::SeeOther().insert_header(("location", "/")).finish())
}iam_actix.helpers(&request) returns the helpers of an HttpRequest outside an extractor.
Options
IamActix::new takes the IamLayerOptions of the axum adapter (login_path,
step_up_path, serve, base_path, trusted_origins, csrf, now).
| Method | What it does |
|---|---|
middleware() | Serves the API under the serve prefixes and attaches IamRequest to every other request |
require_session(step_up) | A guard requiring a session, and a step-up when given |
authorize(rule, step_up) | A guard requiring a session allowed to perform rule.action |
guard(spec) | A guard for any GuardSpec<HttpRequest> |
helpers(&request) | The per-request helpers of a request |
resolve() | Resolves the instance |
Related
Better IAM is created by Sean Filimon
Last updated
axumbeta
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.
Typed clientbeta
Call a Better IAM server from Rust with better-iam-client, a typed method per route with generated request and result types, CSRF headers, bearer tokens, structured errors, a session store, and device proofs.