Expand description
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),
}
}
Re-exports§
pub use crate::authenticator::AccessTokenAuthenticator;
pub use crate::client::DefaultHyperClientBuilder;
pub use crate::client::CustomHyperClientBuilder;
pub use crate::client::HttpClient;
pub use crate::client::HyperClientBuilder;
pub use hyper;
pub use hyper_rustls;
Modules§
- access_
token - pseudo authenticator for use with plain access tokens. If you use a specialized service to manage your OAuth2-tokens you may get just the fresh generated access token from your service. The intention behind this is that if two services using the same refresh token then each service will invalitate the access token of the other service by generating a new token.
- authenticator
- Module containing the core functionality for OAuth2 Authentication.
- authenticator_
delegate - Module containing types related to delegates.
- authorized_
user - This module provides a token source (
GetToken
) that obtains tokens using user credentials for use by software (i.e., non-human actors) to get access to Google services. - client
- Module containing the HTTP client used for sending requests
- error
- Module containing various error types.
- external_
account - This module provides a token source (
GetToken
) that obtains tokens using workload identity federation for use by software (i.e., non-human actors) to get access to Google services. - service_
account_ impersonator - This module provides an authenticator that uses authorized user secrets to generate impersonated service account tokens.
- storage
- 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.
Structs§
- Access
Token - Represents a token returned by oauth2 servers. All tokens are Bearer tokens. Other types of tokens are not supported.
- Application
Default Credentials Authenticator - Create an authenticator that uses a application default credentials.
- Application
Default Credentials Flow Opts - Provide options for the Application Default Credential Flow, mostly used for testing
- Application
Secret - Represents either ‘installed’ or ‘web’ applications in a json secrets file.
See
ConsoleApplicationSecret
for more information - Authorized
User Authenticator - Create an authenticator that uses an authorized user credentials.
- Console
Application Secret - A type to facilitate reading and writing the json secret file as returned by the google developer console
- Device
Flow Authenticator - Create an authenticator that uses the device flow.
- External
Account Authenticator - Create an authenticator that uses an external account credentials.
- Installed
Flow Authenticator - Create an authenticator that uses the installed flow.
- Service
Account Authenticator - Create an authenticator that uses a service account.
- Service
Account Impersonation Authenticator - Create a access token authenticator that uses user secrets to impersonate a service account.
- Service
Account Key - JSON schema of secret service account key.
Enums§
- Error
- Encapsulates all possible results of the
token(...)
operation - Installed
Flow Return Method - Method by which the user agent return token to this application.
Functions§
- parse_
application_ secret - Read an application secret from a JSON string.
- parse_
service_ account_ key - Read a service account key from a JSON string.
- read_
application_ secret - Read an application secret from a file.
- read_
authorized_ user_ secret - Read an authorized user secret from a JSON file. You can obtain it by running on the client:
gcloud auth application-default login
. The file should be on Windows in:%APPDATA%/gcloud/application_default_credentials.json
for other systems:$HOME/.config/gcloud/application_default_credentials.json
. - read_
external_ account_ secret - Read an external account secret from a JSON 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.