gmailr: Access the 'Gmail' 'RESTful' API

gm_token_write

R Documentation

Write/read a gmailr user token

Description

This pair of functions writes an OAuth2 user token to file and reads it back in. This is rarely necessary when working in your primary, interactive computing environment. In that setting, it is recommended to lean into the automatic token caching built-in to gmailr / gargle. However, when preparing a user token for use elsewhere, such as in CI or in a deployed data product, it can be useful to take the full control granted by gm_token_write() and gm_token_read().

Below is an outline of the intended workflow, but you will need to fill in particulars, such as filepaths and environment variables:

Do auth in your primary, interactive environment as the target user, with the desired OAuth client and scopes.
```
gm_auth_configure()
gm_auth("jane@example.com", cache = FALSE)
```
Confirm you are logged in as the intended user:
```
gm_profile()
```

Write the current token to file:

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

In the deployed, non-interactive setting, 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"
)
```

Usage

gm_token_write(token = gm_token(), path = "gmailr-token.rds", key = NULL)

gm_token_read(path = "gmailr-token.rds", key = NULL)

Arguments

`token`	A token with class Token2.0 or an object of httr's class `request`, i.e. a token that has been prepared with `httr::config()` and has a Token2.0 in the `auth_token` component.
`path`	The path to write to (`gm_token_write()`) or to read from (`gm_token_read()`).
`key`	Encryption key, as implemented by httr2's secret functions. If absent, a built-in `key` is used. If supplied, the `key` should usually be the name of an environment variable whose value was generated with `gargle::secret_make_key()` (which is a copy of `httr2::secret_make_key()`). The `key` argument of `gm_token_read()` must match the `key` used in `gm_token_write()`.

Security

gm_token_write() and gm_token_read() have a more security-oriented implementation than the default token caching strategy. OAuth2 user tokens are somewhat opaque by definition, because they aren't written to file in a particularly transparent format. However, gm_token_write() always applies some additional obfuscation to make such credentials even more resilient against scraping by an automated tool. However, a knowledgeable R programmer could decode the credential with some effort. The default behaviour of gm_token_write() (called without key) is suitable for tokens stored in a relatively secure place, such as on Posit Connect within your organization.

To prepare a stored credential for exposure in a more public setting, such as on GitHub or CRAN, you must actually encrypt it, using a key known only to you. You must make the encryption key available via a secure environment variable in any setting where you wish to decrypt and use the token, such as on GitHub Actions.

r-lib/gmailr documentation built on Nov. 5, 2023, 6:22 a.m.