sda.api.graph_auth#

MS Graph API authentication via MSAL.

Two authentication modes are supported, selected automatically by get_token_auto():

  • CI / service-principal mode — all three AZURE_* environment variables (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET) must be set. Uses get_access_token() (client-credentials flow).

  • Interactive desktop mode (SDA-Desktop registration) — default when the env vars are not set. Uses get_access_token_interactive() which tries PublicClientApplication.acquire_token_silent() first (reads the persistent token cache at ~/.sda/token_cache.bin), then falls back to acquire_token_interactive() (browser popup), and finally falls back to acquire_token_by_device_flow() if no display is detected.

Note

Token cache concurrency — the cache file ~/.sda/token_cache.bin is read and written without a file lock. Simultaneous calls from multiple processes on the same machine may produce a race condition on the cache file. In practice this is rare because the silent-refresh path is read-only unless a new token is issued. A proper file lock is left as a future improvement.

Attributes#

GRAPH_SCOPE

GRAPH_DELEGATED_SCOPE

ConfidentialClientApplication

PublicClientApplication

SerializableTokenCache

Functions#

get_access_token(tenant_id, client_id, client_secret)

Acquire an access token using client credentials flow (CI / service principal).

get_access_token_interactive(tenant_id, client_id[, ...])

Acquire an access token via interactive user login (desktop flow).

get_token_auto([cache_path])

Acquire a Graph API access token, auto-detecting the auth mode.

Module Contents#

sda.api.graph_auth.GRAPH_SCOPE = ['https://graph.microsoft.com/.default']#
sda.api.graph_auth.GRAPH_DELEGATED_SCOPE = ['https://graph.microsoft.com/Files.Read']#
sda.api.graph_auth.ConfidentialClientApplication#
sda.api.graph_auth.PublicClientApplication#
sda.api.graph_auth.SerializableTokenCache#
sda.api.graph_auth.get_access_token(tenant_id, client_id, client_secret)#

Acquire an access token using client credentials flow (CI / service principal).

Parameters:

  • tenant_id (str) – Azure AD tenant ID.

  • client_id (str) – Azure AD application (client) ID.

  • client_secret (str) – Azure AD client secret.

Returns:

Bearer access token.

Return type:

str

Raises:

RuntimeError – If the token acquisition fails.

sda.api.graph_auth.get_access_token_interactive(tenant_id, client_id, cache_path=_DEFAULT_CACHE_PATH)#

Acquire an access token via interactive user login (desktop flow).

Tries the following in order:

  1. Silent — return cached / refreshed token without user interaction.

  2. Interactive — open a browser window for the user to sign in (only if a display is detected; see _has_display()).

  3. Device-code — print a URL and code the user can enter on any device (fallback for headless / SSH environments).

The token is cached in cache_path (default ~/.sda/token_cache.bin) and silently refreshed on subsequent calls so the browser only opens once.

Warning

Concurrency — the cache file is not file-locked. Concurrent processes may race on the file. This is a known v1 limitation.

Parameters:

  • tenant_id (str) – Azure AD tenant ID for Spark Cleantech.

  • client_id (str) – Public application (client) ID registered in Azure AD.

  • cache_path (Path, optional) – Path to the serialised token cache file.

Returns:

Bearer access token.

Return type:

str

Raises:

RuntimeError – If all authentication attempts fail.

sda.api.graph_auth.get_token_auto(cache_path=_DEFAULT_CACHE_PATH)#

Acquire a Graph API access token, auto-detecting the auth mode.

  • If the current request set a delegated token via sda.api.graph_context.set_request_graph_token() (SDA-Cloud web session), that token is returned immediately (even when CI env vars are set).

  • If all three AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET environment variables are set, uses the client-credentials (CI) flow.

  • If only some are set, raises RuntimeError naming the missing variables (partial configuration is treated as a misconfiguration, not a silent fallback to interactive mode).

  • Otherwise, uses the interactive desktop flow with the hardcoded Spark tenant and SPARK_DESKTOP_CLIENT_ID from sda.api.graph_sharepoint_ids.

Returns:

Bearer access token.

Return type:

str

Raises:

RuntimeError – If CI env vars are partially set, or if authentication fails.