0
# ARM Policies
1

2
Specialized HTTP pipeline policies for Azure Resource Manager operations. These policies provide ARM-specific functionality including automatic resource provider registration, authentication challenge handling, and enhanced logging with ARM-specific headers.
3

4
## Capabilities
5

6
### ARMAutoResourceProviderRegistrationPolicy
7

8
Automatically registers unregistered Azure resource providers when encountering 409 errors with `MissingSubscriptionRegistration`. This policy intercepts failed requests and performs the necessary registration steps transparently.
9

10
```python { .api }
11
class ARMAutoResourceProviderRegistrationPolicy(HTTPPolicy[HTTPRequestType, HTTPResponseType]):
12
    """Auto register an ARM resource provider if not done yet."""
13
    
14
    def send(self, request: PipelineRequest[HTTPRequestType]) -> PipelineResponse[HTTPRequestType, HTTPResponseType]: ...
15
```
16

17
#### How it Works
18

19
1. Monitors HTTP responses for 409 status codes
20
2. Extracts resource provider name from `MissingSubscriptionRegistration` errors
21
3. Automatically registers the resource provider via ARM API
22
4. Polls registration status until complete
23
5. Retries the original request with a new client request ID
24

25
#### Usage Example
26

27
```python
28
from azure.mgmt.core.policies import ARMAutoResourceProviderRegistrationPolicy
29
from azure.core.pipeline import Pipeline
30

31
# Policy is automatically included in ARMPipelineClient
32
# Can also be used manually in custom pipelines
33
policy = ARMAutoResourceProviderRegistrationPolicy()
34
```
35

36
### AsyncARMAutoResourceProviderRegistrationPolicy
37

38
Asynchronous version of the resource provider registration policy with the same functionality but using async/await patterns.
39

40
```python { .api }
41
class AsyncARMAutoResourceProviderRegistrationPolicy(AsyncHTTPPolicy[HTTPRequestType, AsyncHTTPResponseType]):
42
    """Auto register an ARM resource provider if not done yet."""
43
    
44
    async def send(self, request: PipelineRequest[HTTPRequestType]) -> PipelineResponse[HTTPRequestType, AsyncHTTPResponseType]: ...
45
```
46

47
### ARMChallengeAuthenticationPolicy
48

49
Bearer token authentication policy with built-in support for Continuous Access Evaluation (CAE) challenges. Handles ARM-specific authentication patterns and challenge responses.
50

51
```python { .api }
52
class ARMChallengeAuthenticationPolicy(BearerTokenCredentialPolicy):
53
    """Adds a bearer token Authorization header to requests.
54

55
    This policy internally handles Continuous Access Evaluation (CAE) challenges. When it can't complete a challenge,
56
    it will return the 401 (unauthorized) response from ARM.
57
    """
58
```
59

60
#### Usage Example
61

62
```python
63
from azure.mgmt.core.policies import ARMChallengeAuthenticationPolicy
64
from azure.core.credentials import DefaultAzureCredential
65

66
credential = DefaultAzureCredential()
67
policy = ARMChallengeAuthenticationPolicy(
68
    credential=credential,
69
    scopes=["https://management.azure.com/.default"]
70
)
71
```
72

73
### AsyncARMChallengeAuthenticationPolicy
74

75
Asynchronous version of the ARM challenge authentication policy.
76

77
```python { .api }
78
class AsyncARMChallengeAuthenticationPolicy(AsyncBearerTokenCredentialPolicy):
79
    """Adds a bearer token Authorization header to requests.
80

81
    This policy internally handles Continuous Access Evaluation (CAE) challenges. When it can't complete a challenge,
82
    it will return the 401 (unauthorized) response from ARM.
83
    """
84
```
85

86
### AuxiliaryAuthenticationPolicy
87

88
Adds auxiliary authorization tokens to requests via the `x-ms-authorization-auxiliary` header. Used for scenarios requiring additional authentication tokens alongside the primary bearer token.
89

90
```python { .api }
91
class AuxiliaryAuthenticationPolicy(SansIOHTTPPolicy[HTTPRequestType, HTTPResponseType]):
92
    """Adds auxiliary authorization token header to requests.
93

94
    :param auxiliary_credentials: auxiliary credential for authorizing requests
95
    :type auxiliary_credentials: Sequence[TokenCredential]
96
    :param str scopes: required authentication scopes
97
    """
98
    
99
    def __init__(self, auxiliary_credentials: Sequence[TokenCredential], *scopes: str, **kwargs: Any) -> None: ...
100
    def on_request(self, request: PipelineRequest[HTTPRequestType]) -> None: ...
101
```
102

