rustlavel_oauth/lib.rs
1//! OAuth 2.1 for Rustlavel — the protocol vocabulary, and the client half.
2//!
3//! This crate is what you reach for when your application signs users in
4//! *through* somebody else: Google, GitHub, or any provider that speaks the
5//! authorisation code flow. The other half — being a provider yourself — lives
6//! in `rustlavel-oauth-provider`, which depends on the types defined here so
7//! both ends agree on the wire format by construction.
8//!
9//! ```ignore
10//! use rustlavel_oauth::prelude::*;
11//!
12//! let github = OAuthClient::new(Provider::github())
13//! .credentials(config.string("services.github.id", ""), config.string("services.github.secret", ""))
14//! .redirect_uri("https://app.test/auth/github/callback");
15//!
16//! App::new().plugin(Socialite::new().provider(github).on_login(|user, req| async move {
17//! req.auth().login(&user);
18//! Response::see_other("/dashboard")
19//! }));
20//! ```
21//!
22//! Two things are not configurable, because a client that can be talked out of
23//! them is a client that will be: PKCE is always sent, always S256, and every
24//! callback is checked against a `state` this application issued. Skipping the
25//! second is login CSRF — see [`state`] for what that costs.
26//!
27//! Written from scratch on RFC 6749, 6750, 7009 and 7636, save for SHA-256 and
28//! AES-GCM, which come from the RustCrypto crates by way of `rustlavel-auth`.
29
30pub mod verify;
31pub mod client;
32pub mod error;
33pub mod pkce;
34pub mod provider;
35pub mod routes;
36pub mod scope;
37pub mod state;
38pub mod token;
39pub mod url;
40pub mod user;
41
42pub use client::{Authorization, OAuthClient};
43pub use error::{OAuthError, OAuthErrorCode};
44pub use pkce::{ChallengeMethod, Pkce};
45pub use provider::{ClientAuth, Provider, UserMap};
46pub use routes::Socialite;
47pub use scope::Scopes;
48pub use state::{SealedState, SessionState, StateError, StateGuard};
49pub use token::TokenResponse;
50pub use user::SocialUser;
51
52pub use rustlavel_core::{Error, Result};
53
54/// What a `routes/web.rs` or a controller imports to use this package.
55pub mod prelude {
56 pub use crate::{
57 Authorization, ClientAuth, OAuthClient, OAuthError, OAuthErrorCode, Pkce, Provider,
58 Scopes, SocialUser, Socialite, StateError, StateGuard, TokenResponse, UserMap,
59 };
60}