azr: Credential Chain for Seamless 'OAuth 2.0' Authentication to 'Azure Services'

Description

Implements a credential chain for 'Azure OAuth 2.0' authentication based on the package 'httr2”s 'OAuth' framework. Sequentially attempts authentication methods until one succeeds. During development allows interactive browser-based flows ('Device Code' and 'Auth Code' flows) and non-interactive flow ('Client Secret') in batch mode.

Author(s)

Maintainer: Pedro Baltazar pedrobtz@gmail.com

See Also

Useful links:

• https://pedrobtz.github.io/azr/

• https://github.com/pedrobtz/azr

• Report bugs at https://github.com/pedrobtz/azr/issues

Authorization code credential authentication

Description

Authenticates a user through the OAuth 2.0 authorization code flow. This flow opens a web browser for the user to sign in.

Details

The authorization code flow is the standard OAuth 2.0 flow for interactive authentication. It requires a web browser and is suitable for applications where the user can interact with a browser window.

The credential supports token caching to avoid repeated authentication. Tokens can be cached to disk or in memory. A redirect URI is required for the OAuth flow to complete.

Super classes

azr::Credential -> azr::InteractiveCredential -> AuthCodeCredential

Methods

Public methods

• AuthCodeCredential$new()

• AuthCodeCredential$get_token()

• AuthCodeCredential$req_auth()

• AuthCodeCredential$clone()

Method new()

Create a new authorization code credential

Usage

AuthCodeCredential$new(
  scope = NULL,
  tenant_id = NULL,
  client_id = NULL,
  use_cache = "disk",
  offline = TRUE,
  redirect_uri = default_redirect_uri()
)

Arguments

Returns

A new AuthCodeCredential object

Method get_token()

Get an access token using authorization code flow

Usage

AuthCodeCredential$get_token(reauth = FALSE)

Arguments

Returns

An httr2::oauth_token() object containing the access token

Method req_auth()

Add OAuth authorization code authentication to an httr2 request

Usage

AuthCodeCredential$req_auth(req)

Arguments

Returns

The request object with OAuth authorization code authentication configured

Method clone()

The objects of this class are cloneable with this method.

Usage

AuthCodeCredential$clone(deep = FALSE)

Arguments

Examples

# AuthCodeCredential requires an interactive session
## Not run: 
# Create credential with default settings
cred <- AuthCodeCredential$new(
  tenant_id = "your-tenant-id",
  client_id = "your-client-id",
  scope = "https://management.azure.com/.default"
)

# Get an access token (will open browser for authentication)
token <- cred$get_token()

# Force reauthentication
token <- cred$get_token(reauth = TRUE)

# Use with httr2 request
req <- httr2::request("https://management.azure.com/subscriptions")
req <- cred$req_auth(req)

## End(Not run)

Azure CLI credential authentication

Description

Authenticates using the Azure CLI (az) command-line tool. This credential requires the Azure CLI to be installed and the user to be logged in via ⁠az login⁠.

Details

The credential uses the ⁠az account get-access-token⁠ command to retrieve access tokens. It will use the currently active Azure CLI account and subscription unless a specific tenant is specified.

Super class

azr::Credential -> AzureCLICredential

Public fields

Methods

Public methods

• AzureCLICredential$new()

• AzureCLICredential$get_token()

• AzureCLICredential$req_auth()

• AzureCLICredential$clone()

Method new()

Create a new Azure CLI credential

Usage

AzureCLICredential$new(scope = NULL, tenant_id = NULL, process_timeout = NULL)

Arguments

Returns

A new AzureCLICredential object

Method get_token()

Get an access token from Azure CLI

Usage

AzureCLICredential$get_token(scope = NULL)

Arguments

Returns

An httr2::oauth_token() object containing the access token

Method req_auth()

Add authentication to an httr2 request

Usage

AzureCLICredential$req_auth(req, scope = NULL)

Arguments

Returns

The request object with authentication header added

Method clone()

The objects of this class are cloneable with this method.

Usage

AzureCLICredential$clone(deep = FALSE)

Arguments

Examples

# Create credential with default settings
cred <- AzureCLICredential$new()

# Create credential with specific scope and tenant
cred <- AzureCLICredential$new(
  scope = "https://management.azure.com/.default",
  tenant_id = "your-tenant-id"
)

# To get a token or authenticate a request it is required that
# 'az login' is successfully executed, otherwise it will return an error.
## Not run: 
# Get an access token
token <- cred$get_token()

# Use with httr2 request
req <- httr2::request("https://management.azure.com/subscriptions")
resp <- httr2::req_perform(cred$req_auth(req))

## End(Not run)

Client secret credential authentication

Description

Authenticates a service principal using a client ID and client secret. This credential is commonly used for application authentication in Azure.

Details

The credential uses the OAuth 2.0 client credentials flow to obtain access tokens. It requires a registered Azure AD application with a client secret. The client secret should be stored securely and not hard-coded in scripts.

Super class

azr::Credential -> ClientSecretCredential

Methods

Public methods

• ClientSecretCredential$validate()

