or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication-flows.mddevice-code-flow.mdindex.mdlogging-error-handling.mdtoken-caching.md
tile.json

tessl/pypi-adal

Azure Active Directory Authentication Library for Python that provides OAuth2/OpenID Connect authentication flows and token management for accessing Azure AD protected resources

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/adal@1.2.x

To install, run

npx @tessl/cli install tessl/pypi-adal@1.2.0

index.mddocs/

ADAL (Azure Active Directory Authentication Library)

A Python library that makes it easy for applications to authenticate to Azure Active Directory (AAD) in order to access AAD protected web resources. ADAL provides OAuth2 and OpenID Connect authentication flows with comprehensive token management, caching, and refresh capabilities.

Note: This library is legacy. Microsoft recommends migrating to MSAL Python for new projects.

Package Information

  • Package Name: adal
  • Version: 1.2.7
  • Language: Python
  • Installation: pip install adal
  • License: MIT
  • Dependencies: PyJWT, requests, python-dateutil, cryptography

Core Imports

import adal

Most common usage pattern:

from adal import AuthenticationContext, TokenCache, AdalError

Individual imports:

from adal import (
    AuthenticationContext,
    TokenCache, 
    AdalError,
    set_logging_options,
    get_logging_options,
    ADAL_LOGGER_NAME,
    __version__
)

Basic Usage

import adal

# Create authentication context
authority_url = 'https://login.microsoftonline.com/your-tenant-id'
context = adal.AuthenticationContext(authority_url)

# Authenticate using client credentials flow
resource = 'https://management.azure.com/'
client_id = 'your-client-id'
client_secret = 'your-client-secret'

token = context.acquire_token_with_client_credentials(
    resource, 
    client_id, 
    client_secret
)

print("Access token:", token['accessToken'])
print("Token expires on:", token['expiresOn'])

Architecture

ADAL follows a context-based architecture centered around the AuthenticationContext class:

  • AuthenticationContext: Main entry point that manages authentication flows and token acquisition
  • TokenCache: Thread-safe token storage with serialization/deserialization capabilities
  • Authority: Validates and discovers OAuth2 endpoints for Azure AD tenants
  • Token Management: Automatic refresh handling and cache integration

The library supports multiple OAuth2 flows including authorization code, client credentials, resource owner password credentials, refresh token, certificate-based authentication, and device code flows.

Capabilities

Authentication Flows

Core authentication functionality supporting all major OAuth2 flows for Azure Active Directory integration. Includes client credentials, username/password, authorization code, refresh token, certificate-based, and device code authentication methods.

class AuthenticationContext:
    def __init__(self, authority, validate_authority=None, cache=None, 
                 api_version=None, timeout=None, enable_pii=False, 
                 verify_ssl=None, proxies=None): ...
    
    @property
    def options(self): ...
    
    @options.setter
    def options(self, val): ...
    
    def acquire_token(self, resource, user_id, client_id): ...
    def acquire_token_with_username_password(self, resource, username, password, client_id): ...
    def acquire_token_with_client_credentials(self, resource, client_id, client_secret): ...
    def acquire_token_with_authorization_code(self, authorization_code, redirect_uri, 
                                             resource, client_id, client_secret=None, 
                                             code_verifier=None): ...
    def acquire_token_with_refresh_token(self, refresh_token, client_id, resource, 
                                        client_secret=None): ...
    def acquire_token_with_client_certificate(self, resource, client_id, certificate, 
                                             thumbprint, public_certificate=None): ...

Authentication Flows

Device Code Authentication

Specialized OAuth2 device code flow for applications running on devices without web browsers or with limited input capabilities, such as IoT devices, CLI tools, or applications on smart TVs.

class AuthenticationContext:
    def acquire_user_code(self, resource, client_id, language=None): ...
    def acquire_token_with_device_code(self, resource, user_code_info, client_id): ...
    def cancel_request_to_get_token_with_device_code(self, user_code_info): ...

Device Code Flow

Token Caching

Thread-safe token storage and management with serialization capabilities for persistent caching across application sessions. Supports token lookup, storage, removal, and automatic cleanup.

class TokenCache:
    def __init__(self, state=None): ...
    def find(self, query): ...
    def add(self, entries): ...
    def remove(self, entries): ...
    def serialize(self): ...
    def deserialize(self, state): ...
    def read_items(self): ...
    
    @property
    def has_state_changed(self): ...

Token Caching

Logging and Error Handling

Comprehensive logging system with PII scrubbing capabilities and custom exception handling for authentication errors. Includes correlation ID support and configurable log levels.

def set_logging_options(options=None): ...
def get_logging_options(): ...

class AdalError(Exception):
    def __init__(self, error_msg, error_response=None): ...

Logging and Error Handling

Types

Authentication Response

# Return type for all acquire_token_* methods
AuthenticationResult = dict[str, Any]  # Contains:
#   "accessToken": str - JWT access token
#   "refreshToken": str - Refresh token (if available)  
#   "tokenType": str - Token type (usually "Bearer")
#   "expiresIn": int - Seconds until expiration
#   "expiresOn": str - ISO 8601 expiration timestamp
#   "resource": str - Resource URI
#   "userId": str - User identifier
#   "userInfo": dict - User profile information

Cache Query

# Query parameters for TokenCache.find()
CacheQuery = dict[str, Any]  # Optional keys:
#   "_clientId": str - OAuth client ID (note underscore prefix)
#   "userId": str - User identifier
#   "isMRRT": bool - Match multi-resource refresh tokens

Device Code Response

# Return type for acquire_user_code()
DeviceCodeResult = dict[str, Any]  # Contains:
#   "userCode": str - Code for user to enter
#   "deviceCode": str - Device code for token requests
#   "verificationUrl": str - URL where user enters code
#   "expiresIn": int - Seconds until code expires
#   "interval": int - Polling interval in seconds
#   "message": str - Instructions for user

Constants

__version__: str  # Package version: "1.2.7"
ADAL_LOGGER_NAME: str  # Logger name: "adal-python"