Crate yup_oauth2

This library can be used to acquire oauth2.0 authentication for services.

For your application to use this library, you will have to obtain an application id and secret by following this guide (for Google services) respectively the documentation of the API provider you want to connect to.

Device Flow Usage

With an application secret you can get started right away, building a DeviceFlowAuthenticator and obtaining tokens from it.

Service account "flow"

When using service account credentials, no user interaction is required. The access token can be obtained automatically using the private key of the client (which you can download from the API provider). See examples/service_account/ for an example on how to use service account credentials. See developers.google.com for a detailed description of the protocol. This crate implements OAuth for Service Accounts based on the Google APIs; it may or may not work with other providers.

Installed Flow Usage

The installed flow involves showing a URL to the user (or opening it in a browser) and then either prompting the user to enter a displayed code, or make the authorizing website redirect to a web server spun up by this library and running on localhost.

In order to use the interactive method, use the Interactive InstalledFlowReturnMethod; for the redirect method, use HTTPRedirect.

You can implement your own AuthenticatorDelegate in order to customize the flow; the installed flow uses the present_user_url method.

The returned Token will be stored in memory in order to authorize future API requests to the same scopes. The tokens can optionally be persisted to disk by using persist_tokens_to_disk when creating the authenticator.

The following example, which is derived from the (actual and runnable) example in examples/test-installed/, shows the basics of using this crate:

use yup_oauth2::{InstalledFlowAuthenticator, InstalledFlowReturnMethod};

#[tokio::main]
async fn main() {
    // Read application secret from a file. Sometimes it's easier to compile it directly into
    // the binary. The clientsecret file contains JSON like `{"installed":{"client_id": ... }}`
    let secret = yup_oauth2::read_application_secret("clientsecret.json")
        .await
        .expect("clientsecret.json");

    // Create an authenticator that uses an InstalledFlow to authenticate. The
    // authentication tokens are persisted to a file named tokencache.json. The
    // authenticator takes care of caching tokens to disk and refreshing tokens once
    // they've expired.
    let mut auth = InstalledFlowAuthenticator::builder(secret, InstalledFlowReturnMethod::HTTPRedirect)
    .persist_tokens_to_disk("tokencache.json")
    .build()
    .await
    .unwrap();

    let scopes = &["https://www.googleapis.com/auth/drive.file"];

    // token(<scopes>) is the one important function of this crate; it does everything to
    // obtain a token that can be sent e.g. as Bearer token.
    match auth.token(scopes).await {
        Ok(token) => println!("The token is {:?}", token),
        Err(e) => println!("error: {:?}", e),
    }
}

Modules

authenticator	Module contianing the core functionality for OAuth2 Authentication.
authenticator_delegate	Module containing types related to delegates.
error	Module containing various error types.

Structs

AccessToken	Represents an access token returned by oauth2 servers. All access tokens are Bearer tokens. Other types of tokens are not supported.
ApplicationSecret	Represents either 'installed' or 'web' applications in a json secrets file. See ConsoleApplicationSecret for more information
ConsoleApplicationSecret	A type to facilitate reading and writing the json secret file as returned by the google developer console
DeviceFlowAuthenticator	Create an authenticator that uses the device flow.
InstalledFlowAuthenticator	Create an authenticator that uses the installed flow.
ServiceAccountAuthenticator	Create an authenticator that uses a service account.
ServiceAccountKey	JSON schema of secret service account key. You can obtain the key from the Cloud Console at https://console.cloud.google.com/.

Enums

Error	Encapsulates all possible results of the token(...) operation
InstalledFlowReturnMethod	cf. https://developers.google.com/identity/protocols/OAuth2InstalledApp#choosingredirecturi

Functions

parse_application_secret	Read an application secret from a JSON string.
read_application_secret	Read an application secret from a file.
read_service_account_key	Read a service account key from a JSON file. You can download the JSON keys from the Google Cloud Console or the respective console of your service provider.