credentials_user_oauth2: Get an OAuth token for a user

In r-lib/gargle: Utilities for Working with Google APIs

Get an OAuth token for a user

Description

Consults the token cache for a suitable OAuth token and, if unsuccessful, gets a token via the browser flow. A cached token is suitable if it's compatible with the user's request in this sense:

• OAuth client must be same.

• Scopes must be same.

• Email, if provided, must be same. If specified email is a glob pattern like "*@example.com", email matching is done at the domain level.

gargle is very conservative about using OAuth tokens discovered in the user's cache and will generally seek interactive confirmation. Therefore, in a non-interactive setting, it's important to explicitly specify the "email" of the target account or to explicitly authorize automatic discovery. See gargle2.0_token(), which this function wraps, for more. Non-interactive use also suggests it might be time to use a service account token or workload identity federation.

Usage

credentials_user_oauth2(
  scopes = NULL,
  client = gargle_client(),
  package = "gargle",
  ...,
  app = deprecated()
)

Arguments

scopes	A character vector of scopes to request. Pick from those listed at https://developers.google.com/identity/protocols/oauth2/scopes. For certain token flows, the "https://www.googleapis.com/auth/userinfo.email" scope is unconditionally included. This grants permission to retrieve the email address associated with a token; gargle uses this to index cached OAuth tokens. This grants no permission to view or send email and is generally considered a low-value scope.
client	A Google OAuth client, preferably constructed via gargle_oauth_client_from_json(), which returns an instance of gargle_oauth_client. For backwards compatibility, for a limited time, gargle will still accept an "OAuth app" created with httr::oauth_app().
package	Name of the package requesting a token. Used in messages.
...	Arguments passed on to gargle2.0_token email Optional. If specified, email can take several different forms: "[e-mail]", i.e. an actual email address. This allows the user to target a specific Google identity. If specified, this is used for token lookup, i.e. to determine if a suitable token is already available in the cache. If no such token is found, email is used to pre-select the targeted Google identity in the OAuth chooser. (Note, however, that the email associated with a token when it's cached is always determined from the token itself, never from this argument). "*@example.com", i.e. a domain-only glob pattern. This can be helpful if you need code that "just works" for both [e-mail] and [e-mail]. TRUE means that you are approving email auto-discovery. If exactly one matching token is found in the cache, it will be used. FALSE or NA mean that you want to ignore the token cache and force a new OAuth dance in the browser. Defaults to the option named "gargle_oauth_email", retrieved by gargle_oauth_email() (unless a wrapper package implements different default behavior). use_oob Whether to use out-of-band authentication (or, perhaps, a variant implemented by gargle and known as "pseudo-OOB") when first acquiring the token. Defaults to the value returned by gargle_oob_default(). Note that (pseudo-)OOB auth only affects the initial OAuth dance. If we retrieve (and possibly refresh) a cached token, use_oob has no effect. If the OAuth client is provided implicitly by a wrapper package, its type probably defaults to the value returned by gargle_oauth_client_type(). You can take control of the client type by setting options(gargle_oauth_client_type = "web") or options(gargle_oauth_client_type = "installed"). cache Specifies the OAuth token cache. Defaults to the option named "gargle_oauth_cache", retrieved via gargle_oauth_cache(). credentials Advanced use only: allows you to completely customise token generation.
app	Replaced by the client argument.

Value

A Gargle2.0 token.

See Also

Other credential functions: credentials_app_default(), credentials_byo_oauth2(), credentials_external_account(), credentials_gce(), credentials_service_account(), token_fetch()

Examples

## Not run: 
# Drive scope, built-in gargle demo client
scopes <- "https://www.googleapis.com/auth/drive"
credentials_user_oauth2(scopes, client = gargle_client())

# bring your own client
client <- gargle_oauth_client_from_json(
  path = "/path/to/the/JSON/you/downloaded/from/gcp/console.json",
  name = "my-nifty-oauth-client"
)
credentials_user_oauth2(scopes, client)

## End(Not run)

r-lib/gargle documentation built on Sept. 10, 2023, 10:38 a.m.