Package 'azr'

Description

An R6 class that provides a base HTTP client for interacting with Azure APIs. This client handles authentication, request building, retry logic, logging, and error handling for Azure API requests.

Details

The api_client class is designed to be a base class for Azure service-specific clients. It provides:

• Automatic authentication using Azure credentials

• Configurable retry logic with exponential backoff

• Request and response logging

• JSON, XML, and HTML content type handling

• Standardized error handling

Public fields

Methods

Public methods

• api_client$new()

• api_client$.fetch()

• api_client$.resp_content()

• api_client$.build_request()

• api_client$.send_request()

• api_client$.resp_body_content()

• api_client$.get_token()

• api_client$clone()

Method new()

Create a new API client instance

Usage

api_client$new(
  host_url,
  provider = NULL,
  credentials = NULL,
  timeout = 60L,
  connecttimeout = 30L,
  max_tries = 5L,
  response_handler = NULL,
  verbose = opts$get("api_verbose")
)

Arguments

Returns

A new api_client object

Method .fetch()

Make an HTTP request to the API

Usage

api_client$.fetch(
  path,
  ...,
  query = NULL,
  body = NULL,
  headers = NULL,
  method = "get",
  verbosity = 0L,
  content = c("body", "headers", "response", "request"),
  content_type = NULL
)

Arguments

Returns

Depends on the content parameter:

• "body": Parsed response body (list, data.frame, or character)

• "headers": List of response headers

• "response": Full httr2::response() object

• "request": httr2::request() object

Method .resp_content()

Extract content from a response object

Usage

api_client$.resp_content(resp, content, content_type = NULL)

Arguments

Returns

Depends on the content parameter:

• "body": Parsed response body (list, data.frame, or character)

• "headers": List of response headers

• "response": Full httr2::response() object

Method .build_request()

Build an HTTP request object

Usage

api_client$.build_request(
  path,
  ...,
  query = NULL,
  body = NULL,
  headers = NULL,
  method = "get"
)

Arguments

Returns

An httr2::request() object ready for execution

Method .send_request()

Perform an HTTP request and log the results

Usage

api_client$.send_request(req, verbosity)

Arguments

Returns

An httr2::response() object containing the API response

Method .resp_body_content()

Extract and parse response content

Usage

api_client$.resp_body_content(resp, content_type = NULL)

Arguments

Returns

Parsed response body. Format depends on content type:

• JSON: List or data.frame

• XML: xml2 document

• HTML: xml2 document

• Other: Character string

Method .get_token()

Get authentication token from the credential provider

Usage

api_client$.get_token()

Returns

An httr2::oauth_token() object if a provider is available, otherwise returns NULL with a warning.

Method clone()

The objects of this class are cloneable with this method.

Usage

api_client$clone(deep = FALSE)

Arguments

Examples

## Not run: 
# Create a client with default credentials
client <- api_client$new(
  host_url = "https://management.azure.com"
)

# Create a client with a credential provider
cred_provider <- get_credential_provider(
  scope = "https://management.azure.com/.default"
)
client <- api_client$new(
  host_url = "https://management.azure.com",
  provider = cred_provider
)

# Create a client with custom credentials function
client <- api_client$new(
  host_url = "https://management.azure.com",
  credentials = my_credential_function,
  timeout = 120,
  max_tries = 3
)

# Create a client with custom response handler
custom_handler <- function(content) {
  # Custom processing logic - e.g., keep data frames as-is
  content
}
client <- api_client$new(
  host_url = "https://management.azure.com",
  response_handler = custom_handler
)

# Make a GET request
response <- client$.fetch(
  path = "/subscriptions/{subscription_id}/resourceGroups",
  subscription_id = "my-subscription-id",
  query = list(`api-version` = "2021-04-01"),
  method = "get"
)

## End(Not run)

Description

An R6 class that extends api_client to provide a Kusto Query Language (KQL) query() method against the public Azure Log Analytics REST API, bound to a specific Azure subscription and resource group at construction.

Details

The client is bound to subscription_id and resource_id (the resource group name) at construction. The ⁠$query()⁠ method issues a POST to ⁠https://{endpoint}/{api_version}/subscriptions/{subscription_id}/resourceGroups/{resource_id}/query⁠ with a JSON body (⁠{"query": ..., "timespan": ..., "workspaces": [...]}⁠).

Pass scope = "hierarchy" (or any other supported query-string parameter) via ... on ⁠$query()⁠ to traverse the resource hierarchy.

Super class

azr::api_client -> api_log_analytics_client

Public fields

Methods

Public methods

• api_log_analytics_client$new()

• api_log_analytics_client$query()

• api_log_analytics_client$clone()

Method new()

Create a new Azure Log Analytics API client instance bound to a specific subscription and resource group.

Usage

api_log_analytics_client$new(
  subscription_id,
  resource_id,
  endpoint = default_log_analytics_endpoint(),
  api_version = "v1",
  scope = default_azure_scope("azure_log_analytics"),
  provider = NULL,
  chain = NULL,
  tenant_id = NULL,
  ...
)

Arguments

Returns

A new api_log_analytics_client object

Method query()

Issue a KQL query against the bound subscription and resource group.

Usage

api_log_analytics_client$query(
  query,
  date_from = Sys.Date() - 3,
  date_to = Sys.Date() + 1,
  timespan = NULL,
  max_rows = 500001L,
  options = list(truncationMaxSize = 67108864L),
  workspace_filters = list(regions = list()),
  ...,
  raw = FALSE,
  coerce_types = TRUE
)

Arguments

Returns

Either a single data.frame, a named list of data.frames, or the raw parsed response (when raw = TRUE).

Method clone()

The objects of this class are cloneable with this method.

Usage

api_log_analytics_client$clone(deep = FALSE)

Arguments

Examples

## Not run: 
la <- api_log_analytics_client$new(
  subscription_id = "00000000-0000-0000-0000-000000000000",
  resource_id = "my-resource-group"
)

la$query(
  query = "AzureDiagnostics | take 10",
  timespan = "PT12H",
  scope = "hierarchy"
)

