Consult httr's oob option; improve docs

Closes #102

NEWS.md

@@ -1,5 +1,7 @@
 # gargle (development version)
 
+* gargle consults the option `"httr_oob_default"`, if the option `"gargle_oob_default"` is unset. This is part of an effort to automatically detect the need for out-of-bound auth in more situations (#102).
+
 * `credentials_service_account()` checks explicitly that `type` is `"service_account"`. This makes it easier to detect a common mistake, where the JSON for an OAuth client is provided instead of the JSON representing a service account (#93).
 
 * In a non-interactive context, gargle will use a cached OAuth token, if it discovers (at least) one, even if the user has not given explicit instructions. We emit a recommendation that the user make their intent unambiguous and link to the vignette on non-interactive auth (#92).

R/gargle-package.R

@@ -52,14 +52,19 @@ gargle_oauth_email <- function() {
 #' @rdname gargle_options
 #' @export
 #' @section `gargle_oob_default`:
-#' `gargle_oob_default()` returns the option named "gargle_oob_default",
-#' defaulting to `FALSE`. This controls whether to prefer "out of band"
-#' authentication. This is ultimately passed to [httr::init_oauth2.0()] as
-#' `use_oob`. If `FALSE` (and httpuv is installed), a local webserver is used
-#' for the OAuth dance. Otherwise, user gets a URL and prompt for a validation
-#' code.
+#' `gargle_oob_default()` returns the option named "gargle_oob_default", falls
+#' back to the option named "httr_oob_default", and eventually defaults to
+#' `FALSE`. This controls whether to prefer "out of band" authentication. This
+#' is ultimately passed to [httr::init_oauth2.0()] as `use_oob`. If `FALSE` (and
+#' httpuv is installed), a local webserver is used for the OAuth dance.
+#' Otherwise, user gets a URL and prompt for a validation code.
+#'
+#' Read more about "out of band" authentication in the vignette [Auth when using
+#' R in the browser](https://gargle.r-lib.org/articles/auth-from-web.html).
 gargle_oob_default <- function() {
-  getOption("gargle_oob_default", default = FALSE)
+  getOption("gargle_oob_default") %||%
+    getOption("httr_oob_default") %||%
+    FALSE
 }
 
 #' @rdname gargle_options

tests/testthat/test-assets.R

@@ -1,7 +1,7 @@
 test_that("default options", {
   withr::local_options(list(
     gargle_oauth_cache = NULL,
-    gargle_oob_default = NULL,
+    gargle_oob_default = NULL, httr_oob_default = NULL,
     gargle_oauth_email = NULL,
     gargle_quiet       = NULL
   ))
@@ -11,6 +11,22 @@ test_that("default options", {
   expect_true(gargle_quiet())
 })
 
+test_that("gargle_oob_default() consults gargle's option before httr's", {
+  withr::local_options(list(
+    gargle_oob_default = TRUE,
+    httr_oob_default = FALSE
+  ))
+  expect_true(gargle_oob_default())
+})
+
+test_that("gargle_oob_default() consults httr's option", {
+  withr::local_options(list(
+    gargle_oob_default = NULL,
+    httr_oob_default = TRUE
+  ))
+  expect_true(gargle_oob_default())
+})
+
 test_that("gargle API key", {
   key <- gargle_api_key()
   expect_true(is_string(key))

vignettes/auth-from-web.Rmd

@@ -17,9 +17,9 @@ knitr::opts_chunk$set(
 If you are working with R in a web-based context, like [RStudio Server](https://www.rstudio.com/products/rstudio-server/) or [Cloud](https://rstudio.cloud), your experience of browser-based auth flows will be
 different from those using R, directly in the Console or through an IDE. You need to use **out-of-band authentication**, sometimes denoted "oob". After the usual auth dance, instead of seeing "authentication successful, return to R!", you are presented with an authorization code to copy and paste back into your R session.
 
-The need to use oob auth can sometimes be detected automatically. For example, oob auth is always used when the httpuv package is not installed. We have plans in gargle to automatically detect even more contexts that require oob auth (https://github.com/r-lib/gargle/issues/102). But in the meantime ...
+The need to use oob auth can sometimes be detected automatically. For example, oob auth is always used when the httpuv package is not installed. However, gargle and httr currently fail to detect some other situations where oob is necessary. In these case, the user needs to recognize the situation and explicitly request oob auth.
 
-When oob auth is attempted in a setting where it is doomed to fail, you are redirected to localhost on port 1410 and receive an error along these lines:
+Here's a typical presentation of this problem: during auth, you are redirected to localhost on port 1410 and receive an error along these lines:
 
 ```
 Chrome: This site can't be reached; localhost refused to connect.
@@ -121,6 +121,6 @@ The normal, non-oob auth web flow should work again now.
 
 ## Further reading
 
-[Generating OAuth tokens for a server using httr](https://support.rstudio.com/hc/en-us/articles/217952868-Generating-OAuth-tokens-from-a-server) covers some of the same ground, although for the httr package. gargle provides a Google-specific interface to httr. The main thing to remember is that gargle (and gargle-using packages) refer to the `gargle_oob_default` option, not `httr_oob_default`.
+[Generating OAuth tokens for a server using httr](https://support.rstudio.com/hc/en-us/articles/217952868-Generating-OAuth-tokens-from-a-server) covers some of the same ground, although for the httr package. gargle provides a Google-specific interface to httr. gargle first consults the `gargle_oob_default` option and, if that is undefined, also consults the `httr_oob_default` option.
 
 If you're creating content to be deployed (for example on [shinyapps.io](https://www.shinyapps.io) or [RStudio Connect](https://www.rstudio.com/products/connect/)), you will also need to consider how the [deployed content will authenticate non-interactively](https://gargle.r-lib.org/articles/non-interactive-auth.html).