[][src]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

As the DeviceFlow involves polling, the DeviceFlowHelper should be used as means to adhere to the protocol, and remain resilient to all kinds of errors that can occur on the way.

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 InstalledFlow 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 InstalledInteractive FlowType; for the redirect method, use InstalledRedirect, with the port number to let the server listen on.

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

The returned Token is stored permanently in the given token storage in order to authorize future API requests to the same scopes.

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

use futures::prelude::*;
use yup_oauth2::GetToken;
use yup_oauth2::{Authenticator, InstalledFlow};

use hyper::client::Client;
use hyper_rustls::HttpsConnector;

use std::path::Path;

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(Path::new("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 = Authenticator::new(
        InstalledFlow::new(secret, yup_oauth2::InstalledFlowReturnMethod::HTTPRedirect(0))

    let s = "https://www.googleapis.com/auth/drive.file".to_string();
    let scopes = vec![s];

    // 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.
    let tok = auth.token(scopes);
    // Finally we print the token.
    let fut = tok.map_err(|e| println!("error: {:?}", e)).and_then(|t| {
        println!("The token is {:?}", t);




Represents either 'installed' or 'web' applications in a json secrets file. See ConsoleApplicationSecret for more information


An authenticator can be used with InstalledFlow's or DeviceFlow's and will refresh tokens as they expire as well as optionally persist tokens to disk.


A type to facilitate reading and writing the json secret file as returned by the google developer console


Uses all default implementations by AuthenticatorDelegate, and makes the trait's implementation usable in the first place.


Uses all default implementations in the FlowDelegate trait.


Implements the Oauth2 Device Flow It operates in two steps:


Serializes tokens to a JSON file on disk.


InstalledFlowImpl provides tokens for services that follow the "Installed" OAuth flow. (See https://www.oauth.com/oauth2-servers/authorization/, https://developers.google.com/identity/protocols/OAuth2InstalledApp).


A storage that remembers values for one session only.


A storage that remembers nothing.


Contains state of pending authentication requests


A scheme for use in hyper::header::Authorization


A token source (GetToken) yielding OAuth tokens for services that use ServiceAccount authorization. This token source caches token and automatically renews expired ones, meaning you do not need (and you also should not) use this with Authenticator. Just use it directly.


JSON schema of secret service account key. You can obtain the key from the Cloud Console at https://console.cloud.google.com/.


Represents a token as returned by OAuth2 servers.



All known authentication types, for suitable constants


cf. https://developers.google.com/identity/protocols/OAuth2InstalledApp#choosingredirecturi


Encapsulates all possible results of a poll_token(...) operation in the Device flow.


All possible outcomes of the refresh flow


Encapsulates all possible results of the token(...) operation


Represents all implemented token types





An internal trait implemented by flows to be used by an authenticator.


A partially implemented trait to interact with the Authenticator


FlowDelegate methods are called when an OAuth flow needs to ask the application what to do in certain cases.


A provider for authorization tokens, yielding tokens valid for a given scope. The api_key() method is an alternative in case there are no scopes or if no user is involved.


Implements a specialized storage to set and retrieve Token instances. The scope_hash represents the signature of the scopes for which the given token should be stored or retrieved. For completeness, the underlying, sorted scopes are provided as well. They might be useful for presentation to the user.



Read an application secret from a JSON string.


Read an application secret from a file.


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.