## End(Not run)

Description

An R6 class that wraps an api_client and adds an additional path segment (like "beta" or "v1.0") to all requests. This is useful for APIs that version their endpoints or have different API surfaces under different paths.

Details

The api_resource class creates a modified base request by appending an endpoint path to the client's base request. All subsequent API calls through this resource will automatically include this path prefix.

Public fields

Methods

Public methods

• api_resource$new()

• api_resource$clone()

Method new()

Create a new API resource instance

Usage

api_resource$new(client, endpoint)

Arguments

Returns

A new api_resource object

Method clone()

The objects of this class are cloneable with this method.

Usage

api_resource$clone(deep = FALSE)

Arguments

Examples

## Not run: 
# Create a client
client <- api_client$new(
  host_url = "https://graph.microsoft.com"
)

# Create a resource with v1.0 API endpoint
resource_v1 <- api_resource$new(
  client = client,
  endpoint = "v1.0"
)

# Create a resource with beta API endpoint
resource_beta <- api_resource$new(
  client = client,
  endpoint = "beta"
)

# Make requests - the endpoint is automatically prepended
response <- resource_v1$.fetch(
  path = "/me",
  method = "get"
)

## End(Not run)

Description

Base R6 class for creating API service wrappers. This class provides a foundation for building service-specific API clients with authentication, endpoint management, and configuration.

Public fields

Methods

Public methods

• api_service$new()

Method new()

Create a new API service instance

Usage

api_service$new(
  client = NULL,
  chain = NULL,
  endpoints = list(),
  config = list()
)

Arguments

Returns

A new api_service object

Description

An R6 class that extends api_client to provide specialized methods for Azure Data Lake Storage Gen2 (ADLS Gen2) REST API operations.

Details

The base URL is constructed as: ⁠https://{storageaccount}.{endpoint_suffix}⁠

Super class

azr::api_client -> api_storage_client

Public fields

Methods

Public methods

• api_storage_client$new()

• api_storage_client$download_file()

• api_storage_client$get_access_control()

• api_storage_client$list_files()

• api_storage_client$clone()

Method new()

Create a new Azure Storage API client instance

Usage

api_storage_client$new(
  storageaccount,
  filesystem,
  scope = default_azure_scope("azure_storage"),
  endpoint_suffix = default_storage_endpoint(),
  provider = NULL,
  chain = NULL,
  tenant_id = NULL,
  client_id = default_azure_cli_client_id(),
  ...
)

Arguments

Returns

A new api_storage_client object

Method download_file()

Download a file from the filesystem

Usage

api_storage_client$download_file(path, dest = NULL)

Arguments

Returns

The local path the file was written to (invisibly).

Method get_access_control()

Get the access control list (ACL) for a file or directory

Usage

api_storage_client$get_access_control(dataset, upn = FALSE)

Arguments

Returns

A data.frame with columns group_id and permission, one row per named group entry in the x-ms-acl response header.

Method list_files()

List files and directories in a path

Usage

api_storage_client$list_files(path = "", recursive = FALSE, ...)

Arguments

Returns

A data.frame (or data.table if available) with one row per file or directory. Columns include name, contentLength, lastModified, etc. All pages are fetched transparently; the result is the complete listing.

Method clone()

The objects of this class are cloneable with this method.

Usage

api_storage_client$clone(deep = FALSE)

Arguments

Examples

## Not run: 
# Create a storage client
storage <- api_storage_client$new(
  storageaccount = "mystorageaccount",
  filesystem = "mycontainer"
)

# List files in the root directory
files <- storage$list_files()

# List files in a specific path
files <- storage$list_files(path = "data/folder1")

# List files recursively
files <- storage$list_files(path = "data", recursive = TRUE)

## End(Not run)

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

Public fields

Methods

Public methods

• AuthCodeCredential$new()

• AuthCodeCredential$clone()

Method new()

Create a new authorization code credential

Usage

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

Arguments

Returns

A new AuthCodeCredential object

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)

Description

Retrieves information about the currently active Azure CLI account and subscription. This function runs ⁠az account show⁠ and parses the JSON output into an R list.

Usage

az_cli_account_show(timeout = 10L)

Arguments

Details

The function returns details about the current Azure subscription including:

• Subscription ID and name

• Tenant ID

• Account state (e.g., "Enabled")

• User information

• Cloud environment details

Value

A list containing the account information from Azure CLI

Description

Reads the MSAL token cache file (msal_token_cache.json) from the Azure configuration directory and returns a matching access token as an httr2::oauth_token() object.

Usage

az_cli_get_cached_token(
  scope = NULL,
  tenant_id = NULL,
  client_id = NULL,
  config_dir = default_azure_config_dir()
)

Arguments

Details

The MSAL token cache is a JSON file maintained by the Azure CLI that stores access tokens and refresh tokens. This function reads cached access tokens directly from the file without invoking the Azure CLI, which can be useful in environments where the CLI is slow or unavailable but tokens have been previously cached.

When multiple tokens are found, the function selects the token that expires latest. If scope is provided, only tokens matching that scope/resource are returned.

Value

An httr2::oauth_token() object containing:

• access_token: The OAuth2 access token string

• token_type: The type of token (typically "Bearer")

• .expires_at: POSIXct timestamp when the token expires

Description

Retrieves an access token from Azure CLI using the ⁠az account get-access-token⁠ command. This is a lower-level function that directly interacts with the Azure CLI to obtain OAuth2 tokens.

Usage

az_cli_get_token(scope, tenant_id = NULL, timeout = 10L)

Arguments

Details

This function executes the Azure CLI command and parses the JSON response to create an httr2 OAuth token object. The token includes the access token, token type, and expiration time.

Value

An httr2::oauth_token() object containing:

• access_token: The OAuth2 access token string

• token_type: The type of token (typically "Bearer")

• .expires_at: POSIXct timestamp when the token expires

Description

Checks whether the user is currently logged in to Azure CLI by attempting to retrieve account information.

Usage

az_cli_is_login(timeout = 10L)

Arguments

Value

