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 app 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.
credentials_user_oauth2(
scopes = NULL,
app = gargle_app(),
package = "gargle",
...
)
A Gargle2.0 token.
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.
An OAuth consumer application, created by httr::oauth_app()
.
Name of the package requesting a token. Used in messages.
Arguments passed on to gargle2.0_token
email
Optional. Allows 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 targetted 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. Use NA
or FALSE
to match nothing and force the OAuth dance in the browser. Use
TRUE
to allow email auto-discovery, if exactly one matching token is
found in the cache. Specify just the domain with a glob pattern, e.g.
"*@example.com"
, to create code that "just works" for both
alice@example.com
and bob@example.com
. Defaults to the option named
"gargle_oauth_email", retrieved by gargle_oauth_email()
.
use_oob
Whether to prefer "out of band" authentication. Defaults to
the option named "gargle_oob_default", retrieved via
gargle_oob_default()
.
cache
Specifies the OAuth token cache. Defaults to the option named
"gargle_oauth_cache", retrieved via gargle_oauth_cache()
.
user_params
Named list holding endpoint specific parameters to pass to the server when posting the request for obtaining or refreshing the access token.
type
content type used to override incorrect server response
credentials
Advanced use only: allows you to completely customise token generation.
Other credential functions:
credentials_app_default()
,
credentials_byo_oauth2()
,
credentials_external_account()
,
credentials_gce()
,
credentials_service_account()
,
token_fetch()
if (FALSE) {
## Drive scope, built-in gargle demo app
scopes <- "https://www.googleapis.com/auth/drive"
credentials_user_oauth2(scopes, app = gargle_app())
## bring your own app
app <- httr::oauth_app(
appname = "my_awesome_app",
key = "keykeykeykeykeykey",
secret = "secretsecretsecret"
)
credentials_user_oauth2(scopes, app)
}
Run the code above in your browser using DataLab