NEWS


gargle 1.5.2.9000

gargle 1.5.2 (2023-07-20)

gargle 1.5.1 (2023-06-19)

gargle 1.5.0 (2023-06-10)

gargle 1.4.0 (2023-04-15)

Google Compute Engine

Behaviour in a cloud/server context

Everything else

gargle 1.3.0 (2023-01-30)

(Partial) deprecation out-of-band (OOB) auth flow

On February 16, 2022, Google announced the gradual deprecation of the out-of-band (OOB) OAuth flow. OOB still works if the OAuth client is associated with a GCP project that is in testing mode and this is not going away. But OOB is no longer supported for projects in production mode. To be more accurate, some production-mode projects have gotten an extension to permit the use of OOB auth for a bit longer, but that's just a temporary reprieve.

The typical user who will (eventually) be impacted is:

The phased deprecation of OOB is nearly complete and we expect conventional OOB to stop working with the built-in tidyverse OAuth client on February 1, 2023, at the latest.

In preparation for this, gargle has gained support for a new flow, which we call pseudo-OOB (in contrast to conventional OOB). The pseudo-OOB flow is triggered when use_oob = TRUE (an existing convention in gargle and gargle-using packages) and the configured OAuth client is of "Web application" type. The gargle/googledrive/googlesheets4/bigrquery packages should now default to a "Web application" client on RStudio Server, Posit Workbench and Posit Cloud, leading the user through the pseudo-OOB flow. Other than needing to re-auth once, affected users should still find that things "just work".

Read the vignette("auth-from-web") for more.

gargle-specific notion of OAuth client

gargle_oauth_client() is a new constructor for an S3 class by the same name. There are two motivations:

oauth_app_from_json() has therefore been (soft) deprecated, in favor of a new function gargle_oauth_client_from_json(), which is the preferred way to instantiate an OAuth client, since the downloaded JSON conveys the client type and redirect URI(s). As a bridging measure, gargle_oauth_client currently inherits from httr's oauth_app, but this probably won't be true in the long-term.

gargle_client(type =) replaces gargle_app().

Google Compute Engine and Google Kubernetes Engine

credentials_gce() no longer asks the user about initiating an OAuth cache, which is not relevant to that flow (#221).

gce_instance_service_accounts() is a newly exported utility that exposes the service accounts available from the metadata server for the current instance (#234).

The global option "gargle.gce.timeout" is newly documented in credentials_gce(). This controls the timeout, in seconds, for requests to the metadata server. The default value (or strategy) for setting this should often suffice, but the option exists for those with an empirical need to increase the timeout (#186, #195).

vignette("non-interactive-auth") has a new section "Workload Identity on Google Kubernetes Engine (GKE)" that explains how gargle supports the use of workload identity for applications running on GKE. This is the recommended method of auth in R code running on GKE that needs to access other Google Cloud services, such as the BigQuery API (#197, #223, @MarkEdmondson1234).

Credential function registry

It's gotten a bit easier to work with the credential registry. The primary motivation is that, for example, on Google Compute Engine, you might actually want to suppress auth with the default service account and auth as a normal user instead. This is especially likely to come up with gmailr / the Gmail API.

gargle 1.2.1 (2022-09-08)

Dependency changes

gargle 1.2.0 (2021-07-02)

Workload identity federation

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 credentials_external_account().

This new feature is still experimental and currently only supports AWS. This blog post provides a good high-level introduction to workload identity federation.

Other changes

The email argument of 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 [email protected] or [email protected].

gargle now throws errors via cli::cli_abort(), which means error messages now have the same styling as informational messages.

Dependency changes

aws.ec2metadata and aws.signature are new in Suggests.

gargle 1.1.0 (2021-04-02)

OAuth token cache

Two changes affect stored user OAuth tokens:

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:

User interface

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_verbosity() replaces 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:

The helpers with_gargle_verbosity() and local_gargle_verbosity() make it easy to temporarily modify the verbosity level, in the spirit of the withr package.

Other changes

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).

gargle_oob_default() returns 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_response() and 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.

Dependency changes

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.

gargle 1.0.0 (2021-03-03)

gargle 0.5.0 (2020-05-06)

gargle 0.4.0 (2019-10-04)

gargle 0.3.1 (2019-07-26)

gargle 0.3.0 (2019-06-27)

gargle 0.2.0 (2019-06-11)

gargle 0.1.3 (2019-06-03)