A logical value: TRUE if the user is logged in, FALSE otherwise

Description

Performs an interactive Azure CLI login using device code flow. Automatically captures the device code, copies it to the clipboard, and opens the browser for authentication.

Usage

az_cli_login(tenant_id = NULL, use_bridge = FALSE, verbose = FALSE)

Arguments

Details

This function runs ⁠az login --use-device-code⁠, monitors the output to extract the device code, copies it to the clipboard, and opens the authentication URL in the default browser.

Value

Invisibly returns the exit status (0 for success, non-zero for failure)

Description

Logs out from Azure CLI by removing all stored credentials and account information. This function runs ⁠az logout⁠.

Usage

az_cli_logout()

Details

After logging out, you will need to run az_cli_login() again to authenticate and use Azure CLI credentials.

Value

Invisibly returns NULL

Description

An S7 class holding an ordered collection of azr_dataset objects with unique names.

A catalog can be indexed by dataset name with [[, and supports names() and length().

Usage

azr_catalog(datasets = list())

Arguments

Value

An azr_catalog S7 object.

Examples

ds <- azr_dataset(
  name = "orders",
  scheme = "abfss",
  container = "raw",
  storage = list(prod = "stprod001"),
  path = "sales/orders",
  format = "delta"
)
catalog <- azr_catalog(datasets = list(ds))

catalog[["orders"]]
names(catalog)
length(catalog)

Description

Reads a JSON file describing a collection of datasets and returns an azr_catalog.

The expected JSON shape:

{
  "datasets": [
    {
      "name": "sales_orders",
      "scheme": "abfss",
      "container": "raw",
      "storage": { "prod": "stprod001", "preprod": "stpreprod001" },
      "path": "sales/orders",
      "format": "delta"
    }
  ]
}

Usage

azr_catalog_read(json_file)

Arguments

Value

An azr_catalog object.

See Also

azr_catalog_write()

Description

Writes an azr_catalog to a JSON file in the shape expected by azr_catalog_read().

Usage

azr_catalog_write(catalog, json_file)

Arguments

Value

json_file, invisibly.

See Also

azr_catalog_read()

Description

An S7 class representing an Azure Storage dataset bound to one or more storage accounts keyed by environment tier (e.g. "prod", "preprod").

Usage

azr_dataset(
  name = character(0),
  scheme = character(0),
  container = character(0),
  storage = list(),
  path = character(0),
  format = character(0),
  endpoint_suffix = "core.windows.net"
)

Arguments

Details

Only the storage account varies by tier: container, path, endpoint_suffix, and scheme are shared across all tiers in storage. If an environment also needs a different container, path, or sovereign cloud, model it as a separate azr_dataset.

path must be non-empty, so a dataset cannot point at a container root.

Value

An azr_dataset S7 object.

Description

Parses an Azure Storage URI using parse_storage_path() and constructs an azr_dataset. The parsed storage account is bound to tier in storage.

Usage

azr_dataset_from_uri(
  uri,
  name = NULL,
  format = NULL,
  tier = opts$get("dataset_tier"),
  storage = NULL
)

Arguments

Value

An azr_dataset object.

Description

An S7 class representing the resolved information required by an external reader to load an Azure Storage dataset. Use as.list() to convert it to a plain R list.

Usage

azr_dataset_manifest(
  name = character(0),
  uri = character(0),
  format = character(0)
)

Arguments

Value

An azr_dataset_manifest S7 object.

Description

Build a URI for an azr_dataset or look one up in an azr_catalog

Usage

azr_dataset_uri(x, ...)

Arguments

Value

For an azr_dataset, or an azr_catalog with name supplied, a character scalar URI. For an azr_catalog without name, a named character vector of URIs keyed by dataset name.

Examples

ds <- azr_dataset(
  name = "orders",
  scheme = "abfss",
  container = "raw",
  storage = list(prod = "stprod001"),
  path = "sales/orders",
  format = "delta"
)
azr_dataset_uri(ds, tier = "prod")

catalog <- azr_catalog(datasets = list(ds))
azr_dataset_uri(catalog, tier = "prod", name = "orders")
azr_dataset_uri(catalog, tier = "prod")

Description

Creates a configured client for the Microsoft Graph API with authentication and versioned endpoints (v1.0 and beta). This function returns an api_service object that provides access to Microsoft Graph resources through versioned endpoints.

Usage

azr_graph_client(
  scopes = ".default",
  endpoint = default_graph_endpoint(),
  ...,
  chain = NULL
)

Arguments

Details

The function creates a Microsoft Graph service using these components:

• api_client: A general-purpose API client configured with the Graph API host URL (⁠https://graph.microsoft.com⁠) and authentication provider.

• api_graph_resource: A specialized resource class that extends api_resource with Microsoft Graph-specific methods. Currently implements:

  • me(select = NULL): Fetch the current user's profile. The select parameter accepts a character vector of properties to return (e.g., c("displayName", "mail")).

• api_service: A service container that combines the client and resources with versioned endpoints (v1.0 and beta). The service is locked using lockEnvironment() to prevent modification after creation.

Value

An api_service object configured for Microsoft Graph API with v1.0 and beta endpoints. The object is locked using lockEnvironment() to prevent modification after creation. Access endpoints via ⁠$v1.0⁠ or ⁠$beta⁠.

Examples

## Not run: 
# Create a Graph API client with default credentials
graph <- azr_graph_client()

# Fetch current user profile from v1.0 endpoint
me <- graph$v1.0$me()

# Fetch specific properties using OData $select
me <- graph$v1.0$me(select = c("displayName", "mail", "userPrincipalName"))

# Use beta endpoint for preview features
me_beta <- graph$beta$me(select = c("displayName", "mail"))

# Create with a custom credential chain
custom_chain <- credential_chain(
  AzureCLICredential$new(scope = "https://graph.microsoft.com/.default")
)
graph <- azr_graph_client(chain = custom_chain)

# Use specific scopes instead of .default
graph <- azr_graph_client(scopes = "User.Read Mail.Read")

## End(Not run)

Description

A convenience wrapper around api_log_analytics_client that creates a configured client for the Azure Log Analytics query REST API, bound to a specific subscription and resource group.

Usage

azr_logs_client(
  subscription_id,
  resource_id,
  endpoint = default_log_analytics_endpoint(),
  api_version = "v1",
  scope = default_azure_scope("azure_log_analytics"),
  provider = NULL,
  chain = default_credential_chain(),
  tenant_id = default_azure_tenant_id(),
  ...
)

Arguments

Value

An api_log_analytics_client object.

Examples

## Not run: 
la <- azr_logs_client(
  subscription_id = "00000000-0000-0000-0000-000000000000",
  resource_id = "my-resource-group"
)

la$query(
  query = "AzureDiagnostics | take 10",
  timespan = "PT12H",
  scope = "hierarchy"
)

## End(Not run)

Description

Prints every azr option and invisibly returns a data.frame of the same information. The resolution order is: a value set for the session -> ⁠options(azr.*)⁠ -> the option's environment variable -> a built-in default.

Usage

azr_options(mask = TRUE)

Arguments

Value

Invisibly, a data.frame with columns option, value, source, env_var, env_value, and default.

Examples

azr_options()

# Set for the session
options(azr.chain_verbose = TRUE)

# Or via environment variable (before starting R)
# AZR_CHAIN_VERBOSE=true

Description

Like azr_dataset_uri(), but each entry also carries the dataset's format, which together are what a reader (e.g. sparklyr::spark_read_source()) needs to load a dataset.

Usage

azr_resolve_dataset(x, ...)

Arguments

Value

For an azr_dataset, or an azr_catalog with name supplied, an azr_dataset_manifest. For an azr_catalog without name, a named list of azr_dataset_manifest objects, keyed by dataset name.

Examples

ds <- azr_dataset(
  name = "orders",
  scheme = "abfss",
  container = "raw",
  storage = list(prod = "stprod001"),
  path = "sales/orders",
  format = "delta"
)
azr_resolve_dataset(ds, tier = "prod")

catalog <- azr_catalog(datasets = list(ds))
azr_resolve_dataset(catalog, tier = "prod")

Description

A convenience wrapper around api_storage_client that creates a configured client for Azure Data Lake Storage Gen2 (ADLS Gen2) REST API operations.

Usage

azr_storage_client(
  storageaccount,
  filesystem,
  endpoint_suffix = default_storage_endpoint(),
  scope = default_azure_scope("azure_storage"),
  provider = NULL,
  chain = default_credential_chain(),
  tenant_id = default_azure_tenant_id(),
  ...
)

Arguments

Value

An api_storage_client object.

Examples

## Not run: 
# Create a storage client with default credentials
storage <- azr_storage_client(
  storageaccount = "mystorageaccount",
  filesystem = "mycontainer"
)

# Create a storage client with a specific tenant
storage <- azr_storage_client(
  storageaccount = "mystorageaccount",
  filesystem = "mycontainer",
  tenant_id = "00000000-0000-0000-0000-000000000000"
)

## End(Not run)

Description

Builds the named list of Hadoop ⁠fs.azure.*⁠ configuration keys required to authenticate Apache Spark (or any ABFS-compatible runtime) against Azure Data Lake Storage Gen2. With the default prefix = "spark.hadoop" the returned list is ready to pass to SparkSession.builder.config(), a Databricks cluster's Spark config, or spark-defaults.conf — Spark forwards ⁠spark.hadoop.*⁠ keys to Hadoop at FileSystem-init time. Pass prefix = NULL to get the raw ⁠fs.azure.*⁠ form, suitable for core-site.xml or a ⁠sparkContext.hadoopConfiguration().set(...)⁠ call.

Five authentication types are supported:

"client_secret"

Service principal with client secret (ClientCredsTokenProvider).

"refresh_token"

Delegated user identity via a refresh token (RefreshTokenBasedTokenProvider).

"workload_identity"

Kubernetes workload identity via a projected service-account token file (WorkloadIdentityTokenProvider). Requires Hadoop 3.4.1+ / 3.5.0+ (HADOOP-18610). Stock Apache Spark 3.5 ships with Hadoop 3.3.4, so this requires Spark 4.x or a runtime that bundles a newer Hadoop (Databricks 14.3+ LTS, Synapse 3.4+).

"managed_identity"

Azure managed identity via IMDS (MsiTokenProvider). For Azure VMs, App Service, Functions, Container Instances, and AKS pods without workload identity. Pass client_id to select a user-assigned identity.

"shared_key"

Storage account key (SharedKey auth type). Requires storage_account and account_key; cannot be configured globally.

Sovereign clouds (Azure US Government, Azure China) are supported by passing the matching authority_host (e.g. "login.microsoftonline.us"). The storage endpoint suffix used to scope keys to a specific account is derived from the authority host. Alternatively, pass a fully qualified storage_account like "myacct.dfs.core.usgovcloudapi.net" to override the derivation entirely.

Usage

azure_spark_storage_conf(
  auth_type = c("refresh_token", "client_secret", "workload_identity",
    "managed_identity", "shared_key"),
  storage_account = NULL,
  tenant_id = default_azure_tenant_id(),
  client_id = default_azure_client_id(),
  client_secret = default_azure_client_secret(),
  refresh_token = default_refresh_token(),
  account_key = NULL,
  token_file = default_federated_token_file(),
  authority_host = default_azure_host(),
  prefix = "spark.hadoop"
)

Arguments

Value

A named list of class azure_spark_config. With the default prefix, keys look like ⁠spark.hadoop.fs.azure.account.*⁠; with prefix = NULL, keys look like ⁠fs.azure.account.*⁠. The print method redacts sensitive values (account key, client secret, refresh token).

Examples

# Global client-secret config (applies to all storage accounts)
azure_spark_storage_conf(
  auth_type = "client_secret",
  tenant_id = "my-tenant",
  client_id = "my-client",
  client_secret = "my-secret"
)

# Scoped to a specific storage account
azure_spark_storage_conf(
  auth_type = "client_secret",
  storage_account = "mystorageaccount",
  tenant_id = "my-tenant",
  client_id = "my-client",
  client_secret = "my-secret"
)

# Azure US Government sovereign cloud
azure_spark_storage_conf(
  auth_type = "client_secret",
  storage_account = "mystorageaccount",
  tenant_id = "my-tenant",
  client_id = "my-client",
  client_secret = "my-secret",
  authority_host = "login.microsoftonline.us"
)

## Not run: 
# Workload identity on AKS (reads env vars automatically)
azure_spark_storage_conf(auth_type = "workload_identity")

# Managed identity on an Azure VM (system-assigned)
azure_spark_storage_conf(auth_type = "managed_identity")

## End(Not run)

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$account_show()

• AzureCLICredential$login()

• AzureCLICredential$is_interactive()

• AzureCLICredential$logout()

• AzureCLICredential$clone()

Method new()

Create a new Azure CLI credential

Usage

AzureCLICredential$new(
  scope = NULL,
  tenant_id = NULL,
  process_timeout = NULL,
  auto_login = opts$get("cli_auto_login"),
  use_bridge = TRUE,
  interactive = 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 account_show()

Show the currently active Azure CLI account information

Usage

AzureCLICredential$account_show(timeout = NULL)

Arguments

Returns

A list containing the account information from Azure CLI

Method login()

Perform Azure CLI login using device code flow

Usage

AzureCLICredential$login()

Returns

Invisibly returns the exit status (0 for success, non-zero for failure)

Method is_interactive()

Check if the credential requires user interaction

Usage

AzureCLICredential$is_interactive()

Returns

Logical indicating whether this credential is interactive

Method logout()

Log out from Azure CLI

Usage

AzureCLICredential$logout()

Returns

Invisibly returns NULL

Method clone()

The objects of this class are cloneable with this method.

Usage

AzureCLICredential$clone(deep = FALSE)

Arguments

Examples

# 'az login' must have been executed successfully for these examples to work.
## Not run: 
# 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"
)

# 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)

Description

Creates the default chain of credentials to attempt for cached token retrieval. The credentials are tried in order until one returns a valid cached token. The default chain includes:

1. Authorization Code Credential - Cached tokens from browser-based authentication

2. Device Code Credential - Cached tokens from device code flow

3. Azure CLI Credential - Cached tokens from Azure CLI authentication

Usage

cached_token_credential_chain(scope = NULL, tenant_id = NULL, client_id = NULL)

Arguments

Value

A credential_chain object containing the sequence of credential providers to check for cached tokens.

See Also

CachedTokenCredential, credential_chain()

Description

A credential class that retrieves tokens from the cache only, without triggering interactive authentication flows. This is useful for non-interactive sessions where you want to use previously cached tokens from DeviceCode or AuthCode credentials.

Details

This credential attempts to retrieve cached tokens from a chain of interactive credentials (AuthCode and DeviceCode by default). It will not prompt for new authentication - it only returns tokens that are already cached.

This is particularly useful for:

• Non-interactive R sessions (e.g., scheduled scripts, CI/CD)

• Scenarios where you've previously authenticated interactively and want to reuse those cached tokens

Public fields

Active bindings

Methods

Public methods

• CachedTokenCredential$new()

• CachedTokenCredential$get_token()

• CachedTokenCredential$req_auth()

• CachedTokenCredential$clone()

Method new()

Create a new CachedTokenCredential object

Usage

CachedTokenCredential$new(
  scope = NULL,
  tenant_id = NULL,
  client_id = NULL,
  chain = NULL
)

Arguments

Returns

A new CachedTokenCredential object

Method get_token()

Get an access token from the cache

Usage

CachedTokenCredential$get_token()

Returns

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

Method req_auth()

Add authentication to an httr2 request

Usage

CachedTokenCredential$req_auth(req)

Arguments

Returns

The request object with authentication configured

Method clone()

The objects of this class are cloneable with this method.

Usage

CachedTokenCredential$clone(deep = FALSE)

Arguments

Examples

## Not run: 
# Create credential with default settings
cred <- CachedTokenCredential$new(
  scope = "https://graph.microsoft.com/.default",
  tenant_id = "my-tenant-id"
)

# Get a cached token (will fail if no cached token exists)
token <- cred$get_token()

# Use with httr2 request
req <- httr2::request("https://graph.microsoft.com/v1.0/me")
req <- cred$req_auth(req)

## End(Not run)

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 or NULL. 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)

Description

Creates a custom chain of credential providers to attempt during authentication. Credentials are tried in the order they are provided until one successfully authenticates. This allows you to customize the authentication flow beyond the default credential chain.

Usage

credential_chain(...)

Arguments

Value

A credential_chain object containing the specified sequence of credential providers.

See Also

default_credential_chain(), get_token_provider()

Examples

# Create a custom chain with only non-interactive credentials
custom_chain <- credential_chain(
  client_secret = ClientSecretCredential,
  azure_cli = AzureCLICredential
)

# Use the custom chain to get a token
## Not run: 
token <- get_token(
  scope = "https://graph.microsoft.com/.default",
  chain = custom_chain
)

## End(Not run)

Description

Returns Microsoft's public Azure CLI client ID (⁠04b07795-8ddb-461a-bbee-02f9e1bf7b46⁠). This is the default client_id used by interactive credentials when no application-specific client ID is configured.

Usage

default_azure_cli_client_id()

Value

A character string with the Azure CLI client ID

Examples

default_azure_cli_client_id()

Description

Retrieves the Azure client ID in priority order:

1. AZURE_CLIENT_ID environment variable

2. Built-in fallback (Microsoft's public Azure CLI client ID)

Usage

default_azure_client_id()

Value

A character string with the client ID

Examples

default_azure_client_id()

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()

Description

Retrieves the Azure configuration directory from the AZURE_CONFIG_DIR environment variable, or falls back to the platform-specific default.

Usage

default_azure_config_dir()

Value

A character string with the Azure configuration directory path

Examples

default_azure_config_dir()

Description

Retrieves the Azure authority host in priority order:

1. AZURE_AUTHORITY_HOST environment variable

2. Built-in fallback (login.microsoftonline.com)

Usage

default_azure_host()

Value

A character string with the authority host URL

Examples

default_azure_host()

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"
)

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")
default_azure_scope("graph")
default_azure_scope("storage")

Description

Retrieves the Azure tenant ID in priority order:

1. AZURE_TENANT_ID environment variable

2. Built-in fallback ("common")

Usage

default_azure_tenant_id()

Value

A character string with the tenant ID

Examples

default_azure_tenant_id()

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")

Description

Creates the default chain of credentials to attempt during authentication. The credentials are tried in order until one successfully authenticates. The default chain includes:

1. Client Secret Credential - Uses client ID and secret

2. Authorization Code Credential - Interactive browser-based authentication

3. Device Code Credential - Interactive device code flow

4. Azure CLI Credential - Uses credentials from Azure CLI

Usage

default_credential_chain()

Value

A credential_chain object containing the default sequence of credential providers.

See Also

credential_chain(), get_token_provider()

Description

Retrieves the path to the federated identity token file from the AZURE_FEDERATED_TOKEN_FILE environment variable, or returns NULL if not set. Used by WorkloadIdentityCredential.

Usage

default_federated_token_file()

Value

A character string with the file path, or NULL if not set

Examples

default_federated_token_file()

Description

Returns the default host used to construct Microsoft Graph API URLs (graph.microsoft.com).

Usage

default_graph_endpoint()

Value

A character string with the Microsoft Graph endpoint host.

Examples

default_graph_endpoint()

Description

Returns the default host used to construct Azure Log Analytics query URLs (api.loganalytics.io).

Usage

default_log_analytics_endpoint()

Value

A character string with the Log Analytics query endpoint host.

Examples

default_log_analytics_endpoint()

Description

Returns the path to the MSAL token cache file shared by the Azure CLI and Azure SDKs. Defaults to msal_token_cache.json inside the Azure config directory (see default_azure_config_dir()).

Usage

default_msal_token_cache()

Value

A character string with the path to the MSAL token cache file.

See Also

default_azure_config_dir(), write_msal_token()

Description

A pass-through credential function that performs no authentication. This function returns the request object unchanged, allowing API calls to be made without adding any authentication headers or tokens.

Usage

default_non_auth(req)

Arguments

Value

The same httr2::request() object, unmodified

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()

Description

Retrieves the Azure refresh token from the AZURE_REFRESH_TOKEN environment variable, or returns NULL if not set.

Usage

default_refresh_token()

Value

A character string with the refresh token, or NULL if not set

Examples

default_refresh_token()

Description

Converts data.frame results in the parsed response to data.table objects when the data.table package is available. Applied automatically by api_client unless overridden via the response_handler argument.

Usage

default_response_handler(content)

Arguments

Value

The processed content, with any data.frame objects converted to data.table if the data.table package is installed.

Description

Returns the default endpoint suffix used to construct Azure Data Lake Storage Gen2 DFS URLs.

Usage

default_storage_endpoint()

Value

A character string with the DFS endpoint suffix.

Examples

default_storage_endpoint()

Description

An R6 class that provides lazy initialization of credential providers. The credential provider is created on first access using the default credential chain.

Details

This class wraps the credential discovery process in an R6 object with a lazily evaluated provider field. The provider is only created when first accessed, using the same logic as get_token_provider().

Public fields

Active bindings

Methods

Public methods

• DefaultCredential$new()

• DefaultCredential$get_token()

• DefaultCredential$req_auth()

• DefaultCredential$clone()

Method new()

Create a new DefaultCredential object

Usage

DefaultCredential$new(
  scope = NULL,
  tenant_id = NULL,
  client_id = NULL,
  client_secret = NULL,
  use_cache = c("disk", "memory"),
  offline = TRUE,
  chain = default_credential_chain(),
  verbose = opts$get("chain_verbose")
)

Arguments

Returns

A new DefaultCredential object

Method get_token()

Get an access token using the credential chain

Usage

DefaultCredential$get_token()

Returns

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

Method req_auth()

Add authentication to an httr2 request

Usage

DefaultCredential$req_auth(req)

Arguments

Returns

The request object with authentication configured

Method clone()

The objects of this class are cloneable with this method.

Usage

DefaultCredential$clone(deep = FALSE)

Arguments

Examples

# Create a DefaultCredential object
cred <- DefaultCredential$new(
  scope = "https://graph.microsoft.com/.default",
  tenant_id = "my-tenant-id"
)

## Not run: 
# Get a token (triggers lazy initialization)
token <- cred$get_token()

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

# Or access the provider directly
provider <- cred$provider

## End(Not run)

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$clone()

Method new()

Create a new device code credential

Usage

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

Arguments

Returns

A new DeviceCodeCredential object

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)

Description

Creates a function that retrieves authentication tokens and formats them as HTTP Authorization headers. This function handles credential discovery and returns a callable method that generates Bearer token headers when invoked.

Usage

get_credential_auth(
  scope = NULL,
  tenant_id = NULL,
  client_id = NULL,
  client_secret = NULL,
  use_cache = "disk",
  offline = TRUE,
  chain = default_credential_chain()
)

Arguments

Value

A function that, when called, returns a named list with an Authorization element containing the Bearer token, suitable for use with httr2::req_headers().

See Also

get_token(), get_request_authorizer(), get_token_provider()

Examples

## Not run: 
# Create an authentication function
auth_fn <- get_credential_auth(
  scope = "https://graph.microsoft.com/.default"
)

# Call it to get headers
auth_headers <- auth_fn()

# Use with httr2
req <- httr2::request("https://graph.microsoft.com/v1.0/me") |>
  httr2::req_headers(!!!auth_headers)

## End(Not run)

Description

Discovers and returns an authenticated credential object from a chain of credential providers. This function attempts each credential in the chain until one successfully authenticates, returning the first successful credential object.

Usage

get_credential_provider(
  scope = NULL,
  tenant_id = NULL,
  client_id = NULL,
  client_secret = NULL,
  use_cache = "disk",
  offline = TRUE,
  oauth_host = NULL,
  oauth_endpoint = NULL,
  chain = NULL,
  allow_interactive = rlang::is_interactive(),
  verbose = opts$get("chain_verbose"),
  interactive = NULL
)

Arguments

Value

A credential object that inherits from the Credential class and has successfully authenticated.

See Also

get_token_provider(), get_request_authorizer(), default_credential_chain()

Examples

## Not run: 
# Get a credential provider with default settings
cred <- get_credential_provider(
  scope = "https://graph.microsoft.com/.default",
  tenant_id = "my-tenant-id"
)

# Use the credential to get a token
token <- cred$get_token()

## End(Not run)

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 = TRUE,
  chain = default_credential_chain()
)

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)

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 = TRUE,
  chain = default_credential_chain()
)

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)

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 = TRUE,
  chain = default_credential_chain()
)

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)

