An authorization framework with compile-time enforcement.
Dacquiri turns authorization vulnerabilities into compile-time errors.
Dacquiri has two main concepts that govern how authorization policies are defined and applied.
dacquiri relies on nightly + multiple unstable features to work.
The following unstable features will, at minimum, be required in your
application for it to work with dacquiri.
```rust
``
Additionally, you can add#![allow(incomplete_features)]` to ignore the inevitable unstable feature warnings.
Attributes are properties we prove about a Subject
(the entity we are applying the authorization check against).
Attributes are statements that are true about a particular subject. For example,
UserIsEnabled may be an attribute defined for User subjects that have their enabled flag set to true.
Some additional attributes you might define could answer the following:
* Is this user's ID verified?
* Is this user's account older than 30 days?
* Is this user a member of a particular team?
The last attribute introduces us to the idea of resources.
A Resource is the object a subject is attempting to acquire a particular attribute against.
A common example of an attribute, with a resource, would be a UserIsTeamMember attribute.
For this attribute, the subject is User and the resource is Team. This attribute would only be
granted if the User was a member of the specified Team.
While this a useful primitive, it wouldn't make much sense to check if a User was a member of a Team and then perform actions against a
completely different Team object. Therefore, attributes also remember which
resource they were acquired against. This way, if necessary, you can access an attribute's associated resource.
We define attributes using the attribute macro, 1 to 3 arguments, and an AttributeResult return type.
```rust
use dacquiri::prelude::*;
fn checkuseris_enabled(user: &User) -> AttributeResult
This will automatically generate an _attribute_ with a `User` as the subject and `()` as the resource.
If we have a resource we depend on, we can add it as the second argument to the function.
rust
use dacquiri::prelude::*;
fn checkuserteam(
user: &User,
team: &Team
) -> AttributeResult
The generatedUserIsTeamMemberattribute will haveUseras the _subject_ andTeam` as the _resource.
Sometimes, you may not have all of the required information to determine if a subject has a particular attribute
for a particular resource even if you already have that resource fetched. In these cases, you can specify an optional
third argument to provide context or assets required to access additional, required information.
Here's an example iteration on the previous attribute we defined where we fetch data, live, from a database. ```rust
use dacquiri::prelude::*;
async fn userteamcheck(
user: &User,
team: &Team,
conn: &mut DatabaseConnection
) -> AttributeResult
You should notice two things that are different about this particular attribute.
1. We didn't have to make the context (_3rd argument_) an immutable reference. Attribute context's
can be owned, immutable, or mutable references. This allows you to use any concrete type you wish here.
2. You should also notice that this attribute function isasync`! Attributes support async and it's as
simple as just adding the keyword to the function. All of the other work is handled automatically for you.
We'll come back to attributes in a bit, but first let's talk about Entitlements.
Entitlements are traits, gated behind one or more attributes, that are automatically applied
to any subject that has acquired all of the prerequisite attributes at some point, in any order.
An example of a useful entitlement could be a VerifiedUser entitlement which would require the following attributes:
* UserIsEnabled - Checks that the user's enabled flag is true
* UserIsVerified - Checks that the user's verified state is Verified::Success
Entitlements allow us to guard functionality behind a prerequisite set of attributes using default trait methods.
We start by defining a trait with the entitlement macro.
```rust
pub trait VerifiedUser {
fn print_message(&self) {
println!("Hello, world!!");
}
}
This _entitlement_ requires that a _subject_ have both the `UserIsVerified` and `UserIsEnabled` attributes.
If a _subject_ has acquired both _attributes_, `VerifiedUser` will automatically be implemented on the _subject_.
To get access to the `User` _subject_ again, we use the [`get_subject`](crate::prelude::SubjectT::get_subject) or
[`get_subject_mut`](crate::prelude::SubjectT::get_subject_mut) methods. Then we can access information
or make changes to our subject once again.
rust
pub trait VerifiedUser {
fn changename(&mut self, newname: impl Into
We can create async methods here as well using [`#[async_trait]`](async_trait::async_trait) like a normal trait.
rust
pub trait VerifiedUser { // set the account's enabled to false and consume the user async fn disableaccount(self, conn: &mut DatabaseConnection) { let query = escape!( "UPDATE users SET enabled = false WHERE uid = {};", self.getsubject().user_id ); conn.execute(query).await; } } ```
To acquire an attribute, we call one of the following on our subject.
- try_grant
- try_grant_async
- try_grant_with_context
- try_grant_with_context_async
- try_grant_with_resource
- try_grant_with_resource_async
- try_grant_with_resource_and_context
- try_grant_with_resource_and_context_async
For example, if we wanted to check if our User was both enabled and a member of a Team we could do the following.
We'll use the previous UserIsEnabled and UserIsTeamMember attribute definitions.
```rust
async fn main() -> Result<(), String> {
let user: User = getuser();
let team: Team = getteam();
let mut conn: DatabaseConnection = getdatabaseconn();
let checkeduser = user
.trygrant::
Now that we know how to acquire an attribute for a subject, let's put the entitlement system to work by guarding a function with one or more entitlements.
We treat entitlements like regular traits and guard with your favorite trait-bound syntax.
Here's a longer, more complicated example, that demonstrates the value that dacquiri provides
by guarding access to the leave_team functionality to Users until they have checked both
attributes required by the TeamMember entitlement bound.
It does not matter the order that the try_grant_* functions are called, that they are called
sequentially, or that they even happened in the same function.
```rust
async fn main() -> Result<(), String> {
let user: User = getuser();
let team: Team = getteam();
let mut conn: DatabaseConnection = getdatabaseconn();
let mut checkeduser = user
.trygrant::.leave_team() if you're not
// a TeamMember (which requires UserIsEnabled and UserIsTeamMember)
user.leaveteam().await
}
trait TeamMember {
// we capture self here because leaving the team
// means we're no longer a team member
async fn leaveteam(
self,
conn: &mut DatabaseConection
) -> Result<(), String> {
let user = self.getsubject();
// we need to specify which attribute's resource we want
let team = self.getresource::
The last topic that needs to be covered is about subjects. We mentioned them earlier; subjects are the
entities that we're administering an authorization policy against and applying access control.
We do need to denote subjects before we can start acquiring attributes on them.
Do mark a struct as a Subject we mark them with #[derive(Subject))
```rust
use dacquiri::prelude::Subject;
pub struct AuthenticatedUser { username: String, session_token: String, enabled: bool } ``` That's it!
Now you have a relatively good grasp on how dacquiri works and how you can use it
to life authorization requirements into the type system.