103
#### Usage Example
104

105
```python
106
from azure.mgmt.core.policies import AuxiliaryAuthenticationPolicy
107
from azure.core.credentials import DefaultAzureCredential
108

109
# Create auxiliary credentials
110
aux_credentials = [DefaultAzureCredential()]
111

112
policy = AuxiliaryAuthenticationPolicy(
113
    auxiliary_credentials=aux_credentials,
114
    "https://management.azure.com/.default"
115
)
116
```
117

118
### AsyncAuxiliaryAuthenticationPolicy
119

120
Asynchronous version of the auxiliary authentication policy.
121

122
```python { .api }
123
class AsyncAuxiliaryAuthenticationPolicy(AsyncHTTPPolicy[HTTPRequestType, AsyncHTTPResponseType]):
124
    """Asynchronous auxiliary authentication policy."""
125
    
126
    def __init__(self, auxiliary_credentials: Sequence[AsyncTokenCredential], *scopes: str, **kwargs: Any) -> None: ...
127
    async def on_request(self, request: PipelineRequest[HTTPRequestType]) -> None: ...
128
    def on_response(self, request: PipelineRequest[HTTPRequestType], response: PipelineResponse[HTTPRequestType, AsyncHTTPResponseType]) -> Optional[Awaitable[None]]: ...
129
    def on_exception(self, request: PipelineRequest[HTTPRequestType]) -> None: ...
130
    async def send(self, request: PipelineRequest[HTTPRequestType]) -> PipelineResponse[HTTPRequestType, AsyncHTTPResponseType]: ...
131
```
132

133
### ARMHttpLoggingPolicy
134

135
Enhanced HTTP logging policy that includes ARM-specific headers in the safe headers allowlist. Enables logging of rate limiting headers and other ARM-specific response metadata.
136

137
```python { .api }
138
class ARMHttpLoggingPolicy(HttpLoggingPolicy):
139
    """HttpLoggingPolicy with ARM specific safe headers for loggers."""
140
    
141
    DEFAULT_HEADERS_ALLOWLIST = HttpLoggingPolicy.DEFAULT_HEADERS_ALLOWLIST | {
142
        "x-ms-ratelimit-remaining-subscription-reads",
143
        "x-ms-ratelimit-remaining-subscription-writes", 
144
        "x-ms-ratelimit-remaining-tenant-reads",
145
        "x-ms-ratelimit-remaining-tenant-writes",
146
        "x-ms-ratelimit-remaining-subscription-resource-requests",
147
        "x-ms-ratelimit-remaining-subscription-resource-entities-read",
148
        "x-ms-ratelimit-remaining-tenant-resource-requests",
149
        "x-ms-ratelimit-remaining-tenant-resource-entities-read",
150
        "x-ms-ratelimit-remaining-resource",
151
        "x-ms-request-charge"
152
    }
153
```
154

155
#### Usage Example
156

157
```python
158
from azure.mgmt.core.policies import ARMHttpLoggingPolicy
159

160
# Policy is automatically used in ARMPipelineClient
161
# Can also be configured manually
162
logging_policy = ARMHttpLoggingPolicy(
163
    logger=None,  # Uses default logger
164
    log_request_body=True,
165
    log_response_body=True
166
)
167
```
168

169
## Key Features
170

171
### HTTPS Enforcement
172

173
All authentication policies enforce HTTPS for security:
174
- Throws `ServiceRequestError` for non-HTTPS URLs when `enforce_https=True` (default)
175
- Can be disabled by setting `enforce_https=False` in request options
176

177
### Token Management
178

179
Authentication policies handle token lifecycle:
180
- Automatic token refresh when tokens expire (300 second buffer)
181
- Support for multiple auxiliary tokens
182
- Integration with Azure Core credential types
183

184
### Error Handling
185

186
- Resource provider registration policy handles and logs registration failures
187
- Authentication policies return appropriate error responses when challenges cannot be completed
188
- All policies maintain error context for debugging
189

190
## Types
191

192
```python { .api }
193
HTTPRequestType = Union[LegacyHttpRequest, HttpRequest]
194
HTTPResponseType = Union[LegacyHttpResponse, HttpResponse]
195
AsyncHTTPResponseType = Union[LegacyAsyncHttpResponse, AsyncHttpResponse]
196
AllHttpResponseType = Union[LegacyHttpResponse, HttpResponse, LegacyAsyncHttpResponse, AsyncHttpResponse]
197
TokenCredentialType = TypeVar("TokenCredentialType", bound=Union[TokenCredential, AsyncTokenCredential])
198
```