#rocket #permissions #security #grant #authz #api-access


Authorization extension for rocket to protect your endpoints

5 releases

0.5.0-rc.2 Jun 20, 2022
0.5.0-beta.1 Feb 23, 2022
0.1.4 Mar 31, 2024
0.1.3 Nov 30, 2023

#295 in Authentication

Download history 1/week @ 2024-02-07 6/week @ 2024-02-14 9/week @ 2024-02-21 103/week @ 2024-02-28 32/week @ 2024-03-06 17/week @ 2024-03-13 10/week @ 2024-03-20 133/week @ 2024-03-27 53/week @ 2024-04-03

218 downloads per month
Used in rocket-grants-proc-macro


147 lines



Extension for rocket to authorize requests.

Crates.io Downloads Badge crates.io Documentation Apache 2.0 or MIT licensed

To check user access to specific endpoints, you can use built-in proc-macro or do it manually.

How to use

  1. Declare your own authorities extraction function

The easiest way is to declare a function with the following signature:

// You can use custom type instead of String
async fn extract(req: &rocket::Request<'_>) -> Option<HashSet<String>>
  1. Add fairing to your application using the extraction function defined in step 1
    rocket::build().mount("/api", rocket::routes![endpoint])
         .attach(GrantsFairing::with_extractor_fn(|req| {
             Box::pin(extract(req)) // example with a separate async function `extract`, but you can write a closure right here

Steps 1 and 2 can be replaced by integration with your custom fairing.

  1. Protect your endpoints in any convenient way from the examples below:

Example of proc-macro way protection

async fn macro_secured() -> &'static str {
Example of ABAC-like protection and custom permission type

Here is an example using the ty and expr attributes. But these are independent features.

expr allows you to include some checks in the macro based on function params, it can be combined with authorities by using all/any.

ty allows you to use a custom type for the authority (then the fairing needs to be configured). Take a look at an enum-role example

use enums::Role::{self, ADMIN};
use dto::User;

#[rocket_grants::protect("USER", expr = "user_id == user.id")]
#[rocket::post("/secure/<user_id>", data = "<user>")]
async fn role_macro_secured_with_params(user_id: i32, user: Json<User>) -> &'static str {
   "some secured info with parameters"

#[rocket_grants::protect(any("ADMIN", expr = "user.is_super_user()"))]
#[rocket::post("/secure/admin/<user_id>", data = "<user>")]
async fn admin_or_super_user(user_id: i32, user: Json<User>) -> &'static str {
   "some secured info with parameters"

Example of manual way protection

use rocket_grants::authorities::{AuthDetails, AuthoritiesCheck};

async fn manual_secure(details: AuthDetails) -> &'static str {
    if details.has_authority("ROLE_ADMIN") {
        return "ADMIN_RESPONSE"

You can find more examples in the git repository folder and documentation.

Error customization

Custom error responses can be specified using Rocket catchers. See the Rocket documentation for catchers.

You can set up custom responses for:

401 Unauthorized - when it wasn't possible to obtain authorization data from the request in your extractor.

403 Forbidden - when the permissions did not match the specified for the endpoint.

Supported rocket versions

  • For rocket-grants: 0.1.* supported version of rocket is 0.5.*


~816K SLoC