зеркало из https://github.com/Azure/AzureRMR.git
document
This commit is contained in:
hong-revo
Родитель
288b07219d
Коммит
837fa0a18a
|
|
@ -1,7 +1,6 @@
|
|||
# Generated by roxygen2: do not edit by hand
|
||||
|
||||
export(AzureRMR_dir)
|
||||
export(AzureToken)
|
||||
export(az_resource)
|
||||
export(az_resource_group)
|
||||
export(az_rm)
|
||||
|
|
@ -30,6 +29,5 @@ export(is_url)
|
|||
export(list_azure_logins)
|
||||
export(list_azure_tokens)
|
||||
export(named_list)
|
||||
export(normalize_guid)
|
||||
export(normalize_tenant)
|
||||
import(AzureAuth)
|
||||
importFrom(utils,modifyList)
|
||||
|
|
|
|||
|
|
@ -1,27 +0,0 @@
|
|||
% Generated by roxygen2: do not edit by hand
|
||||
% Please edit documentation in R/AzureToken.R
|
||||
\docType{class}
|
||||
\name{AzureToken}
|
||||
\alias{AzureToken}
|
||||
\title{Azure OAuth authentication}
|
||||
\format{An R6 object of class \code{AzureToken}.}
|
||||
\usage{
|
||||
AzureToken
|
||||
}
|
||||
\description{
|
||||
Azure OAuth 2.0 token class, inheriting from the \link[httr:Token2.0]{Token2.0 class} in httr. Rather than calling the initialization method directly, tokens should be created via \code{\link[=get_azure_token]{get_azure_token()}}.
|
||||
}
|
||||
\section{Methods}{
|
||||
|
||||
\itemize{
|
||||
\item \code{refresh}: Refreshes the token. For expired Azure tokens using client credentials, refreshing really means requesting a new token.
|
||||
\item \code{validate}: Checks if the token is still valid. For Azure tokens using client credentials, this just checks if the current time is less than the token's expiry time.
|
||||
\item \code{hash}: Computes an MD5 hash on selected fields of the token. Used internally for identification purposes when caching.
|
||||
\item \code{cache}: Stores the token on disk for use in future sessions.
|
||||
}
|
||||
}
|
||||
|
||||
\seealso{
|
||||
\link{get_azure_token}, \link[httr:Token]{httr::Token}
|
||||
}
|
||||
\keyword{datasets}
|
||||
|
|
@ -1,150 +0,0 @@
|
|||
% Generated by roxygen2: do not edit by hand
|
||||
% Please edit documentation in R/AzureToken.R
|
||||
\name{get_azure_token}
|
||||
\alias{get_azure_token}
|
||||
\alias{delete_azure_token}
|
||||
\alias{clean_token_directory}
|
||||
\alias{list_azure_tokens}
|
||||
\title{Manage Azure Active Directory OAuth 2.0 tokens}
|
||||
\usage{
|
||||
get_azure_token(resource, tenant, app, password = NULL,
|
||||
username = NULL, auth_type = NULL,
|
||||
aad_host = "https://login.microsoftonline.com/")
|
||||
|
||||
delete_azure_token(resource, tenant, app, password = NULL,
|
||||
username = NULL, auth_type = NULL,
|
||||
aad_host = "https://login.microsoftonline.com/", hash = NULL,
|
||||
confirm = TRUE)
|
||||
|
||||
clean_token_directory(confirm = TRUE)
|
||||
|
||||
list_azure_tokens()
|
||||
}
|
||||
\arguments{
|
||||
\item{resource}{URL for your resource host. For Resource Manager in the public Azure cloud, this is \code{https://management.azure.com/}.}
|
||||
|
||||
\item{tenant}{Your tenant. This can be a name ("myaadtenant"), a fully qualified domain name ("myaadtenant.onmicrosoft.com" or "mycompanyname.com"), or a GUID.}
|
||||
|
||||
\item{app}{The client/app ID to use to authenticate with.}
|
||||
|
||||
\item{password}{The password, either for the app, or your username if supplied. See 'Details' below.}
|
||||
|
||||
\item{username}{Your AAD username, if using the resource owner grant. See 'Details' below.}
|
||||
|
||||
\item{auth_type}{The authentication type. See 'Details' below.}
|
||||
|
||||
\item{aad_host}{URL for your AAD host. For the public Azure cloud, this is \code{https://login.microsoftonline.com/}. Change this if you are using a government or private cloud.}
|
||||
|
||||
\item{hash}{The MD5 hash of this token, computed from the above inputs. Used by \code{delete_azure_token} to identify a cached token to delete.}
|
||||
|
||||
\item{confirm}{For \code{delete_azure_token}, whether to prompt for confirmation before deleting a token.}
|
||||
}
|
||||
\description{
|
||||
These functions extend the OAuth functionality in httr for use with Azure Active Directory (AAD).
|
||||
}
|
||||
\details{
|
||||
\code{get_azure_token} does much the same thing as \code{\link[httr:oauth2.0_token]{httr::oauth2.0_token()}}, but customised for Azure. It obtains an OAuth token, first by checking if a cached value exists on disk, and if not, acquiring it from the AAD server. \code{delete_azure_token} deletes a cached token, and \code{list_azure_tokens} lists currently cached tokens.
|
||||
|
||||
Note that tokens are only cached if you allowed AzureRMR to create a data directory at package startup.
|
||||
}
|
||||
\section{Authentication methods}{
|
||||
|
||||
The OAuth authentication type can be one of four possible values: "authorization_code", "client_credentials", "device_code", or "resource_owner". The first two are provided by the \link[httr:Token2.0]{httr::Token2.0} token class, while the last two are provided by the AzureToken class which extends httr::Token2.0. Here is a short description of these methods.
|
||||
\enumerate{
|
||||
\item Using the authorization_code method is a 3-step process. First, \code{get_azure_token} contacts the AAD authorization endpoint to obtain a temporary access code. It then contacts the AAD access endpoint, passing it the code. The access endpoint sends back a login URL which \code{get_azure_token} opens in your browser, where you can enter your credentials. Once this is completed, the endpoint returns the OAuth token via a HTTP redirect URI.
|
||||
\item 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, \code{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, \code{get_azure_token} polls the AAD access endpoint for a token, which is provided once you have successfully entered the code.
|
||||
\item The client_credentials method is much simpler than the above methods, requiring only one step. \code{get_azure_token} contacts the access endpoint, passing it the app secret (which you supplied in the \code{password} argument). Assuming the secret is valid, the endpoint then returns the OAuth token.
|
||||
\item The resource_owner method also requires only one step. In this method, \code{get_azure_token} passes your (personal) username and password to the AAD access endpoint, which validates your credentials and returns the token.
|
||||
}
|
||||
|
||||
If the authentication method is not specified, it is chosen based on the presence or absence of the \code{password} and \code{username} arguments:
|
||||
\itemize{
|
||||
\item Password and username present: resource_owner.
|
||||
\item Password and username absent: authorization_code if the httpuv package is installed, device_code otherwise
|
||||
\item Password present, username absent: client_credentials
|
||||
\item Password absent, username present: error
|
||||
}
|
||||
|
||||
The httpuv package must be installed to use the authorization_code method, as this requires a web server to listen on the (local) redirect URI. See \link[httr:oauth2.0_token]{httr::oauth2.0_token} for more information; note that Azure does not support the \code{use_oob} feature of the httr OAuth 2.0 token class.
|
||||
|
||||
Similarly, since the authorization_code method opens a browser to load the AAD authorization page, your machine must have an Internet browser installed that can be run from inside R. In particular, if you are using a Linux \href{https://azure.microsoft.com/en-us/services/virtual-machines/data-science-virtual-machines/}{Data Science Virtual Machine} in Azure, you may run into difficulties; use one of the other methods instead.
|
||||
}
|
||||
|
||||
\section{Caching}{
|
||||
|
||||
AzureRMR differs from httr in its handling of token caching in a number of ways. First, caching is based on all the inputs to \code{get_azure_token} as listed above. Second, it defines its own directory for cached tokens, using the rappdirs package. On recent Windows versions, this will usually be in the location \code{C:\\Users\\(username)\\AppData\\Local\\AzureR\\AzureRMR}. On Linux, it will be in \code{~/.config/AzureRMR}, and on MacOS, it will be in \code{~/Library/Application Support/AzureRMR}. 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 \code{list_azure_tokens}. This returns a list of token objects, named according to their MD5 hashes.
|
||||
|
||||
To delete a cached token, use \code{delete_azure_token}. This takes the same inputs as \code{get_azure_token}, or you can specify the MD5 hash directly in the \code{hash} argument.
|
||||
|
||||
To delete \emph{all} cached tokens, use \code{clean_token_directory}.
|
||||
}
|
||||
|
||||
\section{Value}{
|
||||
|
||||
For \code{get_azure_token}, an object of class \code{AzureToken} representing the AAD token. For \code{list_azure_tokens}, a list of such objects retrieved from disk.
|
||||
}
|
||||
|
||||
\examples{
|
||||
\dontrun{
|
||||
|
||||
# authenticate with Azure Resource Manager:
|
||||
# no user credentials are supplied, so this will use the authorization_code
|
||||
# method if httpuv is installed, and device_code if not
|
||||
arm_token <- get_azure_token(
|
||||
resource="https://management.azure.com/",
|
||||
tenant="myaadtenant.onmicrosoft.com",
|
||||
app="app_id")
|
||||
|
||||
# you can force a specific authentication method with the auth_type argument
|
||||
arm_token <- get_azure_token(
|
||||
resource="https://management.azure.com/",
|
||||
tenant="myaadtenant.onmicrosoft.com",
|
||||
app="app_id",
|
||||
auth_type="device_code")
|
||||
|
||||
# to use the client_credentials method, supply the app secret as the password
|
||||
arm_token <- get_azure_token(
|
||||
resource="https://management.azure.com/",
|
||||
tenant="myaadtenant.onmicrosoft.com",
|
||||
app="app_id",
|
||||
password="app_secret")
|
||||
|
||||
# authenticate with Azure storage
|
||||
storage_token <- get_azure_token(
|
||||
resource="https://storage.azure.com/",
|
||||
tenant="myaadtenant.onmicrosoft.com",
|
||||
app="app_id")
|
||||
|
||||
# authenticate to your resource with the resource_owner method: provide your username and password
|
||||
owner_token <- get_azure_token(
|
||||
resource="https://myresource/",
|
||||
tenant="myaadtenant",
|
||||
app="app_id",
|
||||
username="user",
|
||||
password="abcdefg")
|
||||
|
||||
# list saved tokens
|
||||
list_azure_tokens()
|
||||
|
||||
# delete a saved token from disk
|
||||
delete_azure_token(
|
||||
resource="https://myresource/",
|
||||
tenant="myaadtenant",
|
||||
app="app_id",
|
||||
username="user",
|
||||
password="abcdefg")
|
||||
|
||||
# delete a saved token by specifying its MD5 hash
|
||||
delete_azure_token(hash="7ea491716e5b10a77a673106f3f53bfd")
|
||||
|
||||
}
|
||||
}
|
||||
\seealso{
|
||||
\link{AzureToken}, \link[httr:oauth2.0_token]{httr::oauth2.0_token}, \link[httr:Token]{httr::Token},
|
||||
|
||||
\href{https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-protocols-oauth-code}{OAuth authentication for Azure Active Directory},
|
||||
\href{https://www.oauth.com/oauth2-servers/device-flow/token-request/}{Device code flow on OAuth.com},
|
||||
\href{https://tools.ietf.org/html/rfc6749}{OAuth 2.0 RFC} for the gory details on how OAuth works
|
||||
}
|
||||
63
man/guid.Rd
63
man/guid.Rd
|
|
@ -1,63 +0,0 @@
|
|||
% Generated by roxygen2: do not edit by hand
|
||||
% Please edit documentation in R/normalize.R
|
||||
\name{normalize_tenant}
|
||||
\alias{normalize_tenant}
|
||||
\alias{normalize_guid}
|
||||
\alias{is_guid}
|
||||
\title{Normalize GUID and tenant values}
|
||||
\usage{
|
||||
normalize_tenant(tenant)
|
||||
|
||||
normalize_guid(x)
|
||||
|
||||
is_guid(x)
|
||||
}
|
||||
\arguments{
|
||||
\item{tenant}{For \code{normalize_tenant}, a string containing an Azure Active Directory tenant. This can be a name ("myaadtenant"), a fully qualified domain name ("myaadtenant.onmicrosoft.com" or "mycompanyname.com"), or a valid GUID.}
|
||||
|
||||
\item{x}{For \code{is_guid}, a character string; for \code{normalize_guid}, a string containing a \emph{validly formatted} GUID.}
|
||||
}
|
||||
\value{
|
||||
For \code{is_guid}, whether the argument is a validly formatted GUID.
|
||||
|
||||
For \code{normalize_guid}, the GUID in canonical format. If the argument is not recognised as a GUID, it throws an error.
|
||||
|
||||
For \code{normalize_tenant}, the normalized ID or name of the tenant.
|
||||
}
|
||||
\description{
|
||||
These functions are used by \code{get_azure_token} to recognise and properly format tenant and app IDs.
|
||||
}
|
||||
\details{
|
||||
A tenant can be identified either by a GUID, or its name, or a fully-qualified domain name (FQDN). The rules for normalizing a tenant are:
|
||||
\enumerate{
|
||||
\item If \code{tenant} is recognised as a valid GUID, return its canonically formatted value
|
||||
\item Otherwise, if it is a FQDN, return it
|
||||
\item Otherwise, if it is not the string "common", append ".onmicrosoft.com" to it
|
||||
\item Otherwise, return the value of \code{tenant}
|
||||
}
|
||||
|
||||
See the link below for GUID formats recognised by these functions.
|
||||
}
|
||||
\examples{
|
||||
|
||||
is_guid("72f988bf-86f1-41af-91ab-2d7cd011db47") # TRUE
|
||||
is_guid("{72f988bf-86f1-41af-91ab-2d7cd011db47}") # TRUE
|
||||
is_guid("72f988bf-86f1-41af-91ab-2d7cd011db47}") # FALSE (unmatched brace)
|
||||
is_guid("microsoft") # FALSE
|
||||
|
||||
# all of these return the same value
|
||||
normalize_guid("72f988bf-86f1-41af-91ab-2d7cd011db47")
|
||||
normalize_guid("{72f988bf-86f1-41af-91ab-2d7cd011db47}")
|
||||
normalize_guid("(72f988bf-86f1-41af-91ab-2d7cd011db47)")
|
||||
normalize_guid("72f988bf86f141af91ab2d7cd011db47")
|
||||
|
||||
normalize_tenant("microsoft") # returns 'microsoft.onmicrosoft.com'
|
||||
normalize_tenant("microsoft.com") # returns 'microsoft.com'
|
||||
normalize_tenant("72f988bf-86f1-41af-91ab-2d7cd011db47") # returns the GUID
|
||||
|
||||
}
|
||||
\seealso{
|
||||
\link{get_azure_token}
|
||||
|
||||
\href{https://docs.microsoft.com/en-us/dotnet/api/system.guid.parse]}{Parsing rules for GUIDs in .NET}. \code{is_guid} and \code{normalize_guid} recognise the "N", "D", "B" and "P" formats.
|
||||
}
|
||||
|
|
@ -6,7 +6,6 @@
|
|||
\alias{is_resource_group}
|
||||
\alias{is_resource}
|
||||
\alias{is_template}
|
||||
\alias{is_azure_token}
|
||||
\title{Informational functions}
|
||||
\usage{
|
||||
is_azure_login(object)
|
||||
|
|
@ -18,8 +17,6 @@ is_resource_group(object)
|
|||
is_resource(object)
|
||||
|
||||
is_template(object)
|
||||
|
||||
is_azure_token(object)
|
||||
}
|
||||
\arguments{
|
||||
\item{object}{An R object.}
|
||||
|
|
|
|||
|
|
@ -0,0 +1,21 @@
|
|||
% Generated by roxygen2: do not edit by hand
|
||||
% Please edit documentation in R/reexport_AzureAuth.R
|
||||
\docType{import}
|
||||
\name{reexports}
|
||||
\alias{reexports}
|
||||
\alias{clean_token_directory}
|
||||
\alias{delete_azure_token}
|
||||
\alias{get_azure_token}
|
||||
\alias{is_azure_token}
|
||||
\alias{is_guid}
|
||||
\alias{list_azure_tokens}
|
||||
\title{Objects exported from other packages}
|
||||
\keyword{internal}
|
||||
\description{
|
||||
These objects are imported from other packages. Follow the links
|
||||
below to see their documentation.
|
||||
|
||||
\describe{
|
||||
\item{AzureAuth}{\code{\link[AzureAuth]{clean_token_directory}}, \code{\link[AzureAuth]{delete_azure_token}}, \code{\link[AzureAuth]{get_azure_token}}, \code{\link[AzureAuth]{is_azure_token}}, \code{\link[AzureAuth]{is_guid}}, \code{\link[AzureAuth]{list_azure_tokens}}}
|
||||
}}
|
||||
|
||||
Загрузка…
Ссылка в новой задаче