Rust Reference - PropelAuth Docs

Rust Reference

PropelAuth's Rust library provides all the building blocks you need to add authentication to your Rust projects. You should prefer the Actix or Axum libraries if you are using those frameworks, as they provide a more first-class experience, however, this library can be used in any Rust project.

Installation

In your Cargo.toml file, add the following line:

propelauth = { version = "0.9.0" }

Initialize

There are two options for initializing the library. You can call PropelAuth::fetch_and_init which is an async function that will fetch the metadata needed to verify access tokens. Or, you can call PropelAuth::init and pass in the metadata directly. The later is useful for serverless environments.

let auth = PropelAuth::fetch_and_init(AuthOptions {
    auth_url: "REPLACE_ME".to_string(),
    api_key: "REPLACE_ME".to_string(),
}).await.expect("Unable to initialize authentication;");

Protect API Routes

After initializing auth, you can verify access tokens by passing in the Authorization header (formatted Bearer TOKEN):

let result = auth.verify().validate_authorization_header(&authorization_header);
match result {
    Ok(user) => { /* valid access token in the header */ }
    Err(_) => { /* invalid access token, typically we return a 401 Unauthorized here */ }
}

Verifying the access token doesn't require an external request.

Authorization / Organizations

You can also verify which organizations the user is in, and which roles and permissions they have, with the validate_org_membership function on the user object.

Check Org Membership

Verify that the request was made by a valid user and that the user is a member of the specified organization. This can be done using the User object.

let org = user.validate_org_membership(
    RequiredOrg::OrgId(orgId),
    UserRequirementsInOrg::None
)?;

Check Org Membership and Role

Similar to checking org membership, but will also verify that the user has a specific Role in the organization. This can be done using either the User or OrgMemberInfo objects.

A user has a Role within an organization. By default, the available roles are Owner, Admin, or Member, but these can be configured. These roles are also hierarchical, so Owner > Admin > Member.

let org = user.validate_org_membership(
    RequiredOrg::OrgId(orgId),
    UserRequirementsInOrg::IsRole("Owner")
)?;

Check Org Membership and Permission

Similar to checking org membership, but will also verify that the user has the specified permission in the organization. This can be done using either the User or OrgMemberInfo objects.

Permissions are arbitrary strings associated with a role. For example, can_view_billing, ProductA::CanCreate, and ReadOnly are all valid permissions. You can create these permissions in the PropelAuth dashboard.

let org = user.validate_org_membership(
    RequiredOrg::OrgId(orgId),
    UserRequirementsInOrg::HasPermission("can_view_billing")
)?;

User

The User object contains information about the user that made the request.

OrgMemberInfo

The OrgMemberInfo object contains information about the user's membership in an organization.

Calling backend APIs

You can also use the library to call the PropelAuth APIs directly, allowing you to fetch users, create orgs, and a lot more.

let auth = PropelAuth::fetch_and_init(AuthOptions {
  auth_url: "REPLACE_ME".to_string(),
  api_key: "REPLACE_ME".to_string(),
}).await.expect("Unable to initialize authentication");

let magic_link = auth.user().create_magic_link(CreateMagicLinkRequest {
  email: "user@customer.com".to_string(),
  ..Default::default()
}).await.expect("Couldn't create magic link");

See the API Reference for more information.