Description

Determines whether the current R session is running in a hosted environment such as Google Colab, VS Code, Kubernetes, or RStudio Server (non-localhost).

Usage

is_hosted_session()

Details

This function checks for (in order):

• Option override: if azr.hosted option is set, returns isTRUE() of its value

• Google Colab: presence of the COLAB_RELEASE_TAG environment variable

• VS Code: presence of the VSCODE_INJECTION or VSCODE_PROXY_URI environment variable

• Kubernetes: presence of the KUBERNETES_SERVICE_HOST environment variable

• RStudio Server: RSTUDIO_PROGRAM_MODE is "server" and RSTUDIO_HTTP_REFERER does not contain "localhost"

Value

A logical value: TRUE if running in a hosted session (Google Colab, VS Code, Kubernetes, or remote RStudio Server), FALSE otherwise.

Examples

if (is_hosted_session()) {
  message("Running in a hosted environment")
}

Description

Authenticates using an Azure managed identity. Supports both system-assigned and user-assigned managed identities. This credential works when code is running inside an Azure environment that has a managed identity configured (e.g., VMs, App Service, Container Instances, AKS pods).

Details

Authentication is performed by querying the Azure Instance Metadata Service (IMDS) endpoint at ⁠http://169.254.169.254/metadata/identity/oauth2/token⁠. No credentials need to be stored — the identity is granted by the Azure platform.

