Correct AuthenticationPolicy contract for 2026-01-01

[baoqihuang0326]

Summary

Follow-up to #45764 that aligns the 2026-01-01 AuthenticationPolicy contract with the implemented Network RP service behavior. 2026-01-01 is unreleased — it exists only on the release-microsoft-network-2026-01-01 branch and has no counterpart on main — so these corrections land before the version ships rather than changing a published contract.

Application Gateway authentication bindings

• Move the authentication bindings to the attachment points the service actually implements: defaultAuthConfigs on ApplicationGatewayAdvancedRoutingMap and authConfigs on ApplicationGatewayAdvancedRoutingRule.
• Remove defaultAuthConfigs from ApplicationGatewayUrlPathMap and authConfigs from ApplicationGatewayRoutingRule; those are not advanced routing attachment types and were never implemented.
• Retain authConfigs on ApplicationGatewayRequestRoutingRule.
• All bindings use maxItems: 1 because NRP supports one auth config per attachment point.
• Document that auth config names must be unique across the gateway, that a gateway can reference at most 100 distinct authentication policies, and that bindings require the Standard_v2 or WAF_v2 SKU.

AuthenticationPolicy resource

• Add the user-assigned identity envelope property used by user sign-in policies to reach their Key Vault client secret.
• Replace the tags-only AuthenticationPolicies_UpdateTags PATCH with AuthenticationPolicies_Update, backed by a resource-specific AuthenticationPolicyUpdateParameters model carrying both tags and identity. AuthenticationPolicy is a tracked resource, so ARM requires PATCH for tag updates, and the MSI onboarding guidance requires the control plane to accept identity updates on PATCH. Using a dedicated update model rather than the shared TagsObject satisfies both at the source instead of via suppression.
• Keep UserTrustProviderType extensible (modelAsString: true) with the Entra SDK constant mapped to the lowercase wire value entra.
• Document that JWT validation and user sign-in fields are mutually exclusive within a single policy.

Constraints and documentation

• Service limits: issuer 2048 characters, client secret URL 4096 characters, session cookie name 256 characters, scope item 128 characters, and scope collection 10 items.
• issuer is typed as url with an HTTPS pattern, consistent with jwksUri and clientSecret.
• sessionTimeout remains a string to match the implemented wire shape, with its accepted syntax and units documented and enforced via pattern and length.
• clientId is documented and constrained as a GUID.
• Normalize AuthenticationPolicy example locations to lowercase and align example payloads with service-tested values.

Suppressions

Net change for AuthenticationPolicy is two fewer suppressions.

• Scope the ProvisioningStateMustBeReadOnly suppression to the specific GET, PUT, and PATCH response schemas.
• Make the arm-resource-invalid-envelope-property suppression reason self-contained for the identity property.
• No PatchIdentityProperty suppression is needed, because the PATCH body accepts identity.
• Remove the TrackedResourcePatchOperation suppression, which no longer applies now that PATCH exists.
• Remove the obsolete SchemaDescriptionOrTitle suppression now that the description is emitted.

Clarifications

• The TypeSpec union member is named Entra, while its serialized wire value remains lowercase entra. This is intentional and matches the existing NRP contract.
• ApplicationGatewayAuthConfig is not renamed in this PR. The shared Azure Firewall naming question can be resolved before a Firewall binding is introduced, avoiding an unrelated change to the currently published Application Gateway model.
• Renaming AuthenticationPolicies_UpdateTags to AuthenticationPolicies_Update is safe because 2026-01-01 is unreleased, and the former name is no longer accurate now that the body is not tags-only.

Validation

• TypeSpec compilation
• OAV semantic validation for authenticationPolicy.json and applicationGateway.json
• OAV example validation for authenticationPolicy.json
• Prettier and diff checks

[github-actions]

Next Steps to Merge

✅ All automated merging requirements have been met! To get your PR merged, see aka.ms/azsdk/specreview/merge.

Comment generated by summarize-checks workflow run.

[azure-pipelines]

Azure Pipelines:
Successfully started running 9 pipeline(s).
5 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[github-actions]

API Change Check

APIView identified API level changes in this PR and created the following API reviews

Language	API Review for Package
TypeSpec	Microsoft.Network
Go	sdk/resourcemanager/network/armnetwork
JavaScript	@azure/arm-network
Java	com.azure.resourcemanager:azure-resourcemanager-network
Python	azure-mgmt-network

---

Comment generated by After APIView workflow run.

[baoqihuang0326]

Addressed in 49afe4c. UserTrustProviderType now includes the open string variant, matching OnUnauthenticatedRequest. Generated Swagger restores x-ms-enum.name: UserTrustProviderType, modelAsString: true, and the Entra SDK constant mapped to the current lowercase wire value entra. I also removed the obsolete SchemaDescriptionOrTitle suppression because the description is now emitted.

[baoqihuang0326]

Addressed in 9d1040b:

• Documented that JWT validation and user sign-in fields are mutually exclusive and cannot be combined in one policy.
• Documented that auth config names must be unique across the gateway and that a gateway can reference at most 100 distinct authentication policies.
• Scoped the ProvisioningStateMustBeReadOnly suppression to the GET 200 and PUT 200/201 response schemas.
• The PATCH body parameter naming concern is no longer applicable: this PR removes the unsupported AuthenticationPolicy PATCH operation and its example entirely.

[baoqihuang0326]

Updated in e90beb8 using the service-tested payloads:

• Added the AuthenticationPolicy user-assigned identity property used by user sign-in policies to access their Key Vault client secret.
• Updated the user sign-in create/update example with the tested eastus, identity, issuer, client ID, and client secret values.
• Added a separate JWT-validation create/update example using only JWT fields.
• Updated the Basic_v2 Application Gateway example with a user-assigned identity, HTTPS listener hostname, and the supported request-routing-rule authConfigs binding.

The advanced-routing fragment is intentionally not included because its advanced routing map/rule models are not public in this API version; adding those values to the existing URL path map/routing rule types would recreate the unsupported placement issue this PR removes.

[github-actions]

TypeSpec suppressions requiring review (testing, non-blocking)

Status: ❌ Approval required (currently under testing, review NOT enforced) — 4 suppressions

⚠️ This check is currently in testing mode and is non-blocking — it will not prevent this PR from merging. This PR adds or updates the TypeSpec suppressions listed below. Suppressions are strongly discouraged — they bypass linter rules that protect API quality and consistency. Authors should avoid adding new suppressions and prefer fixing the underlying issue; reviewers should approve only when there is a clear, compelling justification and no reasonable alternative. Review each linked rule and source location, then apply Approved-TypeSpecSuppression only if every justification is acceptable. The Status column shows ✅ once the label is applied and ❌ while approval is pending.

New suppressions (4)

Status	Rule	Source	Justification
❌	@azure-tools/typespec-azure-resource-manager/arm-no-record Don't use Record types for ARM resources.	AuthenticationPolicy.tsp#L60	Resource tags are an open string map, consistent with the tags property on the Network RP Resource base type
❌	@azure-tools/typespec-azure-resource-manager/arm-resource-invalid-envelope-property Check for invalid resource envelope properties.	AuthenticationPolicy.tsp#L48	AuthenticationPolicy requires this user-assigned identity in the resource envelope so a user sign-in policy can read its client secret from Key Vault; the property uses the standard ManagedServiceIdentity shape and is an envelope-level credential of the resource rather than a routing/authentication setting, so it cannot move under properties.
❌	@azure-tools/typespec-azure-resource-manager/arm-no-record Don't use Record types for ARM resources.	AuthenticationPolicy.tsp#L60	Resource tags are an open string map, consistent with the tags property on the Network RP Resource base type
❌	@azure-tools/typespec-azure-resource-manager/arm-resource-invalid-envelope-property Check for invalid resource envelope properties.	AuthenticationPolicy.tsp#L48	AuthenticationPolicy requires this user-assigned identity in the resource envelope so a user sign-in policy can read its client secret from Key Vault; the property uses the standard ManagedServiceIdentity shape and is an envelope-level credential of the resource rather than a routing/authentication setting, so it cannot move under properties.

For an overview of TypeSpec linting rules click here.
For a mapping from ARM lintdiff rules to corresponding TypeSpec linting rules click here.

💬 Have feedback on the TypeSpec suppression flow? Let us know.

[baoqihuang0326]

Corrected in 4909de5 based on the updated service information:

• Restored the tags-only AuthenticationPolicies_UpdateTags PATCH operation supported by the generic controller.
• Restored the source and generated PATCH examples.
• Renamed the generated body parameter to parameters using the established Network RP @@clientName pattern.
• Removed the no-PATCH waiver.
• Added PATCH 200 to the scoped ProvisioningStateMustBeReadOnly suppression.
• Documented the 256-character combined limit across all scope entries.

[baoqihuang0326]

Addressed in 502f154:

• Removed authConfigs from the Basic_v2 request and both response bodies, restoring that example to the release-branch version. The binding example is now on the Standard_v2 ApplicationGatewayCreate.json example and references the JWT validation policy.
• Added defaultAuthConfigs to ApplicationGatewayAdvancedRoutingMapPropertiesFormat and authConfigs to ApplicationGatewayAdvancedRoutingRulePropertiesFormat, both with maxItems: 1 and x-ms-identifiers: ["name"].
• Added the returned user-assigned identity, including service-populated principalId and clientId, to both AuthenticationPolicy PUT response bodies.
• Added machine-readable constraints for client ID GUID shape, HTTPS/2048-character JWKS URI, 2048-character audience, nonempty/patterned scope values, and session cookie name pattern.
• Removed the incorrect 4096-character limit from the Key Vault URL. The description now states the URL requirements and documents that the retrieved secret value is limited to 4096 characters.

The branch also incorporated the concurrent release-branch merge and PATCH identity-property suppression before this commit was pushed.

[Sandip Shahane (sandipsh)]

ARM API Review

Posting findings from the ARM API Reviewer agent (critic-verified, 3 iteration(s), converged) against commit 502f154. See inline comments for findings 1-2.

Approval labels observed: none.

[Sandip Shahane (sandipsh)]

[NEW] 🔴 Blocking [Section 2 - API Versioning] specification/network/resource-manager/Microsoft.Network/Network/Network/models.tsp - line 7991 - This moves published authentication bindings to different models in stable 2026-01-01: ApplicationGatewayUrlPathMap.defaultAuthConfigs and ApplicationGatewayRoutingRule.authConfigs are removed, while similarly named properties are added to the advanced routing map/rule models. The new properties are not wire-compatible replacements for the removed properties.

Classification reasoning: Introduced in this PR. Both removed properties are present in the PR base, including defaultAuthConfigs at base source line 7843, and absent at the current head; the advanced-model properties are newly added at current lines 7991 and 8081.

Approval context: No Versioning-Approved-* label was observed at the session SHA. If API versioning approval already covers this exact published-contract correction, apply the matching label and resolve this conversation; otherwise preserve the old properties or introduce the corrected placement in a new API version.

Suggested fix: Restore the two published properties in 2026-01-01 and add the corrected advanced-model bindings in a new API version. If changing the published stable version is unavoidable, obtain explicit versioning approval for both removals and apply the matching Versioning-Approved-* label.

[baoqihuang0326]

This one I would like to push back on, because the premise that 2026-01-01 is a published stable contract does not hold.

2026-01-01 has never shipped. It exists only on the release-microsoft-network-2026-01-01 release branch, which is the base branch of this PR. There is no stable/2026-01-01 directory on main:

$ git ls-tree --name-only origin/main specification/network/resource-manager/Microsoft.Network/Network/stable/
...
specification/network/resource-manager/Microsoft.Network/Network/stable/2025-07-01
specification/network/resource-manager/Microsoft.Network/Network/stable/2025-09-01

The latest stable version on main is 2025-09-01. ApplicationGatewayUrlPathMap.defaultAuthConfigs and ApplicationGatewayRoutingRule.authConfigs were both introduced on this same release branch by #45764 and have never been released, so removing them is not a change to a published contract and there is no client that could depend on them. Introducing the corrected placement in "a new API version" would mean shipping 2026-01-01 with bindings the service does not implement and then immediately deprecating them.

That is exactly what this follow-up PR is for: correcting the unreleased 2026-01-01 contract before it is merged to main, so that the released shape matches the implemented NRP behavior. ApplicationGatewayAdvancedRoutingMap / ApplicationGatewayAdvancedRoutingRule are the service's actual advanced routing attachment points; ApplicationGatewayUrlPathMap and ApplicationGatewayRoutingRule are not.

The "not wire-compatible replacements" observation is correct and intentional. They are not replacements, they are the correct attachment points. Please let me know if you would still like a Versioning-Approved-* label applied for tracking, but no versioning exception should be required for a version that has not been released.

[baoqihuang0326]

Addressed in ea8ce5e:

• Removed the entraJWTValidationConfigs collection and entraJWTValidationConfig rule reference from the Basic_v2 request and both response bodies. The Basic_v2 example now contains no authentication feature unsupported by that SKU.
• Updated request-routing-rule, advanced-routing-map, and advanced-routing-rule auth binding descriptions to explicitly allow only Standard_v2 and WAF_v2.
• Changed the JWKS URI and Key Vault URL patterns to ^[Hh][Tt][Tt][Pp][Ss]://, matching NRP case-insensitive URI scheme parsing.