From 79a6102b81756fea5377a4882809f9a40fe189da Mon Sep 17 00:00:00 2001 From: hong-revo Date: Tue, 12 Feb 2019 21:44:46 +1100 Subject: [PATCH] doc oops --- README.md | 4 +- vignettes/token.Rmd | 8 +- vignettes/token.html | 171 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 177 insertions(+), 6 deletions(-) create mode 100644 vignettes/token.html diff --git a/README.md b/README.md index e1600b4..696cb60 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ get_azure_token("myresource", "mytenant", "app_id", auth_type="device_code") # obtain a token using client_credentials # supply credentials in password arg get_azure_token("myresource", "mytenant", "app_id", - password="mypassword", auth_type="client_credentials") + password="client_secret", auth_type="client_credentials") # can also supply a client certificate, as a string get_azure_token("myresource", "mytenant", "app_id", @@ -53,7 +53,7 @@ get_azure_token("myresource", "mytenant", "app_id", # obtain a token using resource_owner # supply credentials in username and password args get_azure_token("myresource", "mytenant", "app_id", - password="mypassword", auth_type="resource_owner") + username="myusername", password="mypassword", auth_type="resource_owner") ``` If you don't specify the method, `get_azure_token` makes a best guess based on the presence or absence of the other authentication arguments, and whether httpuv is installed. diff --git a/vignettes/token.Rmd b/vignettes/token.Rmd index 821aafa..be95369 100644 --- a/vignettes/token.Rmd +++ b/vignettes/token.Rmd @@ -68,7 +68,7 @@ get_azure_token("myresource", "mytenant", "app_id", auth_type="device_code") # obtain a token using client_credentials # supply credentials in password arg get_azure_token("myresource", "mytenant", "app_id", - password="mypassword", auth_type="client_credentials") + password="client_secret", auth_type="client_credentials") # can also supply a client certificate, as a string get_azure_token("myresource", "mytenant", "app_id", @@ -81,7 +81,7 @@ get_azure_token("myresource", "mytenant", "app_id", # obtain a token using resource_owner # supply credentials in username and password args get_azure_token("myresource", "mytenant", "app_id", - password="mypassword", auth_type="resource_owner") + username="myusername", password="mypassword", auth_type="resource_owner") ``` If you don't specify the method, `get_azure_token` makes a best guess based on the presence or absence of the other authentication arguments, and whether httpuv is installed. @@ -94,7 +94,7 @@ get_azure_token("myresource", "mytenant", "app_id") ## 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 `~/.config/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). +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 `~/.config/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). To list all cached tokens on disk, use `list_azure_tokens`. This returns a list of token objects, named according to their MD5 hashes. @@ -108,7 +108,7 @@ list_azure_tokens() # delete a token delete_azure_token("myresource", "mytenant", "app_id", - password="mypassword", auth_type="client_credentials") + password="client_credentials", auth_type="client_credentials") ``` ## More information diff --git a/vignettes/token.html b/vignettes/token.html new file mode 100644 index 0000000..94f262b --- /dev/null +++ b/vignettes/token.html @@ -0,0 +1,171 @@ + + + + + + + + + + + + + + + +Acquire an OAuth token + + + + + + + + + + + + + + + + + +

Acquire an OAuth token

+

Hong Ooi

+ + + +

This is a short introduction to authenticating with Azure Active Directory (AAD) with AzureAuth.

+
+

The get_azure_token function

+

The main function in AzureAuth is get_azure_token, which obtains an OAuth token from AAD:

+
library(AzureAuth)
+
+token <- get_azure_token(resource="myresource", tenant="mytenant", app="app_id",
+    password="mypassword", username="username", certificate="encoded_cert", version=1, ...)
+

The function has the following arguments:

+ +

Scopes in AAD v2.0 consist of a URL or a GUID, along with a path that designates the scope. If a scope doesn’t have a path, get_azure_token will append the /.default path with a warning. A special scope is offline_access, which requests a refresh token from AAD along with the access token: without this, you will have to reauthenticate if you want to refresh the token.