To use a system-assigned managed identity, leave client_id as NULL. To use a user-assigned managed identity, supply its client_id.

This credential fails immediately (2-second timeout) when not running inside Azure, so it is safe to include early in a credential chain.

Super class

azr::Credential -> ManagedIdentityCredential

Public fields

Methods

Public methods

• ManagedIdentityCredential$new()

• ManagedIdentityCredential$get_token()

• ManagedIdentityCredential$req_auth()

• ManagedIdentityCredential$clone()

Method new()

Create a new managed identity credential

Usage

ManagedIdentityCredential$new(scope = NULL, client_id = NULL)

Arguments

Returns

A new ManagedIdentityCredential object

Method get_token()

Get an access token from the IMDS endpoint

Usage

ManagedIdentityCredential$get_token()

Details

Returns a valid in-object cached token immediately if one exists. Otherwise queries the Azure Instance Metadata Service (IMDS) for a new token.

Returns

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

Method req_auth()

Add managed identity authentication to an httr2 request

Usage

ManagedIdentityCredential$req_auth(req)

Arguments

Returns

The request object with a Bearer token authorization header

Method clone()

The objects of this class are cloneable with this method.

Usage

ManagedIdentityCredential$clone(deep = FALSE)

Arguments

Examples

## Not run: 
# System-assigned managed identity (no client_id needed)
cred <- ManagedIdentityCredential$new(
  scope = "https://management.azure.com/.default"
)

