зеркало из https://github.com/Azure/AzureAuth.git
document refresh behaviour
This commit is contained in:
Hong Ooi
Родитель
a8273c303e
Коммит
7265550b08
2
NEWS.md
2
NEWS.md
|
|
@ -1,6 +1,6 @@
|
|||
# AzureAuth 1.2.1
|
||||
|
||||
* Pass the resource and scope as explicit parameters to the AAD endpoint when refreshing a token.
|
||||
* Pass the resource and scope as explicit parameters to the AAD endpoint when refreshing a token. Among other things, this allows using a refresh token from one resource to obtain an access token for another resource.
|
||||
|
||||
# AzureAuth 1.2.0
|
||||
|
||||
|
|
|
|||
29
R/token.R
29
R/token.R
|
|
@ -7,7 +7,7 @@
|
|||
#' @param app The client/app ID to use to authenticate with.
|
||||
#' @param password For most authentication flows, this is the password for the _app_ where needed, also known as the client secret. For the resource owner grant, this is your personal account password. See 'Details' below.
|
||||
#' @param username Your AAD username, if using the resource owner grant. See 'Details' below.
|
||||
#' @param certificate A file containing the certificate for authenticating with, an Azure Key Vault certificate object, or a call to the `cert_assertion` function to build a client assertion with a certificate. See 'Certificate authentication' below.
|
||||
#' @param certificate A file containing the certificate for authenticating with (including the private key), an Azure Key Vault certificate object, or a call to the `cert_assertion` function to build a client assertion with a certificate. See 'Certificate authentication' below.
|
||||
#' @param auth_type The authentication type. See 'Details' below.
|
||||
#' @param aad_host URL for your AAD host. For the public Azure cloud, this is `https://login.microsoftonline.com/`. Change this if you are using a government or private cloud. Can also be a full URL, eg `https://mydomain.b2clogin.com/mydomain/other/path/names/oauth2` (this is relevant mainly for Azure B2C logins).
|
||||
#' @param version The AAD version, either 1 or 2.
|
||||
|
|
@ -57,10 +57,10 @@
|
|||
#' @section OpenID Connect:
|
||||
#' `get_azure_token` can be used to obtain ID tokens along with regular OAuth access tokens, when using an interactive authentication flow (authorization_code or device_code). The behaviour depends on the AAD version:
|
||||
#' - AAD v1.0 will return an ID token as well as the access token by default; you don't have to do anything extra. However, AAD v1.0 will not _refresh_ the ID token when it expires; you must reauthenticate to get a new one. To ensure you don't pull the cached version of the credentials, specify `use_cache=FALSE` in the calls to `get_azure_token`.
|
||||
#' - Unlike AAD v1.0, AAD v2.0 does not return an ID token by default. To get a token, specify `openid` as a scope. On the other hand it _does_ refresh the ID token, so bypassing the cache is not needed. It's recommended to use AAD v2.0 if you only want an ID token; see the examples below.
|
||||
#' - Unlike AAD v1.0, AAD v2.0 does not return an ID token by default. To get a token, specify `openid` as a scope. On the other hand it _does_ refresh the ID token, so bypassing the cache is not needed. It's recommended to use AAD v2.0 if you only want an ID token.
|
||||
#'
|
||||
#' @section Caching:
|
||||
#' AzureAuth differs from httr in its handling of token caching in a number of ways. First, caching is based on all the inputs to `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 `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. Tokens are cached in a custom, user-specific directory, created with 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.
|
||||
#'
|
||||
|
|
@ -68,6 +68,13 @@
|
|||
#'
|
||||
#' To delete _all_ cached tokens, use `clean_token_directory`.
|
||||
#'
|
||||
#' @section Refreshing:
|
||||
#' A token object can be refreshed by calling its `refresh()` method. If the token's credentials contain a refresh token, this is used; otherwise a new access token is obtained by reauthenticating.
|
||||
#'
|
||||
#' Note that in AAD, a refresh token can be used to obtain an access token for any resource or scope that you have permissions for. Thus, for example, you could use a refresh token issued on a request for `https://management.azure.com` to obtain a new access token for `https://graph.microsoft.com` (assuming you've been granted permission).
|
||||
#'
|
||||
#' To obtain an access token for a new resource, change the object's `resource` (for an AAD v1.0 token) or `scope` field (for an AAD v2.0 token) before calling `refresh()`. If you _also_ want to retain the token for the old resource, you should call the `clone()` method first to create a copy. See the examples below.
|
||||
#'
|
||||
#' @section Value:
|
||||
#' For `get_azure_token`, an object inheriting from `AzureToken`. The specific class depends on the authentication flow: `AzureTokenAuthCode`, `AzureTokenDeviceCode`, `AzureTokenClientCreds`, `AzureTokenOnBehalfOf`, `AzureTokenResOwner`. For `get_managed_token`, a similar object of class `AzureTokenManaged`.
|
||||
#'
|
||||
|
|
@ -130,7 +137,7 @@
|
|||
#' "mytenant", "app_id", version=2)
|
||||
#'
|
||||
#' # requesting multiple scopes (Microsoft Graph) with AAD 2.0
|
||||
#' tok <- get_azure_token(c("https://graph.microsoft.com/User.Read.All",
|
||||
#' get_azure_token(c("https://graph.microsoft.com/User.Read.All",
|
||||
#' "https://graph.microsoft.com/User.ReadWrite.All",
|
||||
#' "https://graph.microsoft.com/Directory.ReadWrite.All",
|
||||
#' "offline_access"),
|
||||
|
|
@ -180,6 +187,20 @@
|
|||
#' # get a token from within a managed identity (VM, container or service)
|
||||
#' get_managed_token("https://management.azure.com/")
|
||||
#'
|
||||
#'
|
||||
#' # use a refresh token from one resource to get an access token for another resource
|
||||
#' tok <- get_azure_token("https://myresource", "mytenant", "app_id")
|
||||
#' tok2 <- tok$clone()
|
||||
#' tok2$resource <- "https://anotherresource"
|
||||
#' tok2$refresh()
|
||||
#'
|
||||
#' # same for AAD v2.0
|
||||
#' tok <- get_azure_token(c("https://myresource/.default", "offline_access"),
|
||||
#' "mytenant", "app_id", version=2)
|
||||
#' tok2 <- tok$clone()
|
||||
#' tok2$scope <- c("https://anotherresource/.default", "offline_access")
|
||||
#' tok2$refresh()
|
||||
#'
|
||||
#' }
|
||||
#' @export
|
||||
get_azure_token <- function(resource, tenant, app, password=NULL, username=NULL, certificate=NULL, auth_type=NULL,
|
||||
|
|
|
|||
|
|
@ -56,7 +56,7 @@ is_azure_v2_token(object)
|
|||
|
||||
\item{username}{Your AAD username, if using the resource owner grant. See 'Details' below.}
|
||||
|
||||
\item{certificate}{A file containing the certificate for authenticating with, an Azure Key Vault certificate object, or a call to the \code{cert_assertion} function to build a client assertion with a certificate. See 'Certificate authentication' below.}
|
||||
\item{certificate}{A file containing the certificate for authenticating with (including the private key), an Azure Key Vault certificate object, or a call to the \code{cert_assertion} function to build a client assertion with a certificate. See 'Certificate authentication' below.}
|
||||
|
||||
\item{auth_type}{The authentication type. See 'Details' below.}
|
||||
|
||||
|
|
@ -126,13 +126,13 @@ OAuth tokens can be authenticated via an SSL/TLS certificate, which is considere
|
|||
\code{get_azure_token} can be used to obtain ID tokens along with regular OAuth access tokens, when using an interactive authentication flow (authorization_code or device_code). The behaviour depends on the AAD version:
|
||||
\itemize{
|
||||
\item AAD v1.0 will return an ID token as well as the access token by default; you don't have to do anything extra. However, AAD v1.0 will not \emph{refresh} the ID token when it expires; you must reauthenticate to get a new one. To ensure you don't pull the cached version of the credentials, specify \code{use_cache=FALSE} in the calls to \code{get_azure_token}.
|
||||
\item Unlike AAD v1.0, AAD v2.0 does not return an ID token by default. To get a token, specify \code{openid} as a scope. On the other hand it \emph{does} refresh the ID token, so bypassing the cache is not needed. It's recommended to use AAD v2.0 if you only want an ID token; see the examples below.
|
||||
\item Unlike AAD v1.0, AAD v2.0 does not return an ID token by default. To get a token, specify \code{openid} as a scope. On the other hand it \emph{does} refresh the ID token, so bypassing the cache is not needed. It's recommended to use AAD v2.0 if you only want an ID token.
|
||||
}
|
||||
}
|
||||
|
||||
\section{Caching}{
|
||||
|
||||
AzureAuth 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}. On Linux, it will be in \code{~/.config/AzureR}, and on MacOS, it will be in \code{~/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 \code{get_azure_token} as listed above. Tokens are cached in a custom, user-specific directory, created with the rappdirs package. On recent Windows versions, this will usually be in the location \code{C:\\Users\\(username)\\AppData\\Local\\AzureR}. On Linux, it will be in \code{~/.config/AzureR}, and on MacOS, it will be in \code{~/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 \code{list_azure_tokens}. This returns a list of token objects, named according to their MD5 hashes.
|
||||
|
||||
|
|
@ -141,6 +141,15 @@ To delete a cached token, use \code{delete_azure_token}. This takes the same inp
|
|||
To delete \emph{all} cached tokens, use \code{clean_token_directory}.
|
||||
}
|
||||
|
||||
\section{Refreshing}{
|
||||
|
||||
A token object can be refreshed by calling its \code{refresh()} method. If the token's credentials contain a refresh token, this is used; otherwise a new access token is obtained by reauthenticating.
|
||||
|
||||
Note that in AAD, a refresh token can be used to obtain an access token for any resource or scope that you have permissions for. Thus, for example, you could use a refresh token issued on a request for \code{https://management.azure.com} to obtain a new access token for \code{https://graph.microsoft.com} (assuming you've been granted permission).
|
||||
|
||||
To obtain an access token for a new resource, change the object's \code{resource} (for an AAD v1.0 token) or \code{scope} field (for an AAD v2.0 token) before calling \code{refresh()}. If you \emph{also} want to retain the token for the old resource, you should call the \code{clone()} method first to create a copy. See the examples below.
|
||||
}
|
||||
|
||||
\section{Value}{
|
||||
|
||||
For \code{get_azure_token}, an object inheriting from \code{AzureToken}. The specific class depends on the authentication flow: \code{AzureTokenAuthCode}, \code{AzureTokenDeviceCode}, \code{AzureTokenClientCreds}, \code{AzureTokenOnBehalfOf}, \code{AzureTokenResOwner}. For \code{get_managed_token}, a similar object of class \code{AzureTokenManaged}.
|
||||
|
|
@ -197,7 +206,7 @@ token2 <- get_azure_token(c("https://management.azure.com/.default", "offline_ac
|
|||
"mytenant", "app_id", version=2)
|
||||
|
||||
# requesting multiple scopes (Microsoft Graph) with AAD 2.0
|
||||
tok <- get_azure_token(c("https://graph.microsoft.com/User.Read.All",
|
||||
get_azure_token(c("https://graph.microsoft.com/User.Read.All",
|
||||
"https://graph.microsoft.com/User.ReadWrite.All",
|
||||
"https://graph.microsoft.com/Directory.ReadWrite.All",
|
||||
"offline_access"),
|
||||
|
|
@ -247,6 +256,20 @@ extract_jwt("id")
|
|||
# get a token from within a managed identity (VM, container or service)
|
||||
get_managed_token("https://management.azure.com/")
|
||||
|
||||
|
||||
# use a refresh token from one resource to get an access token for another resource
|
||||
tok <- get_azure_token("https://myresource", "mytenant", "app_id")
|
||||
tok2 <- tok$clone()
|
||||
tok2$resource <- "https://anotherresource"
|
||||
tok2$refresh()
|
||||
|
||||
# same for AAD v2.0
|
||||
tok <- get_azure_token(c("https://myresource/.default", "offline_access"),
|
||||
"mytenant", "app_id", version=2)
|
||||
tok2 <- tok$clone()
|
||||
tok2$scope <- c("https://anotherresource/.default", "offline_access")
|
||||
tok2$refresh()
|
||||
|
||||
}
|
||||
}
|
||||
\seealso{
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче