-
Notifications
You must be signed in to change notification settings - Fork 4.1k
[ChangeSafety] Phase 1: AcquirePolicyToken Support #28711
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Draft
notyashhh
wants to merge
1
commit into
main
Choose a base branch
from
feat/change-safety
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Draft
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,74 @@ | ||
| # Azure Policy Change Safety (Preview) | ||
|
|
||
| Azure Policy Change Safety introduces *policy evaluation tokens* that must accompany certain state-changing (write) operations to Azure Resource Manager (ARM). These short‑lived, signed tokens prove that any required external validators (approvals, safety checks, etc.) have run before the change is submitted. | ||
|
|
||
| ## Status | ||
| This feature is behind a configuration flag and requires a corresponding update to the shared `azure-powershell-common` library. Until that dependency is updated, enabling the flag has no effect. | ||
|
|
||
| ## Phased Rollout | ||
| | Phase | Scope | Visible Parameter(s) | Notes | | ||
| |-------|-------|----------------------|-------| | ||
| | Phase 1 (current) | Token acquisition only | `-AcquirePolicyToken` | `-ChangeReference` is suppressed/hidden. | | ||
| | Phase 2 (planned) | Adds change reference association | `-AcquirePolicyToken`, `-ChangeReference` | `-ChangeReference` implies token acquisition. | | ||
|
|
||
| If you see references to `-ChangeReference` below, they describe future behavior (Phase 2) and are not yet active. | ||
|
|
||
| ## Enabling the Feature | ||
| ```powershell | ||
| Update-AzConfig -EnablePolicyToken $true | ||
| ``` | ||
|
|
||
| You can also disable it later: | ||
| ```powershell | ||
| Update-AzConfig -EnablePolicyToken $false | ||
| ``` | ||
|
|
||
| Environment variable override (session only): | ||
| ```powershell | ||
| $env:AZ_ENABLE_POLICY_TOKEN = "true" | ||
| ``` | ||
|
|
||
| ## Parameters (write cmdlets; conditional & phased) | ||
| | Parameter | Type | Phase | Purpose | | ||
| |----------|------|-------|---------| | ||
| | `-AcquirePolicyToken` | Switch | 1+ | Force acquisition of a change-safety policy token for the operation. | | ||
| | `-ChangeReference <string>` | String | 2 | (Planned) Associates the operation with an external change record (e.g., a ChangeState resource ID); implies token acquisition. Not yet surfaced. | | ||
|
Comment on lines
+32
to
+35
|
||
|
|
||
| Read-only (GET/list/show) cmdlets will not expose these parameters. | ||
|
|
||
| ## Example Usage (Phase 1) | ||
| ```powershell | ||
| # Acquire a token automatically for a write operation | ||
| New-AzResourceGroup -Name rg-change -Location eastus -AcquirePolicyToken | ||
| ``` | ||
|
|
||
| ### Phase 2 (Planned) Example (Not Yet Active) | ||
| ```powershell | ||
| # This will only work once Phase 2 ships | ||
| New-AzVm -Name web01 -ResourceGroupName rg-change -ChangeReference \ | ||
| "/providers/Microsoft.Change/changes/abc123/changeStates/state456" -Image UbuntuLTS -Location eastus | ||
| ``` | ||
|
|
||
| ## How It Works (Conceptual) | ||
| 1. You provide `-AcquirePolicyToken` (Phase 1) or later `-ChangeReference` (Phase 2) on a write cmdlet. | ||
| 2. The client calls `Microsoft.Authorization/acquirePolicyToken` (synchronously) with method, URI and body of the impending request plus optional change reference (Phase 2). | ||
| 3. Service returns a signed token; it is attached as `x-ms-policy-external-evaluations` header on the actual ARM call. | ||
| 4. ARM validates token; if missing or invalid and required policies exist, the request is rejected. | ||
|
|
||
| ## Troubleshooting | ||
| | Symptom | Possible Cause | Mitigation | | ||
| |--------|----------------|-----------| | ||
| | Parameters not visible | Feature flag not enabled or common library not updated | Run `Update-AzConfig -EnablePolicyToken $true` and ensure you have a version that includes the handler. | | ||
|
Comment on lines
+59
to
+61
|
||
| | Error: failed to acquire policy token | Network / permission / unsupported scope | Re-run with `-Debug`; confirm subscription context and that the operation is write. | | ||
| | ARM denies request citing policy token | Missing `-AcquirePolicyToken` / `-ChangeReference` where a policy now requires it | Re-run with one of the parameters enabled. | | ||
|
|
||
| ## Logging & Privacy | ||
| The token is sensitive and should not appear in logs. The implementation sanitizes the header value in debug traces. | ||
|
|
||
| ## Roadmap (Subject to Change) | ||
| * Support asynchronous (202 Accepted) acquisition mode | ||
| * Retry and token reuse for identical retried writes | ||
| * Warning decoration for policy-denied responses when the feature is disabled | ||
|
|
||
| --- | ||
| Feedback welcome—file an issue with `[ChangeSafety]` in the title. Please specify "Phase 1" in the issue if `-ChangeReference` is not yet available in your build. | ||
21 changes: 21 additions & 0 deletions
21
src/Accounts/Accounts.Test/UnitTest/EnablePolicyTokenConfigTest.cs
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| // ---------------------------------------------------------------------------------- | ||
| // Copyright Microsoft Corporation | ||
| // Licensed under the Apache License, Version 2.0 (the "License"); | ||
| // ---------------------------------------------------------------------------------- | ||
| using Microsoft.Azure.Commands.Common.Authentication.Config.Definitions; | ||
| using NUnit.Framework; | ||
|
|
||
| namespace Microsoft.Azure.Commands.Profile.Test.UnitTest | ||
| { | ||
| [TestFixture] | ||
| public class EnablePolicyTokenConfigTest | ||
| { | ||
| [Test] | ||
| public void Default_IsFalse_And_KeyMatches() | ||
| { | ||
| var cfg = new EnablePolicyTokenConfig(); | ||
| Assert.AreEqual(false, cfg.DefaultValue, "Default should be false for safety opt-in."); | ||
| Assert.AreEqual("EnablePolicyToken", cfg.Key, "Config key mismatch."); | ||
| } | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
38 changes: 38 additions & 0 deletions
38
src/Accounts/Authentication/Config/Definitions/EnablePolicyTokenConfig.cs
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,38 @@ | ||
| // ---------------------------------------------------------------------------------- | ||
| // | ||
| // Copyright Microsoft Corporation | ||
| // Licensed under the Apache License, Version 2.0 (the "License"); | ||
| // you may not use this file except in compliance with the License. | ||
| // You may obtain a copy of the License at | ||
| // http://www.apache.org/licenses/LICENSE-2.0 | ||
| // Unless required by applicable law or agreed to in writing, software | ||
| // distributed under the License is distributed on an "AS IS" BASIS, | ||
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| // See the License for the specific language governing permissions and | ||
| // limitations under the License. | ||
| // ---------------------------------------------------------------------------------- | ||
|
|
||
| using Microsoft.Azure.Commands.Common.Authentication.Config; | ||
| using Microsoft.Azure.PowerShell.Common.Config; | ||
| using Microsoft.Azure.Commands.Shared.Config; | ||
| using System.Collections.Generic; | ||
|
|
||
| namespace Microsoft.Azure.Commands.Common.Authentication.Config.Definitions | ||
| { | ||
| /// <summary> | ||
| /// Enables acquisition and attachment of Azure Policy Change Safety tokens for write operations | ||
| /// when the user opts in and supplies -AcquirePolicyToken or -ChangeReference parameters (implemented | ||
| /// in the shared base cmdlet in azure-powershell-common). This repository only contributes the | ||
| /// configuration surface; functionality becomes active when the updated common library is present. | ||
| /// </summary> | ||
| internal class EnablePolicyTokenConfig : TypedConfig<bool> | ||
| { | ||
| public override object DefaultValue => false; | ||
|
|
||
| public override string Key => ConfigKeys.EnablePolicyToken; | ||
|
|
||
| public override string HelpMessage => "Enables acquisition and attachment of Azure Policy change-safety tokens on write operations when -AcquirePolicyToken or -ChangeReference are specified."; | ||
|
|
||
| public override IReadOnlyCollection<AppliesTo> CanApplyTo => new[] { AppliesTo.Az }; | ||
| } | ||
| } |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The tables use a double leading pipe (||) which breaks standard Markdown table rendering; remove the extra leading pipe so each row begins with a single | to ensure proper formatting.
Copilot uses AI. Check for mistakes.