# User-assigned managed identity
cred <- ManagedIdentityCredential$new(
  scope = "https://management.azure.com/.default",
  client_id = "your-user-assigned-client-id"
)

token <- cred$get_token()

## End(Not run)

Description

Splits an Azure Storage URL or Hadoop filesystem path into its constituent parts. Supports all common Azure Storage path formats:

⁠abfss://⁠ / ⁠abfs://⁠

Azure Data Lake Storage Gen2 (DFS endpoint), used by Spark / Hadoop.

⁠wasbs://⁠ / ⁠wasb://⁠

Legacy Azure Blob filesystem scheme, used by older Spark / Hadoop integrations.

⁠https://⁠ / ⁠http://⁠

Standard Azure Blob or DFS REST endpoint, optionally with a SAS token query string.

⁠az://⁠ / ⁠azure://⁠

Non-standard aliases used by some Python tools (e.g. adlfs); parsed using the same [email protected]/path shape as ⁠abfs://⁠.

The format field is inferred from the path on a best-effort basis: "delta" when the path contains ⁠_delta_log⁠; a file extension name ("parquet", "csv", "json", "avro", "orc", "text") when the last path segment has a recognised extension; "folder" when there is no extension; and NA for unrecognised extensions.

Usage

parse_storage_path(path)

