0
# Azure Identity
1

2
The Microsoft Azure Identity Library for Python provides credentials to authenticate with Microsoft Entra ID (formerly Azure Active Directory). It serves as the central authentication solution for Azure SDK clients, offering a unified interface for acquiring Azure access tokens across diverse environments including local development, CI/CD pipelines, and Azure-hosted applications.
3

4
## Package Information
5

6
- **Package Name**: azure-identity
7
- **Language**: Python
8
- **Installation**: `pip install azure-identity`
9
- **Version**: 1.24.0
10

11
## Core Imports
12

13
```python
14
from azure.identity import DefaultAzureCredential
15
```
16

17
Comprehensive imports for specific credential types:
18

19
```python
20
from azure.identity import (
21
    DefaultAzureCredential,
22
    ClientSecretCredential, 
23
    CertificateCredential,
24
    ManagedIdentityCredential,
25
    InteractiveBrowserCredential,
26
    DeviceCodeCredential,
27
    AzureCliCredential,
28
    ChainedTokenCredential
29
)
30
```
31

32
For async support:
33

34
```python
35
from azure.identity.aio import DefaultAzureCredential as AsyncDefaultAzureCredential
36
```
37

38
## Basic Usage
39

40
```python
41
from azure.identity import DefaultAzureCredential
42
from azure.storage.blob import BlobServiceClient
43

44
# Create credential - automatically detects environment and uses appropriate authentication
45
credential = DefaultAzureCredential()
46

47
# Use with any Azure SDK client
48
blob_client = BlobServiceClient(
49
    account_url="https://mystorageaccount.blob.core.windows.net",
50
    credential=credential
51
)
52

53
# The credential automatically handles token acquisition and refresh
54
blobs = blob_client.list_containers()
55
for blob in blobs:
56
    print(blob.name)
57

58
# For specific authentication scenarios
59
from azure.identity import ClientSecretCredential
60

61
# Service principal authentication
62
sp_credential = ClientSecretCredential(
63
    tenant_id="your-tenant-id",
64
    client_id="your-client-id", 
65
    client_secret="your-client-secret"
66
)
67

68
# Interactive authentication for user scenarios  
69
from azure.identity import InteractiveBrowserCredential
70

71
user_credential = InteractiveBrowserCredential()
72
```
73

74
## Architecture
75

76
Azure Identity implements the **TokenCredential Protocol** that all Azure SDK clients accept. This protocol defines two key methods:
77

78
- `get_token(*scopes)` - Synchronously acquires an access token for the specified scopes
79
- `get_token_info(*scopes)` - Provides token with additional metadata
80

81
### Credential Chain Pattern
82

83
The `DefaultAzureCredential` implements a **credential chain pattern**, attempting authentication methods in this order:
84

85
1. **Environment variables** - Service principal or user authentication via environment variables
86
2. **Workload Identity** - For Azure Kubernetes Service workloads using service account tokens  
87
3. **Managed Identity** - For Azure-hosted applications (VMs, App Service, Function Apps, etc.)
88
4. **Shared Token Cache** - Cached tokens from Microsoft developer tools
89
5. **Visual Studio Code** - Azure account from VS Code Azure extension
90
6. **Azure CLI** - Account logged into Azure CLI
91
7. **Azure PowerShell** - Account logged into Azure PowerShell
92
8. **Azure Developer CLI** - Account logged into Azure Developer CLI
93
9. **Interactive Browser** - Opens browser for user authentication (disabled by default)
94

95
This design provides **zero-configuration authentication** that works across local development and production environments without code changes.
96

97
### Common Authentication Patterns
98

99
- **Service Principal**: Applications authenticate with client credentials (secret or certificate)
100
- **User Authentication**: Interactive flows for user-facing applications
101
- **Managed Identity**: Azure services authenticate automatically without storing credentials
102
- **Developer Authentication**: Local development using existing Azure CLI/PowerShell sessions
103

104
## Capabilities
105

106
### Core Credentials
107

108
Essential credential classes providing the foundation of Azure authentication, including the intelligent DefaultAzureCredential and credential chaining capabilities.
109

110
```python { .api }
111
class DefaultAzureCredential:
112
    def __init__(self, **kwargs): ...
113

114
class ChainedTokenCredential:
115
    def __init__(self, *credentials): ...
116
```
117

118
[Core Credentials](./core-credentials.md)
119

120
### Service Principal Credentials
121

122
Authenticate applications and services using Azure Active Directory service principals with client secrets, certificates, or custom client assertions.
123

124
```python { .api }
125
class ClientSecretCredential:
126
    def __init__(self, tenant_id: str, client_id: str, client_secret: str, **kwargs): ...
127

128
class CertificateCredential:
129
    def __init__(self, tenant_id: str, client_id: str, certificate_path: Optional[str] = None, **kwargs): ...
130

131
class ClientAssertionCredential:
132
    def __init__(self, tenant_id: str, client_id: str, func: Callable[[], str], **kwargs): ...
133
```
134

135
[Service Principal Credentials](./service-principal.md)
136

137
### Interactive User Credentials  
138

139
Enable user authentication through interactive flows including browser-based authentication, device code flow, and username/password authentication.
140

141
```python { .api }
142
from azure.identity._constants import DEVELOPER_SIGN_ON_CLIENT_ID
143

144
class InteractiveBrowserCredential:
145
    def __init__(self, *, client_id: str = DEVELOPER_SIGN_ON_CLIENT_ID, **kwargs): ...
146

147
class DeviceCodeCredential:
148
    def __init__(self, client_id: str = DEVELOPER_SIGN_ON_CLIENT_ID, *, timeout: Optional[int] = None, **kwargs): ...
149

150
class UsernamePasswordCredential:
151
    def __init__(self, client_id: str, username: str, password: str, **kwargs): ...
152
```
153

154
[Interactive User Credentials](./interactive.md)
155

156
### Azure Platform Credentials
157

158
Leverage Azure's native authentication mechanisms including managed identities, workload identities, and Azure service-specific authentication.
159

160
```python { .api }
161
class ManagedIdentityCredential:
162
    def __init__(self, *, client_id: Optional[str] = None, identity_config: Optional[Mapping[str, str]] = None, **kwargs): ...
163

164
class WorkloadIdentityCredential:
165
    def __init__(self, *, tenant_id: Optional[str] = None, client_id: Optional[str] = None, **kwargs): ...
166
```
167

168
[Azure Platform Credentials](./azure-platform.md)
169

170
### Developer Tool Credentials
171

172
Authenticate using existing Azure developer tool sessions including Azure CLI, Azure PowerShell, Azure Developer CLI, and Visual Studio Code.
173

174
```python { .api }
175
class AzureCliCredential:
176
    def __init__(self, *, process_timeout: int = 10, **kwargs): ...
177

178
class AzureDeveloperCliCredential:
179
    def __init__(self, *, process_timeout: int = 10, **kwargs): ...
180

181
class AzurePowerShellCredential:
182
    def __init__(self, *, process_timeout: int = 10, **kwargs): ...
183
```
184

185
[Developer Tool Credentials](./developer.md)
186

187
### Advanced Features
188

189
Advanced authentication features including token caching, authentication records, exception handling, and utility functions.
190

191
```python { .api }
192
class AuthenticationRecord:
193
    def __init__(self, tenant_id: str, client_id: str, authority: str, home_account_id: str, username: str): ...
194

195
class TokenCachePersistenceOptions:
196
    def __init__(self, *, allow_unencrypted_storage: bool = False, name: str = "msal.cache", **kwargs): ...
197
```
198

199
[Advanced Features](./advanced.md)
200

201
### Async Support
202

203
Asynchronous versions of all credential classes for use with asyncio-based applications and Azure SDK async clients.
204

205
```python { .api }
206
# All credential classes available in azure.identity.aio module
207
from azure.identity.aio import DefaultAzureCredential, ClientSecretCredential
208
```
209

210
[Async Support](./async.md)
211

212
## Shared Types
213

214
### TokenCredential Protocol
215

216
```python { .api }
217
from abc import ABC, abstractmethod
218
from typing import Any, Optional, Union
219
from azure.core.credentials import AccessToken
220

221
class TokenCredential(ABC):
222
    @abstractmethod
223
    def get_token(self, *scopes: str, claims: Optional[str] = None, tenant_id: Optional[str] = None, **kwargs: Any) -> AccessToken:
224
        """
225
        Request an access token for the specified scopes.
226
        
227
        Args:
228
            *scopes: Desired scopes for the access token
229
            claims: Additional claims required in the token
230
            tenant_id: Optional tenant ID override
231
            **kwargs: Additional keyword arguments
232
            
233
        Returns:
234
            AccessToken: The access token with expiration information
235
        """
236

237
    def get_token_info(self, *scopes: str, options: Optional[dict] = None) -> dict:
238
        """
239
        Request an access token for the specified scopes with additional information.
240
        
241
        Args:
242
            *scopes: Desired scopes for the access token  
243
            options: Additional options for token acquisition
244
            
245
        Returns:
246
            dict: Token information including access token and metadata
247
        """
248
```
249

250
### AccessToken
251

252
```python { .api }
253
from azure.core.credentials import AccessToken
254

255
class AccessToken:
256
    def __init__(self, token: str, expires_on: int):
257
        """
258
        Represents an access token with expiration information.
259
        
260
        Args:
261
            token: The access token string
262
            expires_on: Token expiration time as seconds since epoch
263
        """
264
        self.token = token
265
        self.expires_on = expires_on
266
```
267

268
### Common Parameter Types
269

270
```python { .api }
271
from typing import List, Optional, Mapping, Callable, Iterable
272

273
# Authority hosts for different Azure clouds
274
AzureAuthorityHost = str  # login.microsoftonline.com, login.chinacloudapi.cn, etc.
275

276
# Tenant identifier
277
TenantId = str  
278

279
# Client application identifier  
280
ClientId = str
281

282
# Cache persistence configuration
283
CachePersistenceOptions = Optional[object]  # TokenCachePersistenceOptions instance
284

285
# Additional tenant allowlist
286
AdditionallyAllowedTenants = List[str]
287

288
# Authentication record for cached authentication
289
AuthRecord = Optional[object]  # AuthenticationRecord instance
290
```