Startup revert (#46)

* revert startup change

* update news

* add create_AzureR_dir

NAMESPACE

@@ -17,6 +17,7 @@ export(AzureTokenResOwner)
 export(build_authorization_uri)
 export(cert_assertion)
 export(clean_token_directory)
+export(create_AzureR_dir)
 export(decode_jwt)
 export(delete_azure_token)
 export(extract_jwt)

NEWS.md

@@ -2,6 +2,8 @@
 
 - Change the default caching behaviour to disable the cache if running inside Shiny.
 - Update Shiny vignette to clean up redirect page after authenticating (thanks to Tyler Littlefield).
+- Revert the changed behaviour for caching directory creation in 1.3.1.
+- Add a `create_AzureR_dir` function to create the caching directory manually. This can be useful not just for non-interactive sessions, but also Jupyter and R notebooks, which are not _technically_ interactive in the sense that they cannot read user input from a console prompt.
 
 # AzureAuth 1.3.1
 

R/AzureAuth.R

@@ -9,13 +9,19 @@ utils::globalVariables(c("self", "private"))
 }
 
 
-# create a directory for saving creds -- print message if creating
+# create a directory for saving creds -- ask first, to satisfy CRAN requirements
 make_AzureR_dir <- function()
 {
     AzureR_dir <- AzureR_dir()
-    if(!dir.exists(AzureR_dir))
+    if(!dir.exists(AzureR_dir) && interactive())
     {
-        packageStartupMessage("Saving Azure credentials in directory:\n", AzureR_dir)
+        ok <- get_confirmation(paste0(
+            "The AzureR packages can save your authentication credentials in the directory:\n\n",
+            AzureR_dir, "\n\n",
+            "This saves you having to re-authenticate with Azure in future sessions. Create this directory?"))
+        if(!ok)
+            return(invisible(NULL))
+
         dir.create(AzureR_dir, recursive=TRUE)
     }
 }
@@ -24,9 +30,13 @@ make_AzureR_dir <- function()
 #' Data directory for AzureR packages
 #'
 #' @details
-#' AzureAuth saves your authentication credentials in a user-specific directory, so you don't have to reauthenticate in every R session. The default location is determined using the rappdirs package: on recent Windows versions, this will usually be in the location `C:\\Users\\(username)\\AppData\\Local\\AzureR`; on Unix/Linux, it will be in `~/.local/share/AzureR`; and on MacOS, it will be in `~/Library/Application Support/AzureR`. Alternatively, you can specify the location of the directory in the environment variable `R_AZURE_DATA_DIR`. AzureAuth does not modify R's working directory, which significantly lessens the risk of accidentally introducing cached tokens into source control.
+#' AzureAuth can save your authentication credentials in a user-specific directory, using the rappdirs package. On recent Windows versions, this will usually be in the location `C:\\Users\\(username)\\AppData\\Local\\AzureR`. On Unix/Linux, it will be in `~/.local/share/AzureR`, and on MacOS, it will be in `~/Library/Application Support/AzureR`.Alternatively, you can specify the location of the directory in the environment variable `R_AZURE_DATA_DIR`. AzureAuth does not modify R's working directory, which significantly lessens the risk of accidentally introducing cached tokens into source control.
 #'
-#' This directory is also used by other AzureR packages, notably AzureRMR (for storing Resource Manager logins) and AzureGraph (for Microsoft Graph logins). You should not save your own files in it; instead, treat it as something internal to the AzureR packages.
+#' On package startup, if this directory does not exist, AzureAuth will prompt you for permission to create it. It's recommended that you allow the directory to be created, as otherwise you will have to reauthenticate with Azure every time. Note that many cloud engineering tools, including the [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/?view=azure-cli-latest), save authentication credentials in this way. The prompt only appears in an interactive session (in the sense that `interactive()` returns TRUE); if AzureAuth is loaded in a batch script, the directory is not created if it doesn't already exist.
+#'
+#' `create_AzureR_dir` is a utility function to create the caching directory manually. This can be useful not just for non-interactive sessions, but also Jupyter and R notebooks, which are not _technically_ interactive in that `interactive()` returns FALSE.
+#'
+#' The caching directory is also used by other AzureR packages, notably AzureRMR (for storing Resource Manager logins) and AzureGraph (for Microsoft Graph logins). You should not save your own files in it; instead, treat it as something internal to the AzureR packages.
 #'
 #' @return
 #' A string containing the data directory.