• ClientSecretCredential$get_token()

• ClientSecretCredential$req_auth()

• ClientSecretCredential$clone()

Method validate()

Validate the credential configuration

Usage

ClientSecretCredential$validate()

Details

Checks that the client secret is provided and not NA. Calls the parent class validation method.

Method get_token()

Get an access token using client credentials flow

Usage

ClientSecretCredential$get_token()

Returns

An httr2::oauth_token() object containing the access token

Method req_auth()

Add OAuth client credentials authentication to an httr2 request

Usage

ClientSecretCredential$req_auth(req)

Arguments

Returns

The request object with OAuth client credentials authentication configured

Method clone()

The objects of this class are cloneable with this method.

Usage

ClientSecretCredential$clone(deep = FALSE)

Arguments

Examples

# Create credential with client secret
cred <- ClientSecretCredential$new(
  tenant_id = "your-tenant-id",
  client_id = "your-client-id",
  client_secret = "your-client-secret",
  scope = "https://management.azure.com/.default"
)

# To get a token or authenticate a request it requires
# valid 'client_id' and 'client_secret' credentials,
# otherwise it will return an error.
## Not run: 
# Get an access token
token <- cred$get_token()

# Use with httr2 request
req <- httr2::request("https://management.azure.com/subscriptions")
resp <- httr2::req_perform(cred$req_auth(req))

## End(Not run)

Device code credential authentication

Description

Authenticates a user through the device code flow. This flow is designed for devices that don't have a web browser or have input constraints.

Details

The device code flow displays a code that the user must enter on another device with a web browser to complete authentication. This is ideal for CLI applications, headless servers, or devices without a browser.

The credential supports token caching to avoid repeated authentication. Tokens can be cached to disk or in memory.

Super classes

azr::Credential -> azr::InteractiveCredential -> DeviceCodeCredential

Methods

Public methods

• DeviceCodeCredential$new()

• DeviceCodeCredential$get_token()

• DeviceCodeCredential$req_auth()

• DeviceCodeCredential$clone()

Method new()

Create a new device code credential

Usage

DeviceCodeCredential$new(
  scope = NULL,
  tenant_id = NULL,
  client_id = NULL,
  use_cache = "disk",
  offline = TRUE
)

Arguments

Returns

A new DeviceCodeCredential object

Method get_token()

Get an access token using device code flow

Usage

DeviceCodeCredential$get_token(reauth = FALSE)

Arguments

Returns

An httr2::oauth_token() object containing the access token

Method req_auth()

Add OAuth device code authentication to an httr2 request

Usage

DeviceCodeCredential$req_auth(req)

Arguments

Returns

The request object with OAuth device code authentication configured

Method clone()

The objects of this class are cloneable with this method.

Usage

DeviceCodeCredential$clone(deep = FALSE)

Arguments

Examples

# DeviceCodeCredential requires an interactive session
## Not run: 
# Create credential with default settings
cred <- DeviceCodeCredential$new()

# Get an access token (will prompt for 'device code' flow)
token <- cred$get_token()

# Force re-authentication
token <- cred$get_token(reauth = TRUE)

# Use with httr2 request
req <- httr2::request("https://management.azure.com/subscriptions")
req <- cred$req_auth(req)

## End(Not run)

Interactive credential base class

Description

Base class for interactive authentication credentials. This class should not be instantiated directly; use DeviceCodeCredential or AuthCodeCredential instead.

Super class

azr::Credential -> InteractiveCredential

Methods

Public methods

• InteractiveCredential$is_interactive()

• InteractiveCredential$clone()

Method is_interactive()

Check if the credential is interactive

Usage

InteractiveCredential$is_interactive()

Returns

Always returns TRUE for interactive credentials

Method clone()

The objects of this class are cloneable with this method.

Usage

InteractiveCredential$clone(deep = FALSE)

Arguments

Azure Authority Host URLs

Description

Login endpoint URLs for different Azure cloud environments.

Usage

azure_authority_hosts

Format

An object of class list of length 3.

Azure Default Client Configuration

Description

Default client ID and tenant ID used for Azure authentication when not explicitly provided. The client ID is Microsoft's public Azure CLI client ID.

Usage

azure_client

Format

An object of class list of length 2.

Common Azure OAuth Scopes

Description

Predefined OAuth scopes for common Azure services.

Usage

azure_scopes

Format

An object of class list of length 4.

Get default Azure client ID

Description

Retrieves the Azure client ID from the AZURE_CLIENT_ID environment variable, or falls back to the default Azure CLI client ID if not set.

Usage

default_azure_client_id()

Value

A character string with the client ID

Examples

default_azure_client_id()

Get default Azure client secret

Description

Retrieves the Azure client secret from the AZURE_CLIENT_SECRET environment variable, or returns NA_character_ if not set.

Usage

default_azure_client_secret()

Value

A character string with the client secret, or NA_character_ if not set

Examples

default_azure_client_secret()

Get default Azure authority host

Description

Retrieves the Azure authority host from the AZURE_AUTHORITY_HOST environment variable, or falls back to Azure Public Cloud if not set.

