create new auth vignette

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: AzureRMR
 Title: Interface to 'Azure Resource Manager'
-Version: 2.4.1
+Version: 2.4.1.9000
 Authors@R: c(
     person("Hong", "Ooi", , "hongooi73@gmail.com", role = c("aut", "cre")),
     person("Microsoft", role="cph")

NEWS.md

@@ -1,3 +1,7 @@
+# AzureRMR 2.4.1.9000
+
+- Replace the old "Service principal" vignette with an "Authentication basics" vignette, which provides more information on common authentication flows.
+
 # AzureRMR 2.4.1
 
 - Fix the `set_tags` method to work when called inside a function (#18).

vignettes/auth.Rmd

@@ -0,0 +1,105 @@
+---
+title: "Authentication basics"
+author: Hong Ooi
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Authentication}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{utf8}
+---
+
+There are a number of ways to authenticate to the Azure Resource Manager API with AzureRMR. This vignette goes through the most common scenarios.
+
+## Interactive authentication
+
+This is the scenario where you're using R interactively, such as in your local desktop or laptop, or in a hosted RStudio Server, Jupyter notebook or ssh session. The first time you authenticate with AzureRMR, you run `create_azure_login()`:
+
+```r
+# on first use
+library(AzureRMR)
+az <- create_azure_login()
+```
+
+Notice that you _don't_ enter your username and password.
+
+AzureRMR will attempt to detect which authentication flow to use, based on your session details. In most cases, it will bring up the Azure Active Directory (AAD) login page in your browser, which is where you enter your user credentials. This is also known as the "authorization code" flow.
+
+There are some complications to be aware of:
+
+- If you are running R in a hosted session, trying to start a browser will usually fail. In this case, specify the device code authentication flow, with the `auth_type` argument:
+
+  ```r
+  az <- create_azure_login(auth_type="device_code")
+  ```
+
+- If you have a personal account that is also a guest in an organisational tenant, you may have to specify your tenant explicitly:
+
+  ```r
+  az <- create_azure_login(tenant="yourtenant")
+  ```
+
+- By default, AzureRMR identifies itself using the Azure CLI app registration ID. You can also supply your own app ID if you have one, for example if you want to restrict access to a specific subscription or resource group. See "Creating a custom app registration" below for more information.
+
+  ```r
+  az <- create_azure_login(app="yourappid")
+  ```
+
+All of the above arguments can be combined, eg this will authenticate using the device code flow, with an explicit tenant name, and a custom app ID:
+
+```r
+az <- create_azure_login(tenant="yourtenant", app="yourappid", auth_type="device_code")
+```
+
+If needed, you can also supply other arguments that will be passed to `AzureAuth::get_azure_token()`.
+
+Having created the login, in subsequent sessions you run `get_azure_login()`. This will load your previous authentication details, saving you from having to login again. If you specified the tenant in the `create_azure_login()` call, you'll also need to specify it for `get_azure_login()`; the other arguments don't have to be repeated.
+
+```r
+az <- get_azure_login()
+
+# if you specified the tenant in create_azure_login
+az <- get_azure_login(tenant="yourtenant")
+```
+
+## Non-interactive authentication
+
+This is the scenario where you want to use AzureRMR as part of an automated script or unattended session, for example in a deployment pipeline. The appropriate authentication flow in this case is the client credentials flow.
+
+For this scenario, you must have a custom app ID and client secret. On the client side, these are supplied in the `app` and `password` arguments. You must also specify your tenant as AAD won't be able to detect it from a user's credentials.
+
+  ```r
+  az <- create_azure_login(tenant="yourtenant", app="yourccappid", password="client_secret")
+  ```
+
+In the non-interactive scenario, you don't use `get_azure_login()`; instead, you simply call `create_azure_login()` as part of your script.
+
+## Creating a custom app registration
+
+This part is meant mostly for Azure tenant administrators, or users who have the appropriate rights to create AAD app registrations.
+
+You can create your own app registration to authenticate with, if the default Azure CLI app ID is insufficient. In particular, you'll need a custom app ID if you are using AzureRMR in a non-interactive session. If security is a concern, a custom app ID also lets you restrict the scope of the resources that AzureRMR that manipulate.
+
+You can create a new app registration using any of the usual methods. For example to create an app registration in the Azure Portal (`https://portal.azure.com/`), click on "Azure Active Directory" in the menu bar down the left, go to "App registrations" and click on "New registration". Name the app something suitable, eg "AzureRMR custom app".
+
+- If you want your users to be able to login with the authorization code flow, you must add a **public client/native redirect URI** of `http://localhost:1410`. This is appropriate if your users will be running R on their local PCs, with an Internet browser available.
+- If you want your users to be able to login with the device code flow, you must **enable the "Allow public client flows" setting** for your app. In the Portal, you can find this setting in the "Authentication" pane once the app registration is complete. This is appropriate if your users are running R in a remote session.
+- If the app is meant for non-interactive use, you must give the app a **client secret**, which is much the same as a password (and should similarly be kept secure). In the Portal, you can set this in the "Certificates and Secrets" pane for your app registration.
+
+Once the app registration has been created, note the app ID and, if applicable, the client secret. The latter can't be viewed after app creation, so make sure you note its value now.
+
+It's also possible to authenticate with a **client certificate (public key)**, but this is more complex and we won't go into it here. For more details, see the [Azure Active Directory documentation](https://docs.microsoft.com/en-au/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow) and the [AzureAuth intro vignette](https://cran.r-project.org/package=AzureAuth/vignettes/token.html).
+
+### Set the app role and scope
+
+You'll also need to set the role assignment and scope(s) for your app ID. The former determines the kinds of actions that AzureRMR can take; the latter determines which resources those action can be applied to.
+
+The main role assignments are 
+
+- **Owner**: can manage all aspects of resources, including role assignments
+- **Contributor**: can modify, create and delete resources, but cannot modify role assignments
+- **Reader**: can view resources but not make changes
+
+It's generally recommended to use the most restrictive role assignment that still lets you carry out your tasks.
+
+In the Portal, you can set the role assignment for your app ID by going to a specific subscription/resource group/resource and clicking on "Access Control (IAM)". Role assignments for subscriptions and resource groups will propagate to objects further down in the hierarchy. Any resources that don't have a role for your app will not be accessible.
+

vignettes/sp.Rmd

@@ -1,35 +0,0 @@
----
-title: "Creating a service principal"
-author: Hong Ooi
-output: rmarkdown::html_vignette
-vignette: >
-  %\VignetteIndexEntry{Creating a service principal}
-  %\VignetteEngine{knitr::rmarkdown}
-  %\VignetteEncoding{utf8}
----
-
-Authenticating with Azure Active Directory requires providing an app or service principal ID. If you don't provide one, AzureRMR will authenticate using the Azure CLI cross-platform app. This is sufficient for most purposes, however if necessary you can create your own service principal to authenticate with. For example, if security is a concern, this lets you restrict the scope of the resources that AzureRMR that manipulate.
-
-Creating a service principal is a one-time task, and the easiest method is to use the Azure cloud shell.
-
-- In the Azure Portal (https://portal.azure.com/), click on the Cloud Shell icon:
-
-![](images/cloudportal2.png)
-
-- If you haven't used the shell before, there will be a dialog box to choose whether to use bash or PowerShell. Choose bash.
-- In the shell, type `az ad sp create-for-rbac --name {app-name} --subscription "{your-subscription-name}" --years {N}`, substituting the desired name of your service principal (try to make it memorable to you, and unlikely to clash with other names), your subscription name, and the number of years you want the password to be valid.
-- Wait until the app creation is complete. You should see a screen like this.
-
-![](images/cloudshell.png)
-
-- Record your app ID and password.
-
-If you want to allow access at something other than subscription level, you can use the `--scopes` argument in place of `--subscription`. For example, to restrict AzureRMR to only the "AnalyticsRG" resource group: `az ad sp create-for-rbac --scopes /subscriptions/{your-subscription-ID}/resourceGroups/AnalyticsRG`.
-
-Once you have created your own service principal, you can supply the app ID and password as arguments to `create_azure_login`. You'll also have to supply your Azure Active Directory tenant, as AAD does not have access to your personal credentials.
-
-```r
-# authenticating with a custom service principal
-create_azure_login(tenant="myaadtenant", app="app_id", password="password")
-```
-