CRAN release: 2022-09-08
Help files below
man/have been re-generated, so that they give rise to valid HTML5. (This is the impetus for this release, to keep the package safely on CRAN.)
We have switched to newer oauth2.googleapis.com-based OAuth2 URIs, moving away from the accounts.google.com and googleapis.com/oauth2 equivalents.
CRAN release: 2021-07-02
credentials_external_account() is a new function that implements “workload identity federation”, a new (as of April 2021) keyless authentication mechanism. This allows applications running on a non-Google Cloud platform, such as AWS, to access Google Cloud resources without using a conventional service account token, eliminating the security problem posed by long-lived, powerful service account credential files.
credentials_external_account() has been inserted into the default registry of credential-fetchers tried by
token_fetch(), which makes it automatically available in certain wrapper packages, such as bigrquery.
credentials_app_default() recognizes the JSON configuration for an external account and passes such a call along to
This new feature is still experimental and currently only supports AWS. This blog post provides a good high-level introduction to workload identity federation.
credentials_user_oauth2() accepts domain-only email specification via a glob pattern. The goal is to make it possible for code like
PKG_auth(email = "*@example.com") to identify a suitable cached token when executed on the machine of either
gargle now throws errors via
cli::cli_abort(), which means error messages now have the same styling as informational messages.
CRAN release: 2021-04-02
Two changes affect stored user OAuth tokens:
- The default cache location has moved, to better align with general conventions around where to cache user data. Here’s how that looks for a typical user:
- Typical before, macOS:
- Typical after, macOS:
- Typical before, Windows:
- Typical after, Windows:
- Typical before, macOS:
- Tokens created with one of the built-in OAuth apps provided by the tidyverse packages are checked for validity. Tokens made with an old app are deleted. Note that we introduced a new OAuth app in gargle v1.0.0 and the previous app could be disabled at any time.
- Nickname of previous tidyverse OAuth app:
- Nickname of tidyverse OAuth app as of gargle v1.0.0:
- Nickname of previous tidyverse OAuth app:
For users who accept all default behaviour around OAuth, these changes just mean you will see some messages about cleaning and moving the token cache. These users can also expect to go through interactive auth (approximately once per package / API), to obtain fresh tokens made with the current tidyverse OAuth app.
If the rolling of the tidyverse OAuth app is highly disruptive to your workflow, this is a good wake-up call that you should be using your own OAuth app or, perhaps, an entirely different auth method, such as using a service account token in non-interactive settings. As always, these articles explain how to take more control of auth: * https://gargle.r-lib.org/articles/get-api-credentials.html * https://gargle.r-lib.org/articles/non-interactive-auth.html
The user interface has gotten more stylish, thanks to the cli package (https://cli.r-lib.org).
All errors thrown by gargle route through
rlang::abort(), providing better access to the backtrace and, potentially, error data. These errors have, at the very least, the
gargle_error class and may also have additional subclasses.
gargle_quiet(). Each such function is (or was) a convenience wrapper to query the option with that name. Therefore, the option named “gargle_verbosity” now replaces “gargle_quiet”. If “gargle_verbosity” is unset, the old “gargle_quiet” is still consulted, but the user is advised to update their usage.
The new “gargle_verbosity” option is more expressive and has three levels:
- “debug”, equivalent to the previous
gargle_quiet = FALSE. Use for debugging and troubleshooting.
- “info” (the default), basically equivalent to the previous
gargle_quiet = TRUE. Since gargle is not a user-facing package, it has very little to say and only emits messages that end users really need to see.
- “silent”, no previous equivalent and of little practical significance. But it can be used to suppress all gargle messages.
There is special error handling when OAuth token refresh fails, due to deletion of the associated OAuth app. This should help users who are relying on the default app provided by a package and, presumably, they need to update that package (#168).
TRUE unconditionally when running in RStudio Server.
response_process() gains a
remember argument. When
TRUE (the default), gargle stores the most recent response internally (with auth tokens redacted). Unexported functions
gargle:::gargle_last_content() facilitate post mortem analysis of, e.g., a failed request (#152).
google.rpc.ErrorInfo errors are explicitly handled now, resulting in a more informative error message.
request_retry() is better able to detect when the per-user quota has been exhausted (vs. the per-project quota), resulting in a more informed choice of backoff.
cli is new in Imports.
rstudioapi is new in Imports.
rappdirs is new in Imports.
httpuv is new in Suggests. We encourage its installation in interactive sessions, if we’re about to initiate OAuth flow, unless it’s clear that out-of-band auth is inevitable.
gargle now relies on testthat >= 3.0.0 and, specifically, uses third edition features.
mockr is new in Suggests, since
testthat::use_mock() is superseded.
CRAN release: 2021-03-03
Better handling of
BadRequesterrors, i.e. more specifics are revealed.
oauth_app_from_jsonnow supports JSON files from the “Web application” client type (#155).
Credentials used in selected client packages have been rolled. Users of bigrquery, googledrive, and googlesheets4 can expect a prompt to re-authorize the “Tidyverse API Packages” when using an OAuth user token. This has no impact on users who use their own OAuth app (i.e. client ID and secret) or those who use service account tokens.
CRAN release: 2020-05-06
Troubleshooting gargle auth is a new vignette.
All user-facing messaging routes through
rlang::inform(), which (as of rlang 0.4.2) prints to standard output in interactive sessions and to standard error in non-interactive sessions (#133). Messaging remains under the control of the
"gargle_quiet"option, which defaults to
Gargle2.0class gains its own
$refresh()method, which removes a token from gargle’s cache when it cannot be refreshed (#79).
field_mask()is a utility function for constructing a Protocol-Buffers-style, JSON-encoded field mask from a named R list.
All R6 classes use the new documentation capabilities that appeared in roxygen2 7.0.0.
response_process()is able to expose details for a wider set of errors.
CRAN release: 2019-10-04
Eliminated uninformative failure when OAuth tokens cached on R <= 3.5 are re-loaded on R >= 3.6. The change to the default serialization version (2 vs. 3) creates an apparent mismatch between a token’s hash and its key. Instead of inexplicably failing, now we attempt to repair the cache and carry on (#109, tidyverse/googledrive#274.
In a non-interactive context, gargle will use a cached OAuth token, if it discovers (at least) one, even if the user has not given explicit instructions. We emit a recommendation that the user make their intent unambiguous and link to the vignette on non-interactive auth (#92).
gargle consults the option
"httr_oob_default", if the option
"gargle_oob_default"is unset. This is part of an effort to automatically detect the need for out-of-bound auth in more situations (#102).
credentials_service_account()checks explicitly that
"service_account". This makes it easier to detect a common mistake, where the JSON for an OAuth client is provided instead of the JSON representing a service account (#93).
CRAN release: 2019-07-26
Non-interactive auth is a new vignette that serves as a guide for any client packages that use gargle for auth.
credentials_app_default()got a small bug fix relating to putting the token in the header (r-dbi/bigrquery#336)
The yes/no asking if it’s OK to cache OAuth tokens prints fully now (r-dbi/bigrquery#333).
CRAN release: 2019-06-27
The unexported functions available for generating standardized docs for
PKG_authfunctions in client packages have been updated.
AuthState$set_api_key()now allow setting a value of
NULL, i.e. these fields are easier to clear.
credentials_byo_oauth2()gains the ability to ingest a token from an object of class
httr::request, i.e. to retrieve the
auth_tokencomponent that holds an object of class
httr::Token2.0that has been processed with
CRAN release: 2019-06-11
New vignette on “How to get your own API credentials”, to help other package authors or users obtain their own API key or OAuth client ID and secret.