[][src]Crate rocket_oauth2

rocket_oauth2

OAuth2 (RFC 6749) for Rocket applications.

Requirements

  • Rocket 0.4

API Stability

rocket_oauth2 is still in its early stages and the API is subject to heavy change in the future.

Features

  • Handles the Authorization Code Grant (RFC 6749, §4.1)
  • Built-in support for a few popular OAuth2 providers
  • Support for custom providers
  • Support for custom adapters
  • Refreshing tokens

Not-yet-planned Features

  • Grant types other than Authorization Code.

Design

This crate is designed around 2 traits: Callback and Adapter. The Adapter trait is implemented by types that can generate authorization URLs and perform token exchanges. The Callback trait is implemented by Rocket applications to perform application-specific actions when a token has been exchanged successfully.

Generally, a Rocket application will implement Callback on one type per service the application will connect to. The OAuth2 type registers routes and handlers in the application for the OAuth2 redirect and an optional login handler for convenience.

Implementations

rocket_oauth2 currently provides only one Adapter itself:

hyper_sync_rustls was chosen because it is already a dependency of Rocket. In general, custom Adapters should only be needed to work around non-compliant service providers.

Usage

Add rocket_oauth2 to your Cargo.toml:

rocket_oauth2 = { version = "0.0.0" }

Implement Callback for your type, or write a free function:

use rocket_oauth2::{Callback, OAuth2, TokenResponse};
use rocket_oauth2::hyper_sync_rustls_adapter::HyperSyncRustlsAdapter;

fn github_callback(request: &Request, token: TokenResponse)
    -> Result<Redirect, Box<::std::error::Error>>
{
    let mut cookies = request.guard::<Cookies>().expect("request cookies");

    // Set a private cookie with the access token
    cookies.add_private(
        Cookie::build("token", token.access_token().to_string())
            .same_site(SameSite::Lax)
            .finish()
    );
    Ok(Redirect::to("/"))
}

Configure your OAuth client settings in Rocket.toml:

[global.oauth.github]
provider = "GitHub"
client_id = "..."
client_secret = "..."
redirect_uri = "http://localhost:8000/auth/github"

Create and attach the OAuth2 fairing:

use rocket::fairing::AdHoc;
use rocket_oauth2::{Callback, OAuth2, OAuthConfig, TokenResponse};
use rocket_oauth2::hyper_sync_rustls_adapter::HyperSyncRustlsAdapter;


rocket::ignite()
.attach(OAuth2::fairing(
    HyperSyncRustlsAdapter,
    github_callback,
    "github",

    // Set up a handler for the redirect uri
    "/auth/github",

    // Set up a redirect from /login/github that will request the 'user:read' scope
    Some(("/login/github", vec!["user:read".to_string()])),
))

Modules

hyper_sync_rustls_adapter

Adapter implemented using hyper-sync-rustls.

Structs

Error

Represents an error during authorization. Error has a kind and a source which describe the error.

OAuth2

The OAuth2 structure implements OAuth in a Rocket application by setting up OAuth-related route handlers.

OAuthConfig

Holds configuration for an OAuth application. This consists of the Provider details, a client_id and client_secret, and a redirect_uri.

StaticProvider

A StaticProvider contains the authorization and token exchange URIs specific to a known OAuth service provider.

TokenResponse

The server's response to a successful token exchange, defined in in RFC 6749 §5.1.

Enums

ErrorKind

Represents any kind of error that can occur during authorization. Most of these errors are returned by an Adapter.

TokenRequest

The token types which can be exchanged with the token endpoint

Traits

Adapter

An OAuth2 Adapater can be implemented by any type that facilitates the Authorization Code Grant as described in RFC 6749 §4.1. The implementing type must be able to generate an authorization URI and perform the token exchange.

Callback

An OAuth2 Callback implements application-specific OAuth client logic, such as setting login cookies and making database and API requests. It is tied to a specific Adapter, and will recieve an instance of the Adapter's Token type.

Provider

A Provider can retrieve authorization and token exchange URIs specific to an OAuth service provider.