How to use gargle for auth in a client package

Key choices

Getting a token requires several pieces of information and there are stark differences in how much users (need to) know or control about this process. Let’s review them, with an eye towards identifying the responsibilities of the package author versus the user.

• Overall config: OAuth client and API key. Who provides?
• Token-level properties: Google identity (email) and scopes.
• Request-level: Who manages tokens and injects them into requests?

# googledrive::
drive_auth <- function(email = gargle::gargle_oauth_email(),
                       path = NULL,
                       scopes = "https://www.googleapis.com/auth/drive",
                       cache = gargle::gargle_oauth_cache(),
                       use_oob = gargle::gargle_oob_default(),
                       token = NULL) {
  # this catches a common error, where the user passes JSON for an OAuth client
  # to the `path` argument, which only expects a service account token
  gargle::check_is_service_account(path, hint = "drive_auth_configure")

  cred <- gargle::token_fetch(
    scopes = scopes,
    client = drive_oauth_client() %||% <BUILT_IN_DEFAULT_CLIENT>,
    email = email,
    path = path,
    package = "googledrive",
    cache = cache,
    use_oob = use_oob,
    token = token
  )
  if (!inherits(cred, "Token2.0")) {
    # throw an informative error here
  }
  .auth$set_cred(cred)
  .auth$set_auth_active(TRUE)

  invisible()
}

.auth <- NULL

.onLoad <- function(libname, pkgname) {
  utils::assignInMyNamespace(
    ".auth",
    gargle::init_AuthState(package = "googledrive", auth_active = TRUE)
  )
  
  # other stuff
}

library(googledrive)

# first: download the OAuth client as a JSON file
drive_auth_configure(
  path = "/path/to/the/JSON/that/was/downloaded/from/gcp/console.json"
)

drive_oauth_client()
#> <gargle_oauth_client>
#> name: acme-corp-google-client
#> id: 123456789.apps.googleusercontent.com
#> secret: <REDACTED>
#> type: installed
#> redirect_uris: http://localhost

library(googledrive)

drive_auth_configure(api_key = "123456789")

drive_api_key()
#> "123456789"

# googledrive::
drive_auth(email = "[email protected]")

# googledrive::
drive_auth <- function(email = gargle::gargle_oauth_email(),
                       path = NULL,
                       scopes = "https://www.googleapis.com/auth/drive",
                       cache = gargle::gargle_oauth_cache(),
                       use_oob = gargle::gargle_oob_default(),
                       token = NULL) { ... }

# googledrive::
drive_auth(scopes = "https://www.googleapis.com/auth/drive.readonly")

Overview of mechanics

Here’s a concrete outline of how one could set up a client package to get its auth functionality from gargle.

1. Add gargle to your package’s Imports.
2. Create a file R/YOURPKG_auth.R.
3. Create an internal gargle::AuthClass object to hold auth state. Follow the googledrive example above.
4. Define standard functions for the auth interface between gargle and your package; do this in R/YOURPKG_auth.R. Examples: tidyverse/googledrive/R/drive_auth.R and r-dbi/bigrquery/R/bq_auth.R.
5. Use gargle’s roxygen helpers to create the docs for your auth functions. This relieves you from writing docs and you inherit standard wording. See previously cited examples for inspiration.
6. Use the functions YOURPKG_token() and YOURPKG_api_key() (defined in the standard auth interface) to insert a token or API key in your package’s requests.

Getting that first token

I focus on early use, by the naive user, with the OAuth flow. When the user first calls a high-level googledrive function such as drive_find(), a Drive request is ultimately generated with a call to googledrive::request_generate(). Here is its definition, at least approximately:

# googledrive::
request_generate <- function(endpoint = character(),
                             params = list(),
                             key = NULL,
                             token = drive_token()) {
  ept <- drive_endpoint(endpoint)
  if (is.null(ept)) {
    # throw error about unrecognized endpoint
  }

  ## modifications specific to googledrive package
  params$key <- key %||% params$key %||%
    drive_api_key() %||% <BUILT_IN_DEFAULT_API_KEY>
  if (!is.null(ept$parameters$supportsAllDrives)) {
    params$supportsAllDrives <- TRUE
  }

  req <- gargle::request_develop(endpoint = ept, params = params)
  gargle::request_build(
    path = req$path,
    method = req$method,
    params = req$params,
    body = req$body,
    token = token
  )
}

googledrive::request_generate() is a thin wrapper around gargle::request_develop() and gargle::request_build() that only implements details specific to googledrive, before delegating to more general functions in gargle. The vignette("request-helper-functions") documents these gargle functions.

googledrive::request_generate() gets a token with drive_token(), which is defined like so:

