Transition from OAuth app to OAuth client

Create OAuth clients with gargle

Create an OAuth client with gargle_oauth_client_from_json() (strongly recommended) or gargle_oauth_client(). Don’t use httr::oauth_app() or the deprecated oauth_app_from_json(). Likewise, use gargle_client(), not the deprecated gargle_app(), and, in a tidyverse package, use tidyverse_client(), not the deprecated tidyverse_app(). This applies to your package’s code and to what you show your users in examples and documentation.

The JSON downloaded from Google Cloud Console records the client’s type and redirect URIs, which is why it’s the preferred way to create a client. gargle ships with JSON for a non-functional client of each type. Here’s the “web” one:

path <- system.file(
  "extdata", "client_secret_web.googleusercontent.com.json",
  package = "gargle"
)
(client <- gargle_oauth_client_from_json(path))
#> <gargle_oauth_client>
#> name: a_project_59aa1797ab7ac4667a77617c3400999c
#> id: abc.apps.googleusercontent.com
#> secret: <REDACTED>
#> type: web
#> redirect_uris: https://www.tidyverse.org/google-callback/
class(client)
#> [1] "gargle_oauth_client" "oauth_app"

The “installed” one is client_secret_installed.googleusercontent.com.json, in the same folder.

Use the client interfaces of AuthState

• Create the auth state with init_AuthState(client = ), not init_AuthState(app = ).
• Set the client with .auth$set_client(), not .auth$set_app().
• Get the client from .auth$client, not .auth$app. The app field exists only for backwards compatibility and $set_client() doesn’t update it.

Pass client to gargle’s token functions

Inside PKG_auth(), you presumably call token_fetch(). Pass the OAuth client as client, not app. Neither is a formal argument of token_fetch(); it’s passed along to credentials_user_oauth2(). Here’s a sketch of googledrive::drive_auth():

drive_auth <- function(...) {
  # code not shown
  cred <- gargle::token_fetch(
    scopes = scopes,
    client = drive_oauth_client() %||% gargle::tidyverse_client(),
    email = email,
    path = path,
    package = "googledrive",
    cache = cache,
    use_oob = use_oob,
    token = token
  )
  # code not shown
}

If you call credentials_user_oauth2() or gargle2.0_token() directly, use their client argument, not app.

Finish the user-facing functions

PKG_auth_configure() should take client as its first argument and should have no app argument. PKG_oauth_client() reveals the user’s configured client and PKG_oauth_app() should not exist.

If your package deprecated app and PKG_oauth_app() during the transition, it’s time to remove them, along with the lifecycle::is_present(app) branch in PKG_auth_configure(). Mention the removal in NEWS.md. Here’s how this looks in googledrive:

drive_auth_configure <- function(client, path, api_key) {
  # code not shown
  .auth$set_client(client)
  # code not shown
}

drive_oauth_client <- function() .auth$client

If your package still has app as the main argument of PKG_auth_configure(), you can’t remove it right away, because your users may be relying on it. Introduce client and PKG_oauth_client() and deprecate app and PKG_oauth_app() for at least one release, following the conventions in vignette("communicate", package = "lifecycle").

Re-document with current gargle

gargle has unexported roxygen helpers that generate standard documentation for auth functions, e.g., #' @eval gargle:::PREFIX_auth_configure_params(). In current gargle:

• PREFIX_auth_configure_description() crosslinks to PREFIX_oauth_client(), not PREFIX_oauth_app().
• PREFIX_auth_configure_params() documents the client argument and crosslinks to gargle_oauth_client_from_json(), which requires gargle (>= 1.3.0).
• PREFIX_auth_configure_params() does not document app.

These helpers run when you re-document, so the gargle version installed at that moment is what matters. Re-document with current gargle after you remove app from PKG_auth_configure(). An older gargle documents app, which leads to an R CMD check warning about a documented argument that’s not in the function’s usage.