+
# request an AAD v1.0 token for Resource Manager
+token1 <- get_azure_token("https://management.azure.com/", "mytenant", "app_id")
+
+# same request to AAD v2.0, along with a refresh token
+token2 <- get_azure_token(c("https://management.azure.com/.default", "offline_access"),
+    "mytenant", "app_id", version=2)
+
+
+

Authentication methods

+

AzureAuth supports four distinct methods for authenticating with AAD: authorization_code, device_code, client_credentials and resource_owner.

+
    +
  1. Using the authorization_code method is a multi-step process. First, get_azure_token contacts the AAD authorization endpoint opens a login window in your browser, where you can enter your AAD credentials. In the background, it loads the httpuv package to listen on a local port. Once this is done, the AAD server passes your browser a (local) redirect URL that contains an authorization code. get_azure_token retrieves this authorization code and sends it to the AAD access endpoint, which returns the OAuth token. +

    +The httpuv package must be installed to use this method, as it requires a web server to listen on the (local) redirect URI. Since it opens a browser to load the AAD authorization page, your machine must also have an Internet browser installed that can be run from inside R. In particular, if you are using a Linux Data Science Virtual Machine in Azure, you may run into difficulties; use one of the other methods instead.
    2. +
+
# obtain a token using authorization_code
+# no user credentials needed
+get_azure_token("myresource", "mytenant", "app_id", auth_type="authorization_code")
+
    +
  1. The device_code method is similar in concept to authorization_code, but is meant for situations where you are unable to browse the Internet – for example if you don’t have a browser installed or your computer has input constraints. First, get_azure_token contacts the AAD devicecode endpoint, which responds with a login URL and an access code. You then visit the URL and enter the code, possibly using a different computer. Meanwhile, get_azure_token polls the AAD access endpoint for a token, which is provided once you have entered the code.
    2. +
+
# obtain a token using device_code
+# no user credentials needed
+get_azure_token("myresource", "mytenant", "app_id", auth_type="device_code")
+
    +
  1. The client_credentials method is much simpler than the above methods, requiring only one step. get_azure_token contacts the access endpoint, passing it the credentials. This can be either a client secret or a certificate, which you supply in the password or certificate argument respectively. Once the credentials are verified, the endpoint returns the token. This is the method typically used by service accounts.
    2. +
+
# obtain a token using client_credentials
+# supply credentials in password arg
+get_azure_token("myresource", "mytenant", "app_id",
+                password="client_secret", auth_type="client_credentials")
+
+# can also supply a client certificate, as a string
+get_azure_token("myresource", "mytenant", "app_id",
+                certificate="encoded_certificate", auth_type="client_credentials")
+
    +
  1. The resource_owner method also requires only one step. In this method, get_azure_token passes your (personal) username and password to the AAD access endpoint, which validates your credentials and returns the token.
    2. +
+
# obtain a token using resource_owner
+# supply credentials in username and password args
+get_azure_token("myresource", "mytenant", "app_id",
+                username="myusername", password="mypassword", auth_type="resource_owner")
+

If you don’t specify the method, get_azure_token makes a best guess based on the presence or absence of the other authentication arguments, and whether httpuv is installed.

+
# this will default to authorization_code if httpuv is installed, and device_code if not
+get_azure_token("myresource", "mytenant", "app_id")
+
+
+

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 ~/.config/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).

+

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 delete a cached token, use delete_azure_token. This takes the same inputs as get_azure_token, or you can specify the MD5 hash directly in the hash argument. To delete all cached tokens, use clean_token_directory.

+
# list all tokens
+list_azure_tokens()
+
+# <... list of token objects ...>
+
+# delete a token
+delete_azure_token("myresource", "mytenant", "app_id",
+                   password="client_credentials", auth_type="client_credentials")
+
+
+

More information

+

For the details on Azure Active Directory, consult the Microsoft documentation.

+
+ + + + + + + +