Crate oauth2[−][src]

Expand description

An extensible, strongly-typed implementation of OAuth2 (RFC 6749) including token introspection (RFC 7662) and token revocation (RFC 7009).

Contents

Importing oauth2: selecting an HTTP client interface

This library offers a flexible HTTP client interface with two modes:

  • Synchronous (blocking)

    The synchronous interface is available for any combination of feature flags.

    Example import in Cargo.toml:

    oauth2 = "4.1"

For the HTTP client modes described above, the following HTTP client implementations can be used:

  • reqwest

    The reqwest HTTP client supports both modes. By default, reqwest 0.10 is enabled, which supports the synchronous and asynchronous futures 0.3 APIs.

    Synchronous client: reqwest::http_client

    Async/await futures 0.3 client: reqwest::async_http_client

  • curl

    The curl HTTP client only supports the synchronous HTTP client mode and can be enabled in Cargo.toml via the curl feature flag.

    Synchronous client: curl::http_client

  • ureq

    The ureq HTTP client is a simple HTTP client with minimal dependencies. It only supports the synchronous HTTP client mode and can be enabled in Cargo.toml via the ureq feature flag.

  • Custom

    In addition to the clients above, users may define their own HTTP clients, which must accept an HttpRequest and return an HttpResponse or error. Users writing their own clients may wish to disable the default reqwest 0.10 dependency by specifying default-features = false in Cargo.toml:

    oauth2 = { version = "4.1", default-features = false }

    Synchronous HTTP clients should implement the following trait:

    ⓘ
    FnOnce(HttpRequest) -> Result<HttpResponse, RE>
where RE: std::error::Error + 'static

    Async/await HTTP clients should implement the following trait:

    ⓘ
    FnOnce(HttpRequest) -> F
where
  F: Future<Output = Result<HttpResponse, RE>>,
  RE: std::error::Error + 'static

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.10.

use anyhow;
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_uri(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: Async/Await API

One can use async/await as follows:

use anyhow;
use oauth2::{
    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_uri(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 anyhow;
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 anyhow;
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 anyhow;
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)?;

Device Code Flow

Device Code Flow allows users to sign in on browserless or input-constrained devices. This is a two-stage process; first a user-code and verification URL are obtained by using the Client::exchange_client_credentials method. Those are displayed to the user, then are used in a second client to poll the token endpoint for a token.

Example

use anyhow;
use oauth2::{
    AuthUrl,
    ClientId,
    ClientSecret,
    DeviceAuthorizationUrl,
    Scope,
    TokenResponse,
    TokenUrl
};
use oauth2::basic::BasicClient;
use oauth2::devicecode::StandardDeviceAuthorizationResponse;
use oauth2::reqwest::http_client;
use url::Url;

let device_auth_url = DeviceAuthorizationUrl::new("http://deviceauth".to_string())?;
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_device_authorization_url(device_auth_url);

let details: StandardDeviceAuthorizationResponse = client
    .exchange_device_code()?
    .add_scope(Scope::new("read".to_string()))
    .request(http_client)?;

println!(
    "Open this URL in your browser:\n{}\nand enter the code: {}",
    details.verification_uri().to_string(),
    details.user_code().secret().to_string()
);

let token_result =
    client
    .exchange_device_access_token(&details)
    .request(http_client, std::thread::sleep, None)?;

Other examples

More specific implementations are available as part of the examples:

Contributed Examples

Re-exports

pub use http;
pub use url;
pub use revocation::RevocableToken;
pub use revocation::RevocationErrorResponseType;
pub use revocation::StandardRevocableToken;

Modules

basic

Basic OAuth2 implementation with no extensions (RFC 6749).

curl

HTTP client backed by the curl crate. Requires “curl” feature.

devicecode

Device Code Flow OAuth2 implementation (RFC 8628).

helpers

Helper methods used by OAuth2 implementations/extensions.

reqwest

HTTP client backed by the reqwest crate. Requires “reqwest” feature.

revocation

OAuth 2.0 Token Revocation implementation (RFC 7009).

ureq

HTTP client backed by the ureq crate. Requires “ureq” feature.

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 state parameter.

DeviceAccessTokenRequest

The request for an device access token from the authorization server.

DeviceAuthorizationRequest

The request for a set of verification codes from the authorization server.

DeviceAuthorizationUrl

URL of the client’s device authorization endpoint.

DeviceCode

Device code returned by the device authorization endpoint and used to query the token endpoint.

EmptyExtraTokenFields

Empty (default) extra token fields.

EndUserVerificationUrl

URL of the end-user verification URI on the authorization server.

HttpRequest

An HTTP request.

HttpResponse

An HTTP response.

IntrospectionRequest

A request to introspect an access token.

IntrospectionUrl

URL of the client’s RFC 7662 OAuth 2.0 Token Introspection endpoint.

PasswordTokenRequest

A request to exchange resource owner credentials for an access token.

PkceCodeChallenge

Code Challenge used for PKCE protection via the code_challenge parameter.

PkceCodeChallengeMethod

Code Challenge Method used for PKCE protection via the code_challenge_method parameter.

PkceCodeVerifier

Code Verifier used for PKCE protection via the code_verifier parameter. The value must have a minimum length of 43 characters and a maximum length of 128 characters. Each character must be ASCII alphanumeric or one of the characters “-” / “.” / “_” / “~”.

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.

RevocationRequest

A request to revoke a token via an RFC 7009 compatible endpoint.

RevocationUrl

URL of the authorization server’s RFC 7009 token revocation endpoint.

Scope

Access token scope, as defined by the authorization server.

StandardErrorResponse

Error response returned by server after requesting an access token.

StandardTokenIntrospectionResponse

Standard OAuth2 token introspection response.

StandardTokenResponse

Standard OAuth2 token response.

TokenUrl

URL of the authorization server’s token endpoint.

UserCode

User code returned by the device authorization endpoint and used by the user to authorize at the verification URI.

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.

ConfigurationError

There was a problem configuring the request.

RequestTokenError

Error encountered while requesting access token.

Traits

ErrorResponse

Server Error Response

ErrorResponseType

Error types enum.

ExtraTokenFields

Trait for adding extra fields to the TokenResponse.

TokenIntrospectionResponse

Common methods shared by all OAuth2 token introspection implementations.

TokenResponse

Common methods shared by all OAuth2 token implementations.

TokenType

Trait for OAuth2 access tokens.