[−][src]Crate oauth2
An extensible, strongly-typed implementation of OAuth2 (RFC 6749).
Contents
- Importing
oauth2
: selecting an HTTP client interface - Getting started: Authorization Code Grant w/ PKCE
- Implicit Grant
- Resource Owner Password Credentials Grant
- Client Credentials Grant
- Other examples
Importing oauth2
: selecting an HTTP client interface
This library offers a flexible HTTP client interface with three modes:
-
Synchronous (blocking)
The synchronous interface is available for any combination of feature flags.
Example import in
Cargo.toml
:oauth2 = "3.0"
-
Asynchronous via
futures
0.1Support is enabled via the
futures-01
feature flag.Example import in
Cargo.toml
:oauth2 = { version = "3.0", features = ["futures-01"] }
-
Async/await via
futures
0.3Support is enabled via the
futures-03
feature flag. Typically, the default support forreqwest
0.9 is also disabled when using async/await. If desired, thereqwest-010
feature flag can be used to enablereqwest
0.10 and its async/await client interface.Example import in
Cargo.toml
:oauth2 = { version = "3.0", features = ["futures-03"], default-features = false }
For the HTTP client modes described above, the following HTTP client implementations can be used:
-
The
reqwest
HTTP client supports all three modes. By default,reqwest
0.9 is enabled, which supports the synchronous and asynchronousfutures
0.1 APIs.Synchronous client:
reqwest::http_client
Asynchronous
futures
0.1 client:reqwest::future_http_client
Async/await
futures
0.3 client:reqwest::async_http_client
. This mode requiresreqwest
0.10, which can be enabled via thereqwest-010
feature flag. Typically, the default features are also disabled (default-features = false
inCargo.toml
) to remove the dependency onreqwest
0.9 when usingreqwest
0.10. However, both can be used together if both asynchronous interfaces are desired. -
The
curl
HTTP client only supports the synchronous HTTP client mode and can be enabled inCargo.toml
via thecurl
feature flag.Synchronous client:
curl::http_client
-
Custom
In addition to the clients above, users may define their own HTTP clients, which must accept an
HttpRequest
and return anHttpResponse
or error. Users writing their own clients may wish to disable the defaultreqwest
0.9 dependency by specifyingdefault-features = false
inCargo.toml
:oauth2 = { version = "3.0", default-features = false }
Synchronous HTTP clients should implement the following trait:
ⓘThis example is not testedFnOnce(HttpRequest) -> Result<HttpResponse, RE> where RE: failure::Fail
Asynchronous
futures
0.1 HTTP clients should implement the following trait:ⓘThis example is not testedFnOnce(HttpRequest) -> F where F: Future<Item = HttpResponse, Error = RE>, RE: failure::Fail
Async/await
futures
0.3 HTTP clients should implement the following trait:ⓘThis example is not testedFnOnce(HttpRequest) -> F + Send where F: Future<Output = Result<HttpResponse, RE>> + Send, RE: failure::Fail
Getting started: Authorization Code Grant w/ PKCE
This is the most common OAuth2 flow. PKCE is recommended whenever the OAuth2 client has no client secret or has a client secret that cannot remain confidential (e.g., native, mobile, or client-side web applications).
Example: Synchronous (blocking) API
This example works with oauth2
's default feature flags, which include reqwest
0.9.
use failure; use oauth2::{ AuthorizationCode, AuthUrl, ClientId, ClientSecret, CsrfToken, PkceCodeChallenge, RedirectUrl, Scope, TokenResponse, TokenUrl }; use oauth2::basic::BasicClient; use oauth2::reqwest::http_client; use url::Url; // Create an OAuth2 client by specifying the client ID, client secret, authorization URL and // token URL. let client = BasicClient::new( ClientId::new("client_id".to_string()), Some(ClientSecret::new("client_secret".to_string())), AuthUrl::new("http://authorize".to_string())?, Some(TokenUrl::new("http://token".to_string())?) ) // Set the URL the user will be redirected to after the authorization process. .set_redirect_url(RedirectUrl::new("http://redirect".to_string())?); // Generate a PKCE challenge. let (pkce_challenge, pkce_verifier) = PkceCodeChallenge::new_random_sha256(); // Generate the full authorization URL. let (auth_url, csrf_token) = client .authorize_url(CsrfToken::new_random) // Set the desired scopes. .add_scope(Scope::new("read".to_string())) .add_scope(Scope::new("write".to_string())) // Set the PKCE code challenge. .set_pkce_challenge(pkce_challenge) .url(); // This is the URL you should redirect the user to, in order to trigger the authorization // process. println!("Browse to: {}", auth_url); // Once the user has been redirected to the redirect URL, you'll have access to the // authorization code. For security reasons, your code should verify that the `state` // parameter returned by the server matches `csrf_state`. // Now you can trade it for an access token. let token_result = client .exchange_code(AuthorizationCode::new("some authorization code".to_string())) // Set the PKCE code verifier. .set_pkce_verifier(pkce_verifier) .request(http_client)?; // Unwrapping token_result will either produce a Token or a RequestTokenError.
Example: Asynchronous (futures 0.1-based) API
In order to use futures
0.1, include oauth2
as follows:
[dependencies]
oauth2 = { version = "3.0", features = ["futures-01"] }
use failure; use oauth2::{ AuthorizationCode, AuthUrl, ClientId, ClientSecret, CsrfToken, PkceCodeChallenge, RedirectUrl, Scope, TokenResponse, TokenUrl }; use oauth2::basic::BasicClient; use oauth2::reqwest::future_http_client; use tokio::runtime::Runtime; use url::Url; // Create an OAuth2 client by specifying the client ID, client secret, authorization URL and // token URL. let client = BasicClient::new( ClientId::new("client_id".to_string()), Some(ClientSecret::new("client_secret".to_string())), AuthUrl::new("http://authorize".to_string())?, Some(TokenUrl::new("http://token".to_string())?) ) // Set the URL the user will be redirected to after the authorization process. .set_redirect_url(RedirectUrl::new("http://redirect".to_string())?); // Generate a PKCE challenge. let (pkce_challenge, pkce_verifier) = PkceCodeChallenge::new_random_sha256(); // Generate the full authorization URL. let (auth_url, csrf_token) = client .authorize_url(CsrfToken::new_random) // Set the desired scopes. .add_scope(Scope::new("read".to_string())) .add_scope(Scope::new("write".to_string())) // Set the PKCE code challenge. .set_pkce_challenge(pkce_challenge) .url(); // This is the URL you should redirect the user to, in order to trigger the authorization // process. println!("Browse to: {}", auth_url); // Once the user has been redirected to the redirect URL, you'll have access to the // authorization code. For security reasons, your code should verify that the `state` // parameter returned by the server matches `csrf_state`. let mut runtime = Runtime::new().unwrap(); // Now you can trade it for an access token. let token_result = runtime.block_on( client .exchange_code(AuthorizationCode::new("some authorization code".to_string())) // Set the PKCE code verifier. .set_pkce_verifier(pkce_verifier) .request_future(future_http_client) )?; // Unwrapping token_result will either produce a Token or a RequestTokenError.
Example: Async/Await API
Async/await support requires rustc
1.39.0 or newer. In order to use async/await, include
oauth2
as follows:
[dependencies]
oauth2 = { version = "3.0", features = ["futures-03", "reqwest-010"], default-features = false }
use failure; use oauth2::{ AsyncCodeTokenRequest, AuthorizationCode, AuthUrl, ClientId, ClientSecret, CsrfToken, PkceCodeChallenge, RedirectUrl, Scope, TokenResponse, TokenUrl }; use oauth2::basic::BasicClient; use oauth2::reqwest::async_http_client; use url::Url; // Create an OAuth2 client by specifying the client ID, client secret, authorization URL and // token URL. let client = BasicClient::new( ClientId::new("client_id".to_string()), Some(ClientSecret::new("client_secret".to_string())), AuthUrl::new("http://authorize".to_string())?, Some(TokenUrl::new("http://token".to_string())?) ) // Set the URL the user will be redirected to after the authorization process. .set_redirect_url(RedirectUrl::new("http://redirect".to_string())?); // Generate a PKCE challenge. let (pkce_challenge, pkce_verifier) = PkceCodeChallenge::new_random_sha256(); // Generate the full authorization URL. let (auth_url, csrf_token) = client .authorize_url(CsrfToken::new_random) // Set the desired scopes. .add_scope(Scope::new("read".to_string())) .add_scope(Scope::new("write".to_string())) // Set the PKCE code challenge. .set_pkce_challenge(pkce_challenge) .url(); // This is the URL you should redirect the user to, in order to trigger the authorization // process. println!("Browse to: {}", auth_url); // Once the user has been redirected to the redirect URL, you'll have access to the // authorization code. For security reasons, your code should verify that the `state` // parameter returned by the server matches `csrf_state`. // Now you can trade it for an access token. let token_result = client .exchange_code(AuthorizationCode::new("some authorization code".to_string())) // Set the PKCE code verifier. .set_pkce_verifier(pkce_verifier) .request_async(async_http_client) .await?; // Unwrapping token_result will either produce a Token or a RequestTokenError.
Implicit Grant
This flow fetches an access token directly from the authorization endpoint. Be sure to understand the security implications of this flow before using it. In most cases, the Authorization Code Grant flow is preferable to the Implicit Grant flow.
Example
use failure; use oauth2::{ AuthUrl, ClientId, ClientSecret, CsrfToken, RedirectUrl, Scope }; use oauth2::basic::BasicClient; use url::Url; let client = BasicClient::new( ClientId::new("client_id".to_string()), Some(ClientSecret::new("client_secret".to_string())), AuthUrl::new("http://authorize".to_string())?, None ); // Generate the full authorization URL. let (auth_url, csrf_token) = client .authorize_url(CsrfToken::new_random) .use_implicit_flow() .url(); // This is the URL you should redirect the user to, in order to trigger the authorization // process. println!("Browse to: {}", auth_url); // Once the user has been redirected to the redirect URL, you'll have the access code. // For security reasons, your code should verify that the `state` parameter returned by the // server matches `csrf_state`.
Resource Owner Password Credentials Grant
You can ask for a password access token by calling the Client::exchange_password
method,
while including the username and password.
Example
use failure; use oauth2::{ AuthUrl, ClientId, ClientSecret, ResourceOwnerPassword, ResourceOwnerUsername, Scope, TokenResponse, TokenUrl }; use oauth2::basic::BasicClient; use oauth2::reqwest::http_client; use url::Url; let client = BasicClient::new( ClientId::new("client_id".to_string()), Some(ClientSecret::new("client_secret".to_string())), AuthUrl::new("http://authorize".to_string())?, Some(TokenUrl::new("http://token".to_string())?) ); let token_result = client .exchange_password( &ResourceOwnerUsername::new("user".to_string()), &ResourceOwnerPassword::new("pass".to_string()) ) .add_scope(Scope::new("read".to_string())) .request(http_client)?;
Client Credentials Grant
You can ask for a client credentials access token by calling the
Client::exchange_client_credentials
method.
Example
use failure; use oauth2::{ AuthUrl, ClientId, ClientSecret, Scope, TokenResponse, TokenUrl }; use oauth2::basic::BasicClient; use oauth2::reqwest::http_client; use url::Url; let client = BasicClient::new( ClientId::new("client_id".to_string()), Some(ClientSecret::new("client_secret".to_string())), AuthUrl::new("http://authorize".to_string())?, Some(TokenUrl::new("http://token".to_string())?), ); let token_result = client .exchange_client_credentials() .add_scope(Scope::new("read".to_string())) .request(http_client)?;
Other examples
More specific implementations are available as part of the examples:
Contributed Examples
actix-web-oauth2
(version 2.x of this crate)
Re-exports
pub use http; |
pub use url; |
Modules
basic | Basic OAuth2 implementation with no extensions (RFC 6749). |
curl | HTTP client backed by the curl crate. |
helpers | Helper methods used by OAuth2 implementations/extensions. |
reqwest | HTTP client backed by the reqwest crate. |
Structs
AccessToken | Access token returned by the token endpoint and used to access protected resources. |
AuthUrl | URL of the authorization server's authorization endpoint. |
AuthorizationCode | Authorization code returned from the authorization endpoint. |
AuthorizationRequest | A request to the authorization endpoint |
Client | Stores the configuration for an OAuth2 client. |
ClientCredentialsTokenRequest | A request to exchange client credentials for an access token. |
ClientId | Client identifier issued to the client during the registration process described by Section 2.2. |
ClientSecret | Client password issued to the client during the registration process described by Section 2.2. |
CodeTokenRequest | A request to exchange an authorization code for an access token. |
CsrfToken | Value used for CSRF protection
via the |
EmptyExtraTokenFields | Empty (default) extra token fields. |
HttpRequest | An HTTP request. |
HttpResponse | An HTTP response. |
PasswordTokenRequest | A request to exchange resource owner credentials for an access token. |
PkceCodeChallenge | Code Challenge used for PKCE protection via the
|
PkceCodeChallengeMethod | Code Challenge Method used for PKCE protection
via the |
PkceCodeVerifier | Code Verifier used for PKCE protection via the
|
RedirectUrl | URL of the client's redirection endpoint. |
RefreshToken | Refresh token used to obtain a new access token (if supported by the authorization server). |
RefreshTokenRequest | A request to exchange a refresh token for an access token. |
ResourceOwnerPassword | Resource owner's password used directly as an authorization grant to obtain an access token. |
ResourceOwnerUsername | Resource owner's username used directly as an authorization grant to obtain an access token. |
ResponseType | Authorization endpoint response (grant) type defined in Section 3.1.1. |
Scope | Access token scope, as defined by the authorization server. |
StandardErrorResponse | Error response returned by server after requesting an access token. |
StandardTokenResponse | Standard OAuth2 token response. |
TokenUrl | URL of the authorization server's token endpoint. |
Enums
AuthType | Indicates whether requests to the authorization server should use basic authentication or include the parameters in the request body for requests in which either is valid. |
RequestTokenError | Error encountered while requesting access token. |
Traits
AsyncClientCredentialsTokenRequest | Asynchronous request to exchange client credentials for an access token. |
AsyncCodeTokenRequest | Asynchronous request to exchange an authorization code for an access token. |
AsyncPasswordTokenRequest | Asynchronous request to exchange resource owner credentials for an access token. |
AsyncRefreshTokenRequest | Asynchronous request to exchange a refresh token for an access token. |
ErrorResponse | Server Error Response |
ErrorResponseType | Error types enum. |
ExtraTokenFields | Trait for adding extra fields to the |
TokenResponse | Common methods shared by all OAuth2 token implementations. |
TokenType | Trait for OAuth2 access tokens. |