yup_oauth2/
lib.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
//! 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](https://developers.google.com/youtube/registering_an_application) (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](https://developers.google.com/identity/protocols/OAuth2ServiceAccount)
//! 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:
//!
//! ```test_harness,no_run
//! use yup_oauth2::{InstalledFlowAuthenticator, InstalledFlowReturnMethod};
//!
//! # #[cfg(any(feature = "hyper-rustls", feature = "hyper-tls"))]
//! #[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),
//!     }
//! }
//! ```
//!
#![deny(missing_docs)]
#![cfg_attr(docsrs, feature(doc_cfg))]

pub mod access_token;
mod application_default_credentials;
pub mod authenticator;
pub mod authenticator_delegate;
pub mod authorized_user;
pub mod client;
mod device;
pub mod error;
pub mod external_account;
mod helper;
mod installed;
mod refresh;
pub mod service_account_impersonator;

#[cfg(feature = "service-account")]
mod service_account;

/// Interface for storing tokens so that they can be re-used. There are built-in memory and
/// file-based storage providers. You can implement your own by implementing the TokenStorage trait.
pub mod storage;

mod types;

pub use hyper;

#[cfg(feature = "hyper-rustls")]
pub use hyper_rustls;

#[cfg(feature = "service-account")]
#[doc(inline)]
pub use crate::authenticator::ServiceAccountAuthenticator;

#[cfg(any(feature = "hyper-rustls", feature = "hyper-tls"))]
pub use crate::authenticator::AccessTokenAuthenticator;

#[cfg(any(feature = "hyper-rustls", feature = "hyper-tls"))]
pub use crate::client::DefaultHyperClientBuilder;
pub use crate::client::{CustomHyperClientBuilder, HttpClient, HyperClientBuilder};

#[doc(inline)]
pub use crate::authenticator::{
    ApplicationDefaultCredentialsAuthenticator, AuthorizedUserAuthenticator,
    DeviceFlowAuthenticator, ExternalAccountAuthenticator, InstalledFlowAuthenticator,
    ServiceAccountImpersonationAuthenticator,
};

pub use crate::helper::*;
pub use crate::installed::InstalledFlowReturnMethod;

pub use crate::application_default_credentials::ApplicationDefaultCredentialsFlowOpts;
#[cfg(feature = "service-account")]
pub use crate::service_account::ServiceAccountKey;

#[doc(inline)]
pub use crate::error::Error;
pub use crate::types::{AccessToken, ApplicationSecret, ConsoleApplicationSecret};