repository·main·Indexed 22 days ago
https://github.com/ramosbugs/oauth2-rsAn extensible, strongly-typed Rust implementation of the OAuth2 protocol (RFC 6749). It provides tools for client and authorization server interactions, supporting flows such as Authorization Code, Client Credentials, Device Authorization (RFC 8628), Resource Owner Password Credentials, and Refresh Token. The library utilizes the builder pattern and typestates to enforce configuration requirements at compile time and includes optional integration with reqwest for asynchronous and synchronous HTTP requests.
The oauth2 crate provides an extensible, strongly-typed implementation of the OAuth2 protocol (RFC 6749). It is designed to be used as a foundation for OAuth2 flows in Rust applications.
Note for Authentication Use Cases: If you are implementing authentication (such as single sign-on or social login), it is recommended to use the openidconnect crate instead, as it is built on top of this crate and specifically handles OpenID Connect flows.
The 5.0 release replaces stateless function pointers with AsyncHttpClient and SyncHttpClient traits. This allows for reusing connections (e.g., using a reqwest::Client).
Security Warning: To prevent SSRF vulnerabilities, configure your HTTP client not to follow redirects (e.g., use redirect::Policy::none in reqwest).
AsyncHttpClient is implemented for:
reqwest::Client (with reqwest feature enabled).Fn(HttpRequest) -> F where F: Future<Output = Result<HttpResponse, E>>.SyncHttpClient is implemented for:
reqwest::blocking::Client (with reqwest-blocking feature enabled).ureq::Agent (with ureq feature enabled).oauth2::CurlHttpClient (with curl feature enabled).Fn(HttpRequest) -> Result<HttpResponse, E>.In 5.0, Client uses typestates to ensure required endpoints are configured before an auth flow is used. All endpoints are now optional.
Use the single-argument Client::new(client_id) constructor. Use setters like set_auth_uri() or set_token_uri() to configure the client.
If you store a BasicClient or Client in a custom data type, you must include the five endpoint typestate generic parameters. The possible states are:
EndpointNotSet: Endpoint is unavailable.EndpointSet: Endpoint is ready for use.EndpointMaybeSet: Endpoint can be used via fallible methods that return Err(ConfigurationError::MissingUrl(_)) (useful for dynamic discovery).If using BasicClient, add these parameters:
HasAuthUrl, HasDeviceAuthUrl, HasIntrospectionUrl, HasRevocationUrl, HasTokenUrl.
// Example: Annotating a BasicClient with specific typestates
type MyClient = BasicClient<
EndpointSet, // HasAuthUrl
EndpointNotSet, // HasDeviceAuthUrl
EndpointNotSet, // HasIntrospectionUrl
EndpointNotSet, // HasRevocationUrl
EndpointSet, // HasTokenUrl
>;In 5.0, the reqwest feature only enables the asynchronous client to reduce dependencies. To use the synchronous (blocking) reqwest client, you must explicitly enable the reqwest-blocking feature in your Cargo.toml.
oauth2 = { version = "5", features = ["reqwest-blocking"] }The 5.0 release introduces several breaking changes to improve API consistency, type safety, and performance. Key changes include:
Client now uses typestates to track which endpoints (like authorization or token URIs) have been set at compile time.AsyncHttpClient and SyncHttpClient traits instead of stateless function pointers, allowing for connection reuse and custom client configuration.http 1.0 and reqwest 0.12.TokenResponse and TokenIntrospectionResponse now use an associated type TokenType instead of a generic parameter TT. Custom ErrorResponse implementations must now implement Display.The required Rust version depends on the major/minor version of the oauth2 crate you are using:
Starting from version 5.0.0, the crate follows a policy of supporting Rust releases going back at least 6 months. MSRV changes occur during minor version updates and are not part of patch releases.
The Client struct uses the Builder Pattern combined with Typestates to enforce OAuth2 requirements at compile time.
Each endpoint (e.g., Authorization, Token, Revocation) has a corresponding generic type parameter (like HasAuthUrl) that tracks whether that endpoint has been configured.
EndpointNotSet: The default state. Methods requiring the endpoint are unavailable.EndpointSet: The endpoint was configured using a direct setter (e.g., set_auth_uri()). Methods requiring this endpoint are available and return the requested object directly.EndpointMaybeSet: The endpoint was configured using an optional setter (e.g., set_auth_uri_option()). Methods requiring this endpoint are available but return a Result<T, ConfigurationError> because the endpoint might be None at runtime.This allows the library to prevent common errors, such as attempting to exchange a code for a token before the token URI has been provided.
The ErrorResponse trait allows you to define how your application handles error responses from an OAuth2 provider. While the library provides StandardErrorResponse, you can implement ErrorResponse yourself to support non-standard-compliant providers or custom error formats.
To implement ErrorResponse, your type must implement:
DebugDisplay (for human-readable error messages)serde::de::DeserializeOwnedserde::SerializeThe TokenIntrospectionResponse trait defines the standard fields returned by an OAuth2 introspection endpoint as per RFC 7662. You can implement this trait on your own custom response types to support non-standard or highly customized OAuth2 providers.
active(&self) -> bool: Returns whether the token is currently active.type TokenType: An associated type representing the token type.scopes(&self) -> Option<&Vec<Scope>>: Space-delimited list of scopes.client_id(&self) -> Option<&ClientId>: The client that requested the token.username(&self) -> Option<&str>: The resource owner's identifier.token_type(&self) -> Option<&Self::TokenType>: The type of token (e.g., Bearer).exp(&self) -> Option<DateTime<Utc>>: Expiration timestamp.iat(&self) -> Option<DateTime<Utc>>: Issued-at timestamp.nbf(&self) -> Option<DateTime<Utc>>: Not-before timestamp.sub(&self) -> Option<&str>: Subject of the token.aud(&self) -> Option<&Vec<String>>: Intended audience.iss(&self) -> Option<&str>: Issuer of the token.jti(&self) -> Option<&str>: Unique identifier for the token.To support non-standard OAuth2 providers or custom token fields, implement the TokenResponse trait and use StandardTokenResponse with a custom ExtraTokenFields type.
StandardTokenResponse<EF, TT> includes standard fields like access_token, token_type, expires_in, refresh_token, and scopes, while flattening any fields defined in your EF (Extra Fields) implementation.
Required trait methods for TokenResponse:
access_token(&self) -> &AccessToken (REQUIRED)token_type(&self) -> &Self::TokenType (REQUIRED)expires_in(&self) -> Option<Duration> (RECOMMENDED)refresh_token(&self) -> Option<&RefreshToken> (OPTIONAL)scopes(&self) -> Option<&Vec<Scope>> (OPTIONAL)The DeviceAuthorizationResponse<EF> contains the data required to complete the device flow. Fields include:
device_code(): The device verification code.user_code(): The code the end-user must enter on their device.verification_uri(): The URL for the user to visit.verification_uri_complete(): An optional URL that includes the user code for easier non-textual transmission.expires_in(): The duration (as Duration) before the codes expire.interval(): The minimum duration (as Duration) the client should wait between polling requests.extra_fields(): Any additional fields defined by the ExtraDeviceAuthorizationFields trait.The Device Authorization Flow is used for devices that lack a browser.
exchange_device_code() on a client that has been configured with set_device_authorization_url(). This returns a DeviceAuthorizationRequest.DeviceAuthorizationResponse.exchange_device_access_token(auth_response) to exchange the device response for an access token.This requires the token endpoint to be set via set_token_uri() (or set_token_uri_option()).