Deploy a token

Demo code

gmailr ships with code for a working demo of the approach described here.

writeLines(list.files(
  system.file("deployed-token-demo", package = "gmailr")
))
#> README.md
#> send-email-byo-encrypted-token.Rmd
#> token-setup.R

We will make reference to these files below.

You may also wish to browse these files on GitHub: https://github.com/r-lib/gmailr/tree/main/inst/deployed-token-demo.

Setup: store a token

This process is recorded in the demo file token-setup.R.

First, complete the OAuth dance in your primary, interactive environment as the target user, using the desired OAuth client and scopes, with cache = FALSE. If you have arranged for the desired OAuth client to be discovered via gm_default_oauth_client(), you only need to call gm_auth():

gm_auth("jane@example.com", cache = FALSE)

If you need to specify the OAuth client explicitly, call gm_auth_configure() prior to gm_auth():

gm_auth_configure("path/to/your/oauth_client.json")
gm_auth("jane@example.com", cache = FALSE)

You may wish to confirm that you are logged in as the intended user:

gm_profile()

Now, write the current gmailr token to file. If you are deploying to somewhere relatively private, such as a server accessible only within your organization, you don’t need to provide any arguments to gm_token_write(). But you’ll often want to specify the target path:

gm_token_write(path = "path/to/gmailr-token.rds")

The resulting token file is rather opaque, i.e. a general purpose automated tool can’t easily scrape your credentials from this. But a knowledgeable R programmer could decode the token, if they made an effort.

If the token file will be exposed in a more public location, such as on GitHub or inside a CRAN package, it should be encrypted. You can generate an encryption key with gargle::secret_make_key() (this is a copy of httr2::secret_make_key(), which you could also use). In your local development environment, make this key available as an environment variable, e.g. GMAILR_KEY, probably with a line like this in your .Renviron file:

GMAILR_KEY=xxxxxxxxxxxxxxx

The usethis::edit_r_environ() function can be handy for creating and/or editing this file.

Once you’ve set up the encryption key, you can use it in gm_token_write(key =):

gm_token_write(
  path = "path/to/gmailr-token.rds",
  key = "GMAILR_KEY"
)

You must make this same key available as a secret or secure environment variable in the deployed context, e.g. on Posit Connect (https://docs.posit.co/connect/admin/security/#application-environment-variables) or GitHub Actions (https://docs.github.com/en/actions/security-guides/encrypted-secrets).

Usage: load and use token

The demo file send-email-byo-encrypted-token.Rmd is an example of a working Shiny app (Shiny document, in this case) that implements the technique described here..

In the code that’s running in the deployed / unattended setting, use a snippet like this to read the token from file and tell gmailr to use it:

gm_auth(token = gm_token_read(
  path = "path/to/gmailr-token.rds",
  key = "GMAILR_KEY"
))

If you did not specify the key in gm_token_write(), omit it from the gm_token_read() call as well. If you did specify the key in gm_token_write(), use the same key in gm_token_read().

Ongoing maintenance

The saved credential contains a refresh token, which is potentially rather long-lived, but is still perishable. As long as the refresh token remains valid, it can be used to obtain short-lived access tokens, without any user interaction. This is sometimes referred to as “refreshing the token” and this is what’s happening behind the scenes with a deployed token.

However, there are many ways that the refresh token can become invalid, for example:

• In the Security settings for their Google user account, a user can remove access associated with a specific OAuth client or app. This invalidates any token obtained with that client.
• If a token isn’t used for a period of time (~6 months), it becomes invalid.
• If an OAuth client is deleted or its host project disables the Gmail API, any associated tokens become invalid.
• There’s a limit to how many refresh tokens a user can have. If a user repeatedly mints new tokens (versus refreshing existing ones), older tokens will “fall off the end” and become invalid.
• If an OAuth client is in “testing” mode, all associated tokens have a limited lifetime, usually 1 week.

The general topic of refresh token expiration is documented in https://developers.google.com/identity/protocols/oauth2#expiration.

If the token becomes invalid, token refresh will fail and your deployed product will no longer be able to access the Gmail API on behalf of the target user. It is a very good idea to rig your code to surface this failure in a very transparent way, so it’s easier for you to diagnose this problem. Functions like gm_profile(), gargle::token_tokeninfo(), and gargle::token_userinfo() can be useful for this. If the stored token can no longer be refreshed, the only remedy is to obtain, store, possibly encrypt, and deploy a new token, using the exact same process as before.