Authorize bigrquery to view and manage your BigQuery projects. This function is a
wrapper around gargle::token_fetch()
.
By default, you are directed to a web browser, asked to sign in to your Google account, and to grant bigrquery permission to operate on your behalf with Google BigQuery. By default, with your permission, these user credentials are cached in a folder below your home directory, from where they can be automatically refreshed, as necessary. Storage at the user level means the same token can be used across multiple projects and tokens are less likely to be synced to the cloud by accident.
If you are interacting with R within a browser (applies to RStudio Server,
Posit Workbench, and Posit Cloud), you need a variant of this flow,
known as out-of-band auth ("oob"). If this does not happen
automatically, you can request it yourself with use_oob = TRUE
or,
more persistently, by setting an option via
options(gargle_oob_default = TRUE)
.
bq_auth(
email = gargle::gargle_oauth_email(),
path = NULL,
scopes = c("https://www.googleapis.com/auth/bigquery",
"https://www.googleapis.com/auth/cloud-platform"),
cache = gargle::gargle_oauth_cache(),
use_oob = gargle::gargle_oob_default(),
token = NULL
)
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()
.
JSON identifying the service account, in one of the forms
supported for the txt
argument of jsonlite::fromJSON()
(typically, a
file path or JSON string).
A character vector of scopes to request. Pick from those listed at https://developers.google.com/identity/protocols/oauth2/scopes.
Specifies the OAuth token cache. Defaults to the option named
"gargle_oauth_cache"
, retrieved via gargle_oauth_cache()
.
Whether to prefer out-of-band authentication. Defaults to the
value returned by gargle_oob_default()
.
A token with class Token2.0 or an object of
httr's class request
, i.e. a token that has been prepared with
httr::config()
and has a Token2.0 in the
auth_token
component.
Most users, most of the time, do not need to call bq_auth()
explicitly -- it is triggered by the first action that requires
authorization. Even when called, the default arguments often suffice.
However, when necessary, this function allows the user to explicitly:
Declare which Google identity to use, via an email address. If there
are multiple cached tokens, this can clarify which one to use. It can
also force bigrquery to switch from one identity to another. If
there's no cached token for the email, this triggers a return to the
browser to choose the identity and give consent. You can specify just
the domain by using a glob pattern. This means that a script
containing email = "*@example.com"
can be run without further
tweaks on the machine of either alice@example.com
or
bob@example.com
.
Use a service account token or workload identity federation.
Bring their own Token2.0.
Specify non-default behavior re: token caching and out-of-bound authentication.
Customize scopes.
For details on the many ways to find a token, see
gargle::token_fetch()
. For deeper control over auth, use
bq_auth_configure()
to bring your own OAuth client or API key.
Read more about gargle options, see gargle::gargle_options.
Other auth functions:
bq_auth_configure()
,
bq_deauth()
if (FALSE) {
## load/refresh existing credentials, if available
## otherwise, go to browser for authentication and authorization
bq_auth()
## force use of a token associated with a specific email
bq_auth(email = "jenny@example.com")
## force a menu where you can choose from existing tokens or
## choose to get a new one
bq_auth(email = NA)
## use a 'read only' scope, so it's impossible to change data
bq_auth(
scopes = "https://www.googleapis.com/auth/devstorage.read_only"
)
## use a service account token
bq_auth(path = "foofy-83ee9e7c9c48.json")
}