@@ -36,6 +46,7 @@ make_AzureR_dir <- function()
 #'
 #' [rappdirs::user_data_dir]
 #'
+#' @rdname AzureR_dir
 #' @export
 AzureR_dir <- function()
 {
@@ -44,3 +55,13 @@ AzureR_dir <- function()
         return(userdir)
     rappdirs::user_data_dir(appname="AzureR", appauthor="", roaming=FALSE)
 }
+
+
+#' @rdname AzureR_dir
+#' @export
+create_AzureR_dir <- function()
+{
+    azdir <- AzureR_dir()
+    if(!dir.exists(azdir))
+        dir.create(azdir, recursive=TRUE)
+}

README.md

@@ -10,7 +10,7 @@ The primary repo for this package is at https://github.com/Azure/AzureAuth; plea
 
 ## Obtaining tokens
 
-The main function in AzureAuth is `get_azure_token`, which obtains an OAuth token from AAD. The token is saved in a user-specific directory; future requests will use the saved token without needing you to reauthenticate. The default location for the token directory is determined using the [rappdirs](https://github.com/r-lib/rappdirs) package, or you can specify the location in the `R_AZURE_DATA_DIR` environment variable. 
+The main function in AzureAuth is `get_azure_token`, which obtains an OAuth token from AAD. The token is cached in a user-specific directory using the [rappdirs](https://github.com/r-lib/rappdirs) package, and future requests will use the cached token without needing you to reauthenticate.
 
 ```r
 library(AzureAuth)
@@ -18,6 +18,8 @@ library(AzureAuth)
 token <- get_azure_token(resource="myresource", tenant="mytenant", app="app_id", ...)
 ```
 
+For reasons of CRAN policy, the first time AzureAuth is loaded, it will prompt you for permission to create this directory. Unless you have a specific reason otherwise, it's recommended that you allow the directory to be created. Note that most other cloud engineering tools save credentials in this way, including Docker, Kubernetes, and the Azure CLI itself. The prompt only appears in an interactive session; if AzureAuth is loaded in a batch script, the directory is not created if it doesn't already exist.
+
 Other supplied functions include `list_azure_tokens`, `delete_azure_token` and `clean_token_directory`, to let you manage the token cache.
 
 AzureAuth supports the following methods for authenticating with AAD: **authorization_code**, **device_code**, **client_credentials**, **resource_owner** and **on_behalf_of**.

man/AzureR_dir.Rd

@@ -2,9 +2,12 @@
 % Please edit documentation in R/AzureAuth.R
 \name{AzureR_dir}
 \alias{AzureR_dir}
+\alias{create_AzureR_dir}
 \title{Data directory for AzureR packages}
 \usage{
 AzureR_dir()
+
+create_AzureR_dir()
 }
 \value{
 A string containing the data directory.
@@ -13,9 +16,13 @@ A string containing the data directory.
 Data directory for AzureR packages
 }
 \details{
-AzureAuth saves your authentication credentials in a user-specific directory, so you don't have to reauthenticate in every R session. The default location is determined using the rappdirs package: on recent Windows versions, this will usually be in the location \verb{C:\\\\Users\\\\(username)\\\\AppData\\\\Local\\\\AzureR}; on Unix/Linux, it will be in \verb{~/.local/share/AzureR}; and on MacOS, it will be in \verb{~/Library/Application Support/AzureR}. Alternatively, you can specify the location of the directory in the environment variable \code{R_AZURE_DATA_DIR}. AzureAuth does not modify R's working directory, which significantly lessens the risk of accidentally introducing cached tokens into source control.
+AzureAuth can save your authentication credentials in a user-specific directory, using the rappdirs package. On recent Windows versions, this will usually be in the location \verb{C:\\\\Users\\\\(username)\\\\AppData\\\\Local\\\\AzureR}. On Unix/Linux, it will be in \verb{~/.local/share/AzureR}, and on MacOS, it will be in \verb{~/Library/Application Support/AzureR}.Alternatively, you can specify the location of the directory in the environment variable \code{R_AZURE_DATA_DIR}. AzureAuth does not modify R's working directory, which significantly lessens the risk of accidentally introducing cached tokens into source control.
 
-This directory is also used by other AzureR packages, notably AzureRMR (for storing Resource Manager logins) and AzureGraph (for Microsoft Graph logins). You should not save your own files in it; instead, treat it as something internal to the AzureR packages.
+On package startup, if this directory does not exist, AzureAuth will prompt you for permission to create it. It's recommended that you allow the directory to be created, as otherwise you will have to reauthenticate with Azure every time. Note that many cloud engineering tools, including the \href{https://docs.microsoft.com/en-us/cli/azure/?view=azure-cli-latest}{Azure CLI}, save authentication credentials in this way. The prompt only appears in an interactive session (in the sense that \code{interactive()} returns TRUE); if AzureAuth is loaded in a batch script, the directory is not created if it doesn't already exist.
+
+\code{create_AzureR_dir} is a utility function to create the caching directory manually. This can be useful not just for non-interactive sessions, but also Jupyter and R notebooks, which are not \emph{technically} interactive in that \code{interactive()} returns FALSE.
+
+The caching directory is also used by other AzureR packages, notably AzureRMR (for storing Resource Manager logins) and AzureGraph (for Microsoft Graph logins). You should not save your own files in it; instead, treat it as something internal to the AzureR packages.
 }
 \seealso{
 \link{get_azure_token}

vignettes/token.Rmd

@@ -138,13 +138,13 @@ Using the interactive flows (authorization_code and device_code) from within a S
 
 ## Caching
 
-AzureAuth caches tokens based on all the inputs to `get_azure_token`, as listed above. It defines its own directory for cached tokens, using the rappdirs package. On recent Windows versions, this will usually be in the location `C:\Users\(username)\AppData\Local\AzureR`. On Linux, it will be in `~/.local/share/AzureR`, and on MacOS, it will be in `~/Library/Application Support/AzureR`. Alternatively, you can supply your own location in the `R_AZURE_DATA_DIR` environment variable.
+AzureAuth caches tokens based on all the inputs to `get_azure_token`, as listed above. It defines its own directory for cached tokens, using the rappdirs package. On recent Windows versions, this will usually be in the location `C:\Users\(username)\AppData\Local\AzureR`. On Linux, it will be in `~/.local/share/AzureR`, and on MacOS, it will be in `~/Library/Application Support/AzureR`. Note that a single directory is used for all tokens, and the working directory is not touched (which significantly lessens the risk of accidentally introducing cached tokens into source control).
 
-Note that a single directory is used for all tokens, and the working directory is not touched (which significantly lessens the risk of accidentally introducing cached tokens into source control).
+For reasons of CRAN policy, the first time that AzureAuth is loaded, it will prompt you for permission to create this directory. Unless you have a specific reason otherwise, it's recommended that you allow the directory to be created. Note that most other cloud engineering tools save credentials in this way, including Docker, Kubernetes, and the Azure CLI itself. The prompt only appears in an interactive session; if AzureAuth is loaded in a batch script, the directory is not created if it doesn't already exist.
 
 To list all cached tokens on disk, use `list_azure_tokens`. This returns a list of token objects, named according to their MD5 hashes.
 
-To load a token from the cache using its MD5 hash, use `load_azure_token`. To delete a cached token, use `delete_azure_token`. This takes the same inputs as `get_azure_token`, or you can supply an MD5 hash via the `hash` argument. To delete _all_ files in the token directory, use `clean_token_directory`.
+To load a token from the cache using its MD5 hash, use `load_azure_token`. To delete a cached token, use `delete_azure_token`. This takes the same inputs as `get_azure_token`, or you can supply an MD5 hash via the `hash` argument. To delete _all_ cached tokens, use `clean_token_directory`.
 
 ```r
 # list all tokens