Usage

default_azure_host()

Value

A character string with the authority host URL

Examples

default_azure_host()

Create default Azure OAuth client

Description

Creates an httr2::oauth_client() configured for Azure authentication.

Usage

default_azure_oauth_client(
  client_id = default_azure_client_id(),
  client_secret = NULL,
  name = NULL
)

Arguments

Value

An httr2::oauth_client() object

Examples

client <- default_azure_oauth_client()
client <- default_azure_oauth_client(
  client_id = "my-client-id",
  client_secret = "my-secret"
)

Get default Azure OAuth scope

Description

Returns the default OAuth scope for a specified Azure resource.

Usage

default_azure_scope(resource = "azure_arm")

Arguments

Value

A character string with the OAuth scope URL

Examples

default_azure_scope()
default_azure_scope("azure_graph")

Get default Azure tenant ID

Description

Retrieves the Azure tenant ID from the AZURE_TENANT_ID environment variable, or falls back to the default value if not set.

Usage

default_azure_tenant_id()

Value

A character string with the tenant ID

Examples

default_azure_tenant_id()

Get default Azure OAuth URLs

Description

Constructs Azure OAuth 2.0 endpoint URLs for a given tenant and authority host.

Usage

default_azure_url(
  endpoint = NULL,
  oauth_host = default_azure_host(),
  tenant_id = default_azure_tenant_id()
)

Arguments

Value

If endpoint is specified, returns a character string with the URL. If endpoint is NULL, returns a named list of all endpoint URLs.

Examples

# Get all URLs
default_azure_url()

# Get specific endpoint
default_azure_url("token")

# Custom tenant
default_azure_url("authorize", tenant_id = "my-tenant-id")

Get default OAuth redirect URI

Description

Constructs a redirect URI for OAuth flows. If the provided URI doesn't have a port, assigns a random port using httpuv::randomPort().

Usage

default_redirect_uri(redirect_uri = httr2::oauth_redirect_uri())

Arguments

Value

A character string with the redirect URI

Examples

default_redirect_uri()

Azure Environment Variable Names

Description

Standard environment variable names used for Azure credential discovery.

Usage

environment_variables

Format

An object of class list of length 9.

Get Default Request Authorizer Function

Description

Creates a request authorizer function that retrieves authentication credentials and returns a callable request authorization method. This function handles the credential discovery process and returns the request authentication method from the discovered credential object.

Usage

get_request_authorizer(
  scope = NULL,
  tenant_id = NULL,
  client_id = NULL,
  client_secret = NULL,
  use_cache = "disk",
  offline = FALSE,
  .chain = default_credential_chain(),
  .verbose = FALSE
)

Arguments

Value

A function that authorizes HTTP requests with appropriate credentials when called.

See Also

get_token_provider(), get_token()

Examples

# In non-interactive sessions, this function will return an error if the
# environment is not setup with valid credentials. And in an interactive session
# the user will be prompted to attempt one of the interactive authentication flows.
## Not run: 
req_auth <- get_request_authorizer(
  scope = "https://graph.microsoft.com/.default"
)
req <- req_auth(httr2::request("https://graph.microsoft.com/v1.0/me"))

## End(Not run)

Get Authentication Token

Description

Retrieves an authentication token using the default token provider. This is a convenience function that combines credential discovery and token acquisition in a single step.

Usage

get_token(
  scope = NULL,
  tenant_id = NULL,
  client_id = NULL,
  client_secret = NULL,
  use_cache = "disk",
  offline = FALSE,
  .chain = default_credential_chain(),
  .verbose = FALSE
)

Arguments

Value

An httr2::oauth_token() object.

See Also

get_token_provider(), get_request_authorizer()

Examples

# In non-interactive sessions, this function will return an error if the
# environment is not setup with valid credentials. And in an interactive session
# the user will be prompted to attempt one of the interactive authentication flows.
## Not run: 
token <- get_token(
  scope = "https://graph.microsoft.com/.default",
  tenant_id = "my-tenant-id",
  client_id = "my-client-id",
  client_secret = "my-secret"
)

## End(Not run)

Get Default Token Provider Function

Description

Creates a token provider function that retrieves authentication credentials and returns a callable token getter. This function handles the credential discovery process and returns the token acquisition method from the discovered credential object.

Usage

get_token_provider(
  scope = NULL,
  tenant_id = NULL,
  client_id = NULL,
  client_secret = NULL,
  use_cache = "disk",
  offline = FALSE,
  .chain = default_credential_chain(),
  .verbose = FALSE
)

Arguments

Value

A function that retrieves and returns an authentication token when called.

See Also

get_request_authorizer(), get_token()

Examples

# In non-interactive sessions, this function will return an error if the
# environment is not set up with valid credentials. In an interactive session
# the user will be prompted to attempt one of the interactive authentication flows.
## Not run: 
token_provider <- get_token_provider(
  scope = "https://graph.microsoft.com/.default",
  tenant_id = "my-tenant-id",
  client_id = "my-client-id",
  client_secret = "my-secret"
)
token <- token_provider()

## End(Not run)