yup_oauth2/
lib.rs

1//! This library can be used to acquire oauth2.0 authentication for services.
2//!
3//! For your application to use this library, you will have to obtain an application
4//! id and secret by
5//! [following this guide](https://developers.google.com/youtube/registering_an_application) (for
6//! Google services) respectively the documentation of the API provider you want to connect to.
7//!
8//! # Device Flow Usage
9//! With an application secret you can get started right away, building a `DeviceFlowAuthenticator`
10//! and obtaining tokens from it.
11//!
12//! # Service account "flow"
13//! When using service account credentials, no user interaction is required. The access token
14//! can be obtained automatically using the private key of the client (which you can download
15//! from the API provider). See `examples/service_account/` for an example on how to use service
16//! account credentials. See
17//! [developers.google.com](https://developers.google.com/identity/protocols/OAuth2ServiceAccount)
18//! for a detailed description of the protocol. This crate implements OAuth for Service Accounts
19//! based on the Google APIs; it may or may not work with other providers.
20//!
21//! # Installed Flow Usage
22//! The installed flow involves showing a URL to the user (or opening it in a browser)
23//! and then either prompting the user to enter a displayed code, or make the authorizing
24//! website redirect to a web server spun up by this library and running on localhost.
25//!
26//! In order to use the interactive method, use the `Interactive` `InstalledFlowReturnMethod`;
27//! for the redirect method, use `HTTPRedirect`.
28//!
29//! You can implement your own `AuthenticatorDelegate` in order to customize the flow;
30//! the installed flow uses the `present_user_url` method.
31//!
32//! The returned `Token` will be stored in memory in order to authorize future
33//! API requests to the same scopes. The tokens can optionally be persisted to
34//! disk by using `persist_tokens_to_disk` when creating the authenticator.
35//!
36//! The following example, which is derived from the (actual and runnable) example in
37//! `examples/test-installed/`, shows the basics of using this crate:
38//!
39//! ```test_harness,no_run
40//! use yup_oauth2::{InstalledFlowAuthenticator, InstalledFlowReturnMethod};
41//!
42//! # #[cfg(any(feature = "hyper-rustls", feature = "hyper-tls"))]
43//! #[tokio::main]
44//! async fn main() {
45//!     // Read application secret from a file. Sometimes it's easier to compile it directly into
46//!     // the binary. The clientsecret file contains JSON like `{"installed":{"client_id": ... }}`
47//!     let secret = yup_oauth2::read_application_secret("clientsecret.json")
48//!         .await
49//!         .expect("clientsecret.json");
50//!
51//!     // Create an authenticator that uses an InstalledFlow to authenticate. The
52//!     // authentication tokens are persisted to a file named tokencache.json. The
53//!     // authenticator takes care of caching tokens to disk and refreshing tokens once
54//!     // they've expired.
55//!     let mut auth = InstalledFlowAuthenticator::builder(secret, InstalledFlowReturnMethod::HTTPRedirect)
56//!     .persist_tokens_to_disk("tokencache.json")
57//!     .build()
58//!     .await
59//!     .unwrap();
60//!
61//!     let scopes = &["https://www.googleapis.com/auth/drive.file"];
62//!
63//!     // token(<scopes>) is the one important function of this crate; it does everything to
64//!     // obtain a token that can be sent e.g. as Bearer token.
65//!     match auth.token(scopes).await {
66//!         Ok(token) => println!("The token is {:?}", token),
67//!         Err(e) => println!("error: {:?}", e),
68//!     }
69//! }
70//! ```
71//!
72#![deny(missing_docs)]
73#![cfg_attr(docsrs, feature(doc_cfg))]
74
75pub mod access_token;
76mod application_default_credentials;
77pub mod authenticator;
78pub mod authenticator_delegate;
79pub mod authorized_user;
80pub mod client;
81mod device;
82pub mod error;
83pub mod external_account;
84mod helper;
85mod installed;
86mod refresh;
87pub mod service_account_impersonator;
88
89#[cfg(feature = "service-account")]
90mod service_account;
91
92/// Interface for storing tokens so that they can be re-used. There are built-in memory and
93/// file-based storage providers. You can implement your own by implementing the TokenStorage trait.
94pub mod storage;
95
96mod types;
97
98pub use hyper;
99
100#[cfg(feature = "hyper-rustls")]
101pub use hyper_rustls;
102
103#[cfg(feature = "service-account")]
104#[doc(inline)]
105pub use crate::authenticator::ServiceAccountAuthenticator;
106
107#[cfg(any(feature = "hyper-rustls", feature = "hyper-tls"))]
108pub use crate::authenticator::AccessTokenAuthenticator;
109
110#[cfg(any(feature = "hyper-rustls", feature = "hyper-tls"))]
111pub use crate::client::DefaultHyperClientBuilder;
112pub use crate::client::{CustomHyperClientBuilder, HttpClient, HyperClientBuilder};
113
114#[doc(inline)]
115pub use crate::authenticator::{
116    ApplicationDefaultCredentialsAuthenticator, AuthorizedUserAuthenticator,
117    DeviceFlowAuthenticator, ExternalAccountAuthenticator, InstalledFlowAuthenticator,
118    ServiceAccountImpersonationAuthenticator,
119};
120
121pub use crate::helper::*;
122pub use crate::installed::InstalledFlowReturnMethod;
123
124pub use crate::application_default_credentials::ApplicationDefaultCredentialsFlowOpts;
125#[cfg(feature = "service-account")]
126pub use crate::service_account::ServiceAccountKey;
127
128#[doc(inline)]
129pub use crate::error::Error;
130pub use crate::types::{AccessToken, ApplicationSecret, ConsoleApplicationSecret};
yup_oauth2/lib.rs

yup_oauth2/
lib.rs
