Authentication

The package uses MSAL client-credentials authentication.

What the client does

• builds an msal.ConfidentialClientApplication
• uses the authority https://login.microsoftonline.com/{tenant_id}
• requests the Defender default scope
• raises AuthenticationError when MSAL does not return an access token

Inputs

Authentication is driven by these constructor values on MDEClient:

• tenant_id
• client_id
• client_secret
• optional token_cache

Token cache behavior

If you do not pass a token cache, the client uses an in-memory msal.TokenCache. If you need persistence, inject your own cache implementation.

Error model

AuthenticationError is raised when:

• MSAL returns None
• MSAL returns a result without access_token

HTTP-level API failures that happen after authentication are not wrapped as AuthenticationError; they bubble up through httpx status handling.

See also

• Authenticate with client credentials
• MDEClient

API

auth

Authentication primitives for the Microsoft Defender for Endpoint client.

This module owns the OAuth2 client-credentials flow used by MDEClient to acquire bearer tokens for the Defender API. It wraps MSAL so endpoint code can simply read MSALAuth.token on each request without worrying about cache hits, expiry, or refresh.

Exports

MSALAuth: Confidential-client wrapper that acquires and caches tokens. AuthenticationError: Raised when MSAL fails to return an access token.

MSALAuth

MSALAuth(
    tenant_id: str,
    client_id: str,
    client_secret: str,
    *,
    token_cache: TokenCache | None = None,
)

OAuth2 client-credentials token acquisition for the Defender API.

Wraps msal.ConfidentialClientApplication and exposes a single token property that returns a current bearer token, transparently using the underlying MSAL cache to avoid unnecessary round-trips to Azure AD.

Parameters:

Name	Type	Description	Default
tenant_id	str	Azure AD tenant ID for the application registration.	required
client_id	str	App registration client ID.	required
client_secret	str	App registration client secret.	required
token_cache	TokenCache | None	Optional msal.TokenCache (or SerializableTokenCache) for cross-process or persistent caching. Defaults to a new in-memory msal.TokenCache().	None

Configure the underlying MSAL confidential-client application.

token property

token: str

Return a valid bearer token for the Defender API.

MSAL serves the token from its cache when one is still valid, and fetches a fresh token from Azure AD otherwise. Callers should read this property on every request rather than caching the string themselves.

Returns:

Type	Description
str	A bearer access token suitable for the Authorization header.

Raises:

Type	Description
AuthenticationError	If MSAL fails to return a token (missing credentials, invalid authority, app permission issues, etc.).

AuthenticationError

Bases: Exception

Raised when MSAL fails to acquire an access token for the Defender API.