Arguments

Value

An azure_storage_path object (a named list) with the fields:

scheme

URL scheme, e.g. "abfss", "wasbs", "https".

storage_account

Storage account name.

endpoint

Storage endpoint type: "dfs" or "blob".

endpoint_suffix

Host suffix after the endpoint label, e.g. "core.windows.net" (Azure public), "core.usgovcloudapi.net" (US Government), "core.chinacloudapi.cn" (China), or "storage.azure.net" (DNS-zone endpoints). Use this to distinguish sovereign clouds from the public cloud.

container

Container name. Called "filesystem" in ADLS Gen2 / ABFS contexts; both refer to the same underlying object.

path

Path within the container, without a leading /. Empty string if the URL points to the container root.

format

Inferred dataset or file format (see above).

query

Named list of query parameters (e.g. a parsed SAS token), or NULL if none.

original

The original input string.

Examples

parse_storage_path(
  "abfss://[email protected]/data/sales/2024"
)

parse_storage_path(
  "https://myaccount.blob.core.windows.net/mycontainer/data/events.parquet"
)

parse_storage_path(
  "wasbs://[email protected]/data/delta_table"
)

Description

Authenticates using an existing refresh token. This credential is useful when you have obtained a refresh token through another authentication flow and want to use it to get new access tokens without interactive authentication.