# googledrive::
drive_token <- function() {
  if (isFALSE(.auth$auth_active)) {
    return(NULL)
  }
  if (!drive_has_token()) {
    drive_auth()
  }
  httr::config(token = .auth$cred)
}

where drive_has_token() in a helper defined as:

# googledrive::
drive_has_token <- function() {
  inherits(.auth$cred, "Token2.0")
}

By default, auth is active, and, for a fresh start, we won’t have a token stashed in .auth yet. So this will result in a call to drive_auth() to obtain a credential, which is then cached in .auth$cred for the remainder of the session. All subsequent calls to drive_token() will just spit back this token.

Above, we discussed scenarios where an advanced user might call drive_auth() proactively, with non-default arguments, possibly even loading a service token or using alternative flows, like an external account. Any token loaded in that way is stashed in .auth$cred and will be returned by subsequent calls to drive_token().

Multiple gargle-using packages can use a shared token by obtaining a suitably scoped token with one package, then registering that token with the other packages. For example, the default scope requested by googledrive is also sufficient for operations available in googlesheets4. You could use a shared token like so:

library(googledrive)
library(googlesheets4)

drive_auth(email = "[email protected]") # gets a suitably scoped token
                                           # and stashes for googledrive use

gs4_auth(token = drive_token())            # registers token with googlesheets4

# now work with both packages freely ...

It is important to make sure that the token-requesting package (googledrive, above) is using an OAuth client for which all the necessary APIs and scopes are enabled.

Auth interface

The exported functions like drive_auth(), drive_token(), etc. constitute the auth interface between googledrive and gargle and are centralized in tidyverse/googledrive/R/drive_auth.R. That is a good template for how to use gargle to manage auth in a client package. In addition, the docs for these gargle-backed functions are generated automatically from standard information maintained in the gargle package.

• drive_token() retrieves the current credential, in a form that is ready for inclusion in HTTP requests. If auth_active is TRUE and cred is NULL, drive_auth() is called to obtain a credential. If auth_active is FALSE, NULL is returned; client packages should be designed to fall back to including an API key in affected HTTP requests, if sensible for the API.
• drive_auth() ensures we are dealing with an authenticated user and have a credential on hand with which to place authorized requests. Sets auth_active to TRUE. Can be called directly, but drive_token() will also call it as needed.
• drive_deauth() clears the current token. It might also toggle auth_active, depending on the features of the target API. See below.
• drive_oauth_client() returns .auth$client.
• drive_api_key() returns .auth$api_key.
• drive_auth_configure() can be used to configure auth. This is how an advanced user would enter their own OAuth client and API key into the auth config, in order to affect all subsequent requests.
• drive_user() reports some information about the user associated with the current token. The Drive API offers an actual endpoint for this, which is not true for most Google APIs. Therefore the analogous function in bigrquery, bq_user() is a better general reference.

De-auth

APIs split into two classes: those that can be used, at least partially, without a token and those that cannot. If an API is usable without a token – which is true for the Drive API – such requests must include an API key. Therefore, the auth design for a client package is different for these two types of APIs.

For an API that can be used without a token: drive_deauth() can be used at any time to enter a de-authorized state. It sets auth_active to FALSE and .auth$cred to NULL. In this state, requests are sent out with an API key and no token. This is a great way to eliminate any friction re: auth if there’s no need for it, i.e. if all requests are for resources that are world readable or available to anyone who knows how to ask for it, such as files shared via “Anyone with the link”. The de-authorized state is especially useful in non-interactive settings or where user interaction is indirect, such as via Shiny.

For an API that cannot be used without a token: BigQuery is an example of such an API. bq_deauth() just clears the current token, so that the auth flow starts over the next time a token is needed.

Bring Your Own Client and Key

Advanced users can use their own OAuth client and API key. drive_auth_configure() lives in R/drive_auth.R and it provides the ability to modify the current client and api_key. Recall that drive_oauth_client() and drive_api_key() also exist for targeted, read-only access.

The vignette("get-api-credentials") describes how to get an API key and OAuth client.

Packages that always send a token will omit the API key functionality here.

Changing identities (and more)

One reason for a user to call drive_auth() directly and proactively is to switch from one Google identity to another or to make sure they are presenting themselves with a specific identity. drive_auth() accepts an email argument, which is honored when gargle determines if there is already a suitable token on hand. Here is a sketch of how a user could switch identities during a session, possibly non-interactive:

library(googledrive)

drive_auth(email = "[email protected]")
# do stuff with Google Drive here, with Jane Doe's "work" account

drive_auth(email = "[email protected]")
# do other stuff with Google Drive here, with Jane Doe's "personal" account

drive_auth(path = "/path/to/a/service-account.json")
# do other stuff with Google Drive here, using a service account