Details

The refresh token credential uses the OAuth 2.0 refresh token flow to obtain new access tokens. It requires a valid refresh token that was previously obtained through an interactive flow (e.g., authorization code or device code).

This is particularly useful for:

• Non-interactive sessions where you have a pre-obtained refresh token

• Long-running applications that need to refresh tokens automatically

• Scenarios where you want to avoid repeated interactive authentication

Super class

azr::Credential -> RefreshTokenCredential

Public fields

Methods

Public methods

• RefreshTokenCredential$new()

• RefreshTokenCredential$validate()

• RefreshTokenCredential$get_token()

• RefreshTokenCredential$req_auth()

• RefreshTokenCredential$clone()

Method new()

Create a new refresh token credential

Usage

RefreshTokenCredential$new(
  refresh_token = default_refresh_token(),
  scope = NULL,
  tenant_id = NULL,
  client_id = NULL
)

Arguments

Returns

A new RefreshTokenCredential object

Method validate()

Validate the credential configuration

Usage

RefreshTokenCredential$validate()

Details

Checks that the refresh token is provided and not NA or NULL. Calls the parent class validation method.

Method get_token()

Get an access token using the refresh token flow

Usage

RefreshTokenCredential$get_token()

Returns

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

Method req_auth()

Add OAuth refresh token authentication to an httr2 request

Usage

RefreshTokenCredential$req_auth(req)

Arguments

Returns

The request object with OAuth refresh token authentication configured

Method clone()

The objects of this class are cloneable with this method.

Usage

RefreshTokenCredential$clone(deep = FALSE)

Arguments

Examples

## Not run: 
# Create credential with a refresh token
cred <- RefreshTokenCredential$new(
  refresh_token = "your-refresh-token",
  scope = "https://management.azure.com/.default",
  tenant_id = "your-tenant-id",
  client_id = "your-client-id"
)

# 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)

Description

Authenticates using Azure Workload Identity by reading a federated token from a file and exchanging it for an Azure AD access token. This is commonly used in Kubernetes environments (AKS) where a service account token is mounted into the pod.

Details

The credential implements the OAuth 2.0 client credentials flow with a JWT bearer assertion (client_assertion). It reads the federated identity token from a file on each call to get_token() so that token rotation by the runtime (e.g., Kubernetes) is automatically picked up.

The following environment variables are used when parameters are not provided:

• AZURE_CLIENT_ID: Client (application) ID of the Azure AD application

• AZURE_TENANT_ID: Azure AD tenant ID

• AZURE_FEDERATED_TOKEN_FILE: Path to the file containing the federated token

Super class

azr::Credential -> WorkloadIdentityCredential

Public fields

Methods

Public methods

• WorkloadIdentityCredential$new()

• WorkloadIdentityCredential$validate()

• WorkloadIdentityCredential$get_token()

• WorkloadIdentityCredential$req_auth()

• WorkloadIdentityCredential$clone()

Method new()

Create a new Workload Identity credential

Usage

WorkloadIdentityCredential$new(
  scope = NULL,
  tenant_id = Sys.getenv(environment_variables$azure_tenant_id, unset = NA_character_),
  client_id = Sys.getenv(environment_variables$azure_client_id, unset = NA_character_),
  token_file_path = default_federated_token_file()
)

Arguments

Returns

A new WorkloadIdentityCredential object

Method validate()

Validate the credential configuration

Usage

WorkloadIdentityCredential$validate()

Details

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

Method get_token()

Get an access token by exchanging the federated token

Usage

WorkloadIdentityCredential$get_token()

Details

Returns a valid in-object cached token immediately if one exists. Otherwise reads the federated token from the file and exchanges it for a new access token so that token rotation performed by the runtime is automatically reflected.

Returns

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

Method req_auth()

Add authentication to an httr2 request

Usage

WorkloadIdentityCredential$req_auth(req)

Arguments

Returns

The request object with a Bearer token authorization header

Method clone()

The objects of this class are cloneable with this method.

Usage

WorkloadIdentityCredential$clone(deep = FALSE)

Arguments

Examples

## Not run: 
# Create credential using environment variables
# (requires AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_FEDERATED_TOKEN_FILE)
cred <- WorkloadIdentityCredential$new(
  scope = "https://management.azure.com/.default"
)

# Or supply parameters directly
cred <- WorkloadIdentityCredential$new(
  tenant_id = "your-tenant-id",
  client_id = "your-client-id",
  token_file_path = "/var/run/secrets/azure/tokens/azure-identity-token",
  scope = "https://management.azure.com/.default"
)

# 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)

Description

Writes an httr2::oauth_token() object into the MSAL token cache JSON file (msal_token_cache.json) shared by the Azure SDK and Azure CLI. The resulting entry is readable by other Azure tools (Python SDK, Azure CLI, and the rest of this package via az_cli_get_cached_token()).

Usage

write_msal_token(token, cache_file = default_msal_token_cache())

Arguments

Details

The function adds or overwrites AccessToken, RefreshToken (when the token carries a refresh token), Account, and AppMetadata sections. Existing entries for other accounts or clients are preserved.

The home_account_id follows the MSAL convention "<object_id>.<tenant_id>" where object_id is the Azure AD OID of the authenticated principal. Cache entry keys are built in the same format used by the Azure CLI and MSAL Python:

• AccessToken: ⁠<home_account_id>-<environment>-accesstoken-<client_id>-<realm>-<target>⁠

• RefreshToken: ⁠<home_account_id>-<environment>-refreshtoken-<client_id>--⁠

• Account: ⁠<home_account_id>-<environment>-<realm>⁠

• AppMetadata: ⁠appmetadata-<environment>-<client_id>⁠

Value

Invisibly returns the path to the cache file.

See Also

az_cli_get_cached_token(), httr2::oauth_token()