From ba240b747d51c8d88737187a6bc0eb9f2208cb3c Mon Sep 17 00:00:00 2001 From: Luana Dos Santos Date: Tue, 18 Aug 2026 10:24:26 -0300 Subject: [PATCH 1/9] W-23907611 docs: draft Policy Write documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rewrite exp-governance-policy-library-apply.adoc from a fully commented-out draft into an active topic covering the Policy Write scope (MS2026-08-R2): apply a universal policy template, and edit/delete/enable-disable native policies, plus the in-progress workflow lock and read-only out-of-scope state. Update the Policies-tab section of exp-services-view-details.adoc to note the new native-policy management actions and read-only out-of-scope policies, and cross-link to the apply/manage topic. Content is grounded in the mulesoft-omni-app UI code. Details that could not be verified in code (universal template list + per-gateway native mappings, GA feature flags, enable/disable support matrix, permission role names, and the API Instance page apply entry point) are marked with TODO(W-23907611) comments for PM confirmation before publishing. Gap analysis: Policy Write — Documentation Gap Report (2026-08-18). Co-Authored-By: Claude Opus 4.8 --- .../exp-governance-policy-library-apply.adoc | 184 +++++++++--------- .../ROOT/pages/exp-services-view-details.adoc | 8 +- 2 files changed, 101 insertions(+), 91 deletions(-) diff --git a/modules/ROOT/pages/exp-governance-policy-library-apply.adoc b/modules/ROOT/pages/exp-governance-policy-library-apply.adoc index 9c7017556..3962c947a 100644 --- a/modules/ROOT/pages/exp-governance-policy-library-apply.adoc +++ b/modules/ROOT/pages/exp-governance-policy-library-apply.adoc @@ -1,126 +1,130 @@ -// = Browse the Policy Library -// :keywords: policy library, canonical policies, governance policies, policy catalog += Apply and Manage Policies from the Policy Library +:keywords: policy library, canonical policies, universal policies, governance policies, apply policy, edit policy, delete policy, policy catalog -// // FLAG: Jul 16 publish condition. The read/browse description below (what the Policy Library is and what users can see) is written for the Jul 16 Policy Read GA. However, the Policy Library UI is gated behind a feature flag (W_23173868_CANONICAL_POLICIES_ENABLED, default off) and is not called out as a Jul 16 deliverable in the PRD. Confirm with the PM that the Policy Library is enabled in browse mode for Jul 16 before publishing this topic. The policy-application wizard is Policy Write (GA Aug 13) and is commented out at the end of this file. +// DRAFT: Policy Write (MS2026-08-R2 / Dreamforce). Tracked in W-23907611. +// This topic was previously a commented-out draft for the Policy Read GA. It has been +// rewritten for the Policy Write scope. Sections contain TODO(W-23907611) markers where a +// detail could not be grounded in code and must be confirmed with the PM before publishing. +// Blockers to resolve before removing this DRAFT banner and publishing: +// 1. Confirmed list of the universal policy templates and their per-gateway native mappings +// (APIM-owned; not enumerated in the Omni codebase). +// 2. Which feature flags are ON for GA, per gateway +// (W_23173868_CANONICAL_POLICIES_ENABLED for Kong, +// W_23308031_NONKONG_POLICIES_VIA_APIM_ENABLED for Apigee/Azure). +// 3. The enable/disable support matrix (which gateways expose the toggle at GA). +// 4. Human-readable required permission/role names for policy write actions. +// 5. Whether applying policies from the API Instance page is enabled at GA +// (listed as out of scope for MS2026-08-R2 in the program tracker). -// The Policy Library is a catalog of predefined policies that you can browse from *Governance* > *Governance Strategies* > *Policy Library*. Use it to explore the policies available to your organization and understand what each one enforces before you govern your APIs. +Use the Policy Library to apply a universal policy template to your API instances and to manage the resulting native policies. A universal template expresses a policy once and applies it as the correct vendor-native policy on each supported gateway, so you can enforce consistent controls across MuleSoft, Google Apigee, Kong Gateway, and Azure API Management without authoring a policy per gateway. -// == Browse Policies by Category +// TODO(W-23907611): AWS API Gateway is excluded from the policy write flow for this release +// (deferred to a later release). Confirm the customer-facing framing of the AWS exclusion with the PM. -// The Policy Library displays each available policy as a card that shows the policy name, its category, and a short description of what the policy does. +== Before You Begin -// To find a policy, you can: +Before getting started, make sure you have: -// * Search for a policy by name using the search box. -// * Filter policies by category: -// + -// -- -// ** *Access and Security*: Authentication and authorization policies, including OAuth 2.0, JWT validation, IP filtering, and rate limiting. -// ** *Performance and Cost*: Policies that manage API performance and cost, such as caching, spike arrest, and request throttling. -// ** *Data Privacy and Integrity*: Policies that protect data privacy and ensure data integrity, such as PII masking, data encryption, and payload validation. -// ** *Compliance and Observability*: Policies that enable compliance tracking and observability, such as audit logging, correlation ID injection, and OpenTelemetry tracing. -// -- +* An Anypoint Platform account. +* Any of these permissions: ++ +-- +** API Governance: Governance Administrator +** API Manager: Manage Policies +-- ++ +// TODO(W-23907611): Confirm the exact permission/role names required for apply, edit, delete, +// and enable/disable. The code enforces per-action permissions (create, update, enable, +// disable, delete) fetched per instance, but exposes only permission keys, not role labels. +For more information, see xref:exp-home-start.adoc#permissions[Enhanced Experience Permissions]. -// Policies that apply to any service, including scanned and federated APIs, are marked with a *Universal* badge. +* API instances registered in the portfolio on a supported gateway. -// == See Also +[NOTE] +==== +Policy write actions respect your permissions. If you don't have permission for an action, that action is unavailable and the experience explains that the action isn't permitted. If the platform can't verify your permissions for an instance, the actions remain available and the gateway enforces authorization when you submit the request. +==== -// * xref:exp-governance-create-strategy.adoc[] -// * xref:exp-services-view-details.adoc[] -// * xref:exp-governance-govern-third-party-apis.adoc[] +== Browse the Policy Library -// // FLAG: Aug 13 release (policy write scope). Everything below documents applying policies to API instances (including third-party provider instances) through the Policy Library wizard, which is Policy Write — GA Aug 13. It is out of scope for the Jul 16 Policy Read GA. Uncomment when the Aug 13 write release is documented, and fold these sections into the topic above (add the apply use cases, permissions, and wizard steps). Note: for MuleSoft-native and Kong instances, policy application already ships, but cross-gateway apply as described here aligns with the Aug 13 milestone — confirm scope with the PM before publishing. -// //// -// == When to Use the Policy Library to Apply Policies +The Policy Library is a catalog of predefined policies that you can browse from *Governance* > *Governance Strategies* > *Policy Library*. Each policy appears with its name, category, and a short description of what it enforces. -// Use the Policy Library instead of governance strategies when you want to: +You can filter policies by category: -// * Apply a policy to a specific set of API instances without creating a governance strategy. -// * Add supplemental policies to instances that are already governed by strategies. -// * Apply policies to third-party provider services hosted on platforms such as Akamai. -// * Test policy behavior on a limited scope before a broader rollout. +* *Access & Security* +* *Performance & Cost* +* *Quality of Service* +* *Data Privacy & Integrity* +* *Compliance & Observability* -// For comprehensive, scope-driven governance across multiple services, use xref:exp-governance-create-strategy.adoc[governance strategies] instead. +// TODO(W-23907611): Confirm the shipping list of universal policy templates and the native +// policy each maps to per gateway (for example, an API key template mapping to VerifyAPIKey +// on Apigee and key-auth on Kong). This mapping is served at runtime by API Manager and is +// not defined in the Omni codebase, so it must be confirmed with the PM / API Platform team +// before it is documented as a table. Do not transcribe the mapping from the planning tracker. -// == Before You Begin +== Apply a Policy -// Before getting started, make sure you have: +. Log in and go to *Governance* > *Governance Strategies* > *Policy Library*. +. Select the policy you want to apply. +. Configure the policy parameters. Required and optional fields vary by policy type. +. Select the API instances where you want to apply the policy. +. Review the summary, then apply the policy. -// * An Anypoint Platform account. -// * Any of these permissions: -// + -// -- -// ** API Governance: Governance Administrator -// ** API Manager: Manage Policies -// -- -// + -// For more information, see xref:exp-home-start.adoc#permissions[Enhanced Experience Permissions]. +// TODO(W-23907611): Confirm the exact wizard step labels and the primary action button label +// against the shipped UI before publishing (the apply flow is driven by the governance policy +// wizard). Applying policies directly from an API Instance page is listed as out of scope for +// MS2026-08-R2 — confirm whether that entry point is available at GA before documenting it. -// * API instances registered in the portfolio. For third-party provider services, make sure that the xref:exp-governance-setup-third-party-providers.adoc[provider connection] is established. +When you apply a policy, the platform validates it against your governance configuration and then creates the corresponding native policy on each selected instance's gateway. -// == Open the Policy Library Wizard +[NOTE] +==== +While a policy operation is in progress on an instance, applying policies to that instance is paused and policy actions are unavailable until the operation completes or fails. This prevents conflicting changes while the vendor-native apply workflow runs. +==== -// . Log in and go to *Governance* > *Governance Strategies* > *Policy Library*. -// . Select *Apply Policy* to start the policy application wizard. +== Manage Applied Policies -// The wizard guides you through policy selection, configuration, instance selection, and review. +Manage the native policies on an instance from the *Policies* tab of the instance detail page. The available actions depend on the gateway and on your permissions. For where to find this tab, see xref:exp-services-view-details.adoc[]. -// == Select Policy +=== Edit a Policy -// Browse the available policies and filter by category, then select the policy you want to apply and select *Next*. +For Apigee and Azure API Management native policies that originate from a universal template, select *Edit Configuration* to change the policy's settings. -// == Configure Policy +Editing uses a two-tier experience: -// Enter configuration parameters for your selected policy. Required and optional fields vary by policy type. +* If the policy's configuration schema is available, the policy opens in an editable form. +* If no schema is available, the policy opens in a read-only view of its current configuration. -// Common configuration fields include: +Your changes are saved back to the vendor gateway. -// * *Policy Name*: A descriptive name for this policy application. -// * *Enforcement Mode*: Whether to enforce the policy or monitor violations only (if supported). -// * *Parameters*: Policy-specific settings such as rate limits, authentication providers, or transformation rules. +[NOTE] +==== +Editing Kong gateway-scope policies is not supported. +==== -// Configure the policy parameters according to your requirements and select *Next*. +=== Delete a Policy -// == Select Instances +To remove a native policy from an instance, select the remove action for the policy. A confirmation dialog appears before the policy is removed. Removing a policy detaches it from the instance, and traffic that the policy was filtering is no longer enforced. After you confirm, the policy no longer appears in the instance's policy list. -// Choose the API instances where you want to apply the policy: +// TODO(W-23907611): Confirm the exact remove action/menu label and confirmation button label +// against the shipped UI before publishing. -// . Review the list of available API instances. The list includes instances from Anypoint Platform and connected third-party providers. -// . Use filters to narrow the list by: -// + -// -- -// ** *Provider*: Filter by specific providers (such as Akamai) or Anypoint Platform gateways. -// ** *Service Type*: Filter by service type (such as REST API or GraphQL). -// ** *Tags*: Filter by tags assigned to services. -// -- +=== Enable or Disable a Policy -// . Select one or more instances where you want to apply the policy. -// . Select *Next*. +On gateways that support it, you can enable or disable a policy without removing it. The state change is reflected in the policy list. On gateways that don't support enabling and disabling, the toggle is unavailable. -// == Review and Apply +// TODO(W-23907611): Confirm the enable/disable support matrix (which gateways expose the +// toggle at GA) before publishing. Do not list specific gateways as supported or unsupported +// until engineering confirms the shipping behavior. -// Review the policy application summary: +=== View Policies Outside Your Scope -// * *Policy*: The selected policy and its configuration. -// * *Instances*: The list of instances where the policy is applied. -// * *Expected Outcome*: A summary of what happens when you apply the policy. +Policies that are outside your instance's scope appear in a read-only state. For these policies, edit, delete, and enable/disable actions are not available. -// *Read-Only Mode*: If any selected instances belong to a provider connection with read-only credentials, those instances receive the policy in monitoring mode only. To enable write access, xref:exp-governance-setup-third-party-providers.adoc#update-credentials[update provider credentials]. +== See Also -// Select *Apply* to apply the policy to the selected instances. - -// == Verify Policy Application - -// After applying the policy: - -// . Go to *Portfolio* > *APIs* and open the affected API instance. -// . Review the *Applied Policies* tab to verify the policy appears in the list. -// . Check the *Policy Application Status*: -// + -// -- -// ** *Enabled*: The policy is actively enforced on the gateway. -// ** *Read-Only*: The policy is applied in monitoring mode only (typically due to read-only provider credentials). -// -- - -// If the policy is in read-only mode and you want enforcement, xref:exp-governance-setup-third-party-providers.adoc#update-credentials[update provider credentials] to grant write access. -// //// +* xref:exp-governance-create-strategy.adoc[] +* xref:exp-governance-work-with-strategies.adoc[] +* xref:exp-services-view-details.adoc[] +* xref:exp-governance-govern-third-party-apis.adoc[] diff --git a/modules/ROOT/pages/exp-services-view-details.adoc b/modules/ROOT/pages/exp-services-view-details.adoc index c84043a2f..cf3d8ae88 100644 --- a/modules/ROOT/pages/exp-services-view-details.adoc +++ b/modules/ROOT/pages/exp-services-view-details.adoc @@ -41,7 +41,7 @@ tab can differ by service type and release. For end-to-end portfolio tasks that |Yes |Yes |Yes |Each Model Proxy is exactly one instance so there is no *Instances* tab. |No |*Policies* -|Governance policies attached to the service or its instances (access, data, performance, compliance, and related domains your organization uses). For APIs discovered by scanners, this tab shows read policies from Amazon API Gateway, Google Apigee, Azure API Management, and Kong Gateway. If the instance uses a Kong gateway, the listed policies are gateway-level policies (plugins). Other service-level policies (plugins) can also apply. +|Governance policies attached to the service or its instances (access, data, performance, compliance, and related domains your organization uses). For APIs discovered by scanners, this tab shows read policies from Amazon API Gateway, Google Apigee, Azure API Management, and Kong Gateway. If the instance uses a Kong gateway, the listed policies are gateway-level policies (plugins). Other service-level policies (plugins) can also apply. On supported gateways, you can also manage native policies from this tab. See xref:exp-governance-policy-library-apply.adoc[]. |Yes |Yes |Yes |Yes |No |*Monitoring* @@ -77,6 +77,12 @@ If a provider scanner has policy-read scopes configured, the *Policies* tab show Policy visibility depends on the last successful scanner run, not on a live provider query. If required provider scopes or roles are missing, policy results can be incomplete or unavailable. Policy fields such as status, apply level, and detail can vary by provider. If expected policies are missing, check scanner run status and history in *Providers*. +== Manage Native Policies + +On supported gateways, the *Policies* tab also lets you manage the native policies applied to an instance. Depending on the gateway and your permissions, you can edit, delete, or enable and disable a policy directly from this tab. Policies that are outside your instance's scope appear in a read-only state, without edit, delete, or enable/disable actions. + +For the full apply and management workflow, see xref:exp-governance-policy-library-apply.adoc[]. + == See Also * xref:exp-overview.adoc[] From 46c5e56779f1bd10b663cdfda8e34f1b5cf8d133 Mon Sep 17 00:00:00 2001 From: jenny hajee Date: Tue, 18 Aug 2026 17:10:37 -0500 Subject: [PATCH 2/9] Jenny added updates for the write policies for API gateway scanners --- modules/ROOT/pages/exp-instances-add.adoc | 10 +++- modules/ROOT/pages/exp-overview.adoc | 4 +- modules/ROOT/pages/exp-providers-manage.adoc | 2 + .../exp-scanners-add-from-providers.adoc | 6 ++ modules/ROOT/pages/exp-scanners-manage.adoc | 4 ++ .../exp-scanners-prerequisites-reference.adoc | 60 +++++++++++++++++++ .../ROOT/pages/exp-scanners-view-details.adoc | 5 ++ 7 files changed, 88 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/exp-instances-add.adoc b/modules/ROOT/pages/exp-instances-add.adoc index 8ee7f08a3..b8a3f2986 100644 --- a/modules/ROOT/pages/exp-instances-add.adoc +++ b/modules/ROOT/pages/exp-instances-add.adoc @@ -54,7 +54,15 @@ Field names, required metadata, and available gateway or runtime options depend After creating or updating an instance, you can continue managing the service through related areas of the experience. -* Use the *Policies* tab to review or apply policies to the instance. If the instance uses a Kong gateway, applying a policy targets the gateway level and protects all services in that gateway. +* Use the *Policies* tab to review or apply policies to the instance. ++ +-- +For a managed instance on an Omni Gateway, policies are enforced through the Omni Gateway. + +For an instance discovered on a third-party API gateway (Amazon API Gateway, Azure API Management, Google Apigee, or Kong Gateway), the *Policies* tab applies policies directly to the provider through policy write, with no Omni Gateway in the request path. This requires a scanner configured with write credentials for the provider. If the scanner has read-only credentials, the instance appears as *Read-Only* and policy actions are unavailable. For write scopes and requirements, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. + +If the instance uses a Kong gateway, applying a policy targets the gateway level and protects all services in that gateway. +-- * Use the *Monitoring* tab to review metrics and runtime performance when monitoring is available. * Coordinate with platform owners if DNS, certificates, or upstream routing changes must happen outside the product. diff --git a/modules/ROOT/pages/exp-overview.adoc b/modules/ROOT/pages/exp-overview.adoc index a27692f30..f59538d49 100644 --- a/modules/ROOT/pages/exp-overview.adoc +++ b/modules/ROOT/pages/exp-overview.adoc @@ -11,7 +11,7 @@ The enhanced MuleSoft experience supports the full lifecycle of AI-connected int Entity Management:: Register and manage agents, REST and GraphQL APIs, MCP servers, Model proxies, and gateways, including Anypoint Omni Gateway, external gateways, and unmanaged gateways. Each type has a dedicated catalog under *Portfolio*. -Governance and Compliance:: Define and apply policies across domains such as access and security, performance and cost, data privacy and integrity, and compliance and observability. Conformance reporting summarizes rule violations and severity so you can close gaps systematically. +Governance and Compliance:: Define and apply policies across domains such as access and security, performance and cost, data privacy and integrity, and compliance and observability. For connected third-party API gateways (Amazon API Gateway, Azure API Management, Google Apigee, and Kong Gateway), apply, enable, disable, and delete policies directly from Anypoint through policy write, with no Omni Gateway in the request path. Conformance reporting summarizes rule violations and severity so you can close gaps systematically. Cost and Performance Optimization:: Monitor token usage, per-instance signals, and daily cost where the product exposes them. Apply governance strategies and related controls, such as tool mapping and tool sanitization, to reduce spend and risk where the experience supports them. @@ -38,7 +38,7 @@ Under *Portfolio*, open *Agents*, *MCP Servers*, *Model Proxies*, *APIs*, or *Ga In *Portfolio*, open a service detail page from *Agents*, *MCP Servers*, *Model Proxies*, or *APIs*, then open the *Instances* tab to create managed or unmanaged deployments that match your needs. Managed instances on Omni Gateway give stronger governance and monitoring when the new experience exposes them. *Gateways* don't include an *Instances* tab on their detail page. For instance workflows, see xref:exp-instances-add.adoc[]. . Configure policies. + -On a service detail page in *Portfolio*, open the *Policies* tab for the service or one of its instances to apply governance policies that match access control, data privacy, performance, and compliance goals. Use top-level *Governance* for gateway-wide policy work, organization strategies, and cost tools. For governance policy workflows, see xref:exp-governance-work-with-strategies.adoc[]. +On a service detail page in *Portfolio*, open the *Policies* tab for the service or one of its instances to apply governance policies that match access control, data privacy, performance, and compliance goals. For APIs discovered from third-party gateways, applying policies requires a scanner configured with write credentials for the provider; see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. Use top-level *Governance* for gateway-wide policy work, organization strategies, and cost tools. For governance policy workflows, see xref:exp-governance-work-with-strategies.adoc[]. . Review compliance. + In *Portfolio*, open a service detail page from *Agents*, *APIs*, or *MCP Servers*, then open the *Conformance Report* tab to review scores, violations, and warnings and address the findings your governance team prioritizes. For gateways, use top-level *Governance* for the same compliance story at the scope the experience supports. For service-level tabs and conformance context, see xref:exp-services-view-details.adoc[]. diff --git a/modules/ROOT/pages/exp-providers-manage.adoc b/modules/ROOT/pages/exp-providers-manage.adoc index a685cc892..cb632603b 100644 --- a/modules/ROOT/pages/exp-providers-manage.adoc +++ b/modules/ROOT/pages/exp-providers-manage.adoc @@ -100,6 +100,8 @@ When scanning Kong, the enhanced experience discovers gateway-level plugin infor *Akamai API Security* is available only when your administrator has enabled the feature for your organization. When enabled, it appears in the *Not Connected* section of the Providers sidebar. ==== +Of these providers, the API gateway providers Amazon (API Gateway), Google (Apigee), Kong, and Microsoft (Azure API Management) support policy write. APIs discovered from a scanner that has only read credentials appear as *Read-Only*, and policy actions are unavailable until you add write credentials to the scanner. For provider-specific read and write scopes, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. + The specific providers available depend on your organization's enabled products and enhanced experience configuration. == See Also diff --git a/modules/ROOT/pages/exp-scanners-add-from-providers.adoc b/modules/ROOT/pages/exp-scanners-add-from-providers.adoc index 1fedbdaef..d38570bcc 100644 --- a/modules/ROOT/pages/exp-scanners-add-from-providers.adoc +++ b/modules/ROOT/pages/exp-scanners-add-from-providers.adoc @@ -38,6 +38,10 @@ Scheduled or on-demand scans pick up releases and configuration drift according + When a scanner is enabled, it can discover and read policies from API configurations. This allows the system to enforce policies on the discovered services. This is especially useful for API-based policies, such as web application firewall (WAF) policies. +* Policy write ++ +For API gateway providers that support policy write (Amazon API Gateway, Azure API Management, Google Apigee, and Kong Gateway), a scanner configured with write credentials lets you apply, enable, disable, and delete policies on discovered APIs directly from Anypoint. For write scopes and requirements, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. + == Workflow Entry Points for Adding a Scanner The system exposes the same underlying connect-and-configure wizard from more than one place; the label depends on context: @@ -82,6 +86,8 @@ If some environments show no policy binding, select *Check again* to retry the p Regardless of entry point, adding a scanner establishes trust and scope. You specify which provider platform to reach, how the system authenticates, and how you validate connectivity. You also name and schedule the scanner—or configure another trigger—so discovery runs on the cadence your team expects. Saving the configuration activates the scanner for the catalogs and features your administrator enabled. +For API gateway providers that support policy write, supply credentials that include the provider's write scope during setup. Discovery credentials alone enable read-only access: the scanner discovers and reads policies, but the affected APIs appear as *Read-Only* and policy actions are unavailable until you add write credentials. For provider-specific read and write scopes, see xref:exp-scanners-prerequisites-reference.adoc[]. + == After the Scanner Runs When the scanner is active, it applies discovery results according to its settings and your organization's rules. You review outcomes on the *Providers* page and on scanner detail pages, and you manage discovered services from the relevant *Portfolio* catalogs. diff --git a/modules/ROOT/pages/exp-scanners-manage.adoc b/modules/ROOT/pages/exp-scanners-manage.adoc index 7398c5f19..f1e6991da 100644 --- a/modules/ROOT/pages/exp-scanners-manage.adoc +++ b/modules/ROOT/pages/exp-scanners-manage.adoc @@ -20,11 +20,15 @@ Re-enable scheduled scanning after a pause. * *Scanner Settings* + Change names, descriptions, credentials, provider scope, or scan-related settings your product exposes, then save, so future runs use the new definition. ++ +For API gateway providers that support policy write, adding write credentials to a read-only scanner enables policy write (apply, enable, disable, and delete) on the scanner's discovered APIs. Read and write credentials are configured separately. For provider-specific write scopes, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. * *Delete Scanner* + Remove the scanner from *Providers* when the provider link is no longer authorized or useful. Consider the impact on discovered services in *Portfolio* and on dependent teams before you delete the scanner. + NOTE: When you delete an Akamai API Security scanner, the system attempts to remove the Akamai correlation policy from the scanner's environments. If the removal fails, the correlation policy may remain applied; check *Automated Policies* to verify. Discovered services remain in your portfolio regardless. ++ +NOTE: Deleting a write-enabled API gateway scanner doesn't remove policies that were previously applied to the provider's APIs through policy write. Those policies remain active on the gateway. Anypoint stops tracking them, and you lose the ability to manage them from Anypoint until you reconnect a scanner with write credentials. == See Also diff --git a/modules/ROOT/pages/exp-scanners-prerequisites-reference.adoc b/modules/ROOT/pages/exp-scanners-prerequisites-reference.adoc index f09f75f74..bbc17f556 100644 --- a/modules/ROOT/pages/exp-scanners-prerequisites-reference.adoc +++ b/modules/ROOT/pages/exp-scanners-prerequisites-reference.adoc @@ -3,6 +3,8 @@ Scanner prerequisites by provider help you confirm required roles, credentials, and permissions before creating a scanner. Use this reference to prevent connection test failures and incomplete discovery by validating provider-specific access in advance. Each scanner also requires Exchange Administrator permission and the correct business group context. +For API gateway providers that support policy write, discovery credentials aren't enough to apply policies. Supply credentials with the write scope for the gateway, and review the additional write prerequisites in xref:_policy_write_prerequisites[]. Write scopes are noted in the matrix as *Write scope (policy apply)*. + == Before You Begin Before adding any scanner, make sure you have: @@ -141,6 +143,12 @@ a| * *Resource scope (REST APIs):* `arn:aws:apigateway:{region}::/restapis/*` * *Resource scope (HTTP APIs):* `arn:aws:apigateway:{region}::/apis/*` +*Write scope (policy apply):* IAM write permissions for API Gateway, in addition to the read permissions: + +* `apigateway:PUT` +* `apigateway:POST` +* `apigateway:DELETE` + [NOTE] For web application firewall (WAF) policies, the scanner also uses `software.amazon.awssdk:wafv2` and `software.amazon.awssdk:route53`. @@ -154,6 +162,8 @@ a| * *Read role scope:* API Management Service Reader at the API Management resource or resource group scope * *Read OAuth scope:* `https://management.azure.com/.default` +*Write scope (policy apply):* API Management Service Contributor role (ARM) at the API Management resource or resource group scope + | Google Apigee | API a| @@ -163,6 +173,8 @@ a| * *Read role:* Service account with the Viewer role, or an Apigee permission role with equivalent read access +*Write scope (policy apply):* API Admin role (Management API), or an Apigee permission role with equivalent write access + | Kong Gateway | API a| @@ -172,6 +184,8 @@ a| * *Apply read scope:* Admin API read permission required to read policy in target environments +*Write scope (policy apply):* Admin API write permission required to apply, enable, disable, or delete policy in target environments + | Akamai Security | API Security a| @@ -216,6 +230,52 @@ a| |=== +== Policy Write Prerequisites + +Policy write lets you apply, enable, disable, and delete policies on connected third-party gateway APIs directly from Anypoint, with no Anypoint gateway in the request path. Policy write is available for API gateway providers only: Amazon API Gateway, Azure API Management, Google Apigee, and Kong Gateway. Agent, API Security, and MCP scanners don't support policy write. + +Before you can write policies, confirm these prerequisites in addition to the discovery prerequisites in the matrix: + +* *Write credentials:* Provide credentials that have the write scope for the target gateway. Configure read and write credentials separately in the scanner. Read-only credentials allow discovery only. +* *Write scope:* The write scope covers enabling, disabling, and deleting existing vendor-native policies, and creating and editing universal (canonical) policies, at both the instance and service scope. Creating and editing native vendor policies isn't supported. +* *Provider write permissions:* Grant the provider-specific *Write scope (policy apply)* listed for each API gateway provider in the xref:_scanner_prerequisite_matrix[]. + +The following table summarizes the read and write scopes for each API gateway provider that supports policy write. + +[cols="1,1,1",options="header"] +|=== +| Provider +| Read Scope +| Write Scope + +| Amazon API Gateway +| `apigateway:GET` +| `apigateway:PUT`, `apigateway:POST`, `apigateway:DELETE` + +| Azure API Management +| Reader role (ARM) +| API Management Service Contributor role (ARM) + +| Google Apigee +| Viewer role (Management API) +| API Admin role (Management API) + +| Kong Gateway +| Admin API read +| Admin API write +|=== + +=== Read-Only APIs + +When a scanner has only read credentials for a gateway, its API instances appear as *Read-Only* and policy actions are unavailable. To enable policy write, update the scanner with write credentials by using the credential update link on the API instance. + +=== Tracked Applies and Audit Trail + +Every policy write is tracked and records an applied or failed state alongside the scanner-read configuration. Anypoint also logs each write as compliance evidence, including who made the change, the policy, the target, the vendor, the timestamp, and the result. + +[NOTE] +Anypoint doesn't manage vendor policy lifecycle, versioning, or CI/CD. + == See Also * xref:exp-scanners-add-from-providers.adoc[] diff --git a/modules/ROOT/pages/exp-scanners-view-details.adoc b/modules/ROOT/pages/exp-scanners-view-details.adoc index e1f3b1595..b699c75b5 100644 --- a/modules/ROOT/pages/exp-scanners-view-details.adoc +++ b/modules/ROOT/pages/exp-scanners-view-details.adoc @@ -39,6 +39,8 @@ For import scanners, this tab reflects discovered services imported by scan runs Use *Settings* to review and update scanner configuration values, such as provider connection details, run schedule, and scanner metadata. You can also delete the scanner from this tab. +For API gateway providers that support policy write, the scanner stores read and write credentials separately. Read credentials enable discovery and policy read; write credentials enable policy write (apply, enable, disable, and delete). Use *Settings* to add or update write credentials—for example, to change an API scanner from read-only to write-enabled. For provider-specific read and write scopes, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. + == Tab Content by Scanner Type Import scanner:: @@ -47,6 +49,9 @@ Shows imported discovery activity in scanner tabs, including newly discovered se Akamai API Security scanner:: Shows correlation and governance enrichment activity for existing services, including risk and findings signals. +API gateway scanner:: +For providers that support policy write (Amazon API Gateway, Azure API Management, Google Apigee, and Kong Gateway), the *Settings* tab additionally supports configuring separate write credentials to enable policy write on discovered APIs. + == See Also * xref:exp-providers-manage.adoc[] From 5024057a14ea3ececea1dfe0f4c7b177dbe81d5d Mon Sep 17 00:00:00 2001 From: jenny hajee Date: Wed, 19 Aug 2026 15:32:59 -0500 Subject: [PATCH 3/9] Amazon out of scope for write policy support in R2 release. Removed those instances --- modules/ROOT/pages/exp-instances-add.adoc | 2 +- modules/ROOT/pages/exp-overview.adoc | 2 +- modules/ROOT/pages/exp-providers-manage.adoc | 2 +- modules/ROOT/pages/exp-scanners-add-from-providers.adoc | 2 +- .../ROOT/pages/exp-scanners-prerequisites-reference.adoc | 8 +++++++- modules/ROOT/pages/exp-scanners-view-details.adoc | 2 +- 6 files changed, 12 insertions(+), 6 deletions(-) diff --git a/modules/ROOT/pages/exp-instances-add.adoc b/modules/ROOT/pages/exp-instances-add.adoc index b8a3f2986..4743ae700 100644 --- a/modules/ROOT/pages/exp-instances-add.adoc +++ b/modules/ROOT/pages/exp-instances-add.adoc @@ -59,7 +59,7 @@ After creating or updating an instance, you can continue managing the service th -- For a managed instance on an Omni Gateway, policies are enforced through the Omni Gateway. -For an instance discovered on a third-party API gateway (Amazon API Gateway, Azure API Management, Google Apigee, or Kong Gateway), the *Policies* tab applies policies directly to the provider through policy write, with no Omni Gateway in the request path. This requires a scanner configured with write credentials for the provider. If the scanner has read-only credentials, the instance appears as *Read-Only* and policy actions are unavailable. For write scopes and requirements, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. +For an instance discovered on a third-party API gateway (Azure API Management, Google Apigee, or Kong Gateway), the *Policies* tab applies policies directly to the provider through policy write, with no Omni Gateway in the request path. This requires a scanner configured with write credentials for the provider. If the scanner has read-only credentials, the instance appears as *Read-Only* and policy actions are unavailable. For write scopes and requirements, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. If the instance uses a Kong gateway, applying a policy targets the gateway level and protects all services in that gateway. -- diff --git a/modules/ROOT/pages/exp-overview.adoc b/modules/ROOT/pages/exp-overview.adoc index f59538d49..ff627267a 100644 --- a/modules/ROOT/pages/exp-overview.adoc +++ b/modules/ROOT/pages/exp-overview.adoc @@ -11,7 +11,7 @@ The enhanced MuleSoft experience supports the full lifecycle of AI-connected int Entity Management:: Register and manage agents, REST and GraphQL APIs, MCP servers, Model proxies, and gateways, including Anypoint Omni Gateway, external gateways, and unmanaged gateways. Each type has a dedicated catalog under *Portfolio*. -Governance and Compliance:: Define and apply policies across domains such as access and security, performance and cost, data privacy and integrity, and compliance and observability. For connected third-party API gateways (Amazon API Gateway, Azure API Management, Google Apigee, and Kong Gateway), apply, enable, disable, and delete policies directly from Anypoint through policy write, with no Omni Gateway in the request path. Conformance reporting summarizes rule violations and severity so you can close gaps systematically. +Governance and Compliance:: Define and apply policies across domains such as access and security, performance and cost, data privacy and integrity, and compliance and observability. For connected third-party API gateways (Azure API Management, Google Apigee, and Kong Gateway), apply, enable, disable, and delete policies directly from Anypoint through policy write, with no Omni Gateway in the request path. Conformance reporting summarizes rule violations and severity so you can close gaps systematically. Cost and Performance Optimization:: Monitor token usage, per-instance signals, and daily cost where the product exposes them. Apply governance strategies and related controls, such as tool mapping and tool sanitization, to reduce spend and risk where the experience supports them. diff --git a/modules/ROOT/pages/exp-providers-manage.adoc b/modules/ROOT/pages/exp-providers-manage.adoc index cb632603b..2ab7de7c4 100644 --- a/modules/ROOT/pages/exp-providers-manage.adoc +++ b/modules/ROOT/pages/exp-providers-manage.adoc @@ -100,7 +100,7 @@ When scanning Kong, the enhanced experience discovers gateway-level plugin infor *Akamai API Security* is available only when your administrator has enabled the feature for your organization. When enabled, it appears in the *Not Connected* section of the Providers sidebar. ==== -Of these providers, the API gateway providers Amazon (API Gateway), Google (Apigee), Kong, and Microsoft (Azure API Management) support policy write. APIs discovered from a scanner that has only read credentials appear as *Read-Only*, and policy actions are unavailable until you add write credentials to the scanner. For provider-specific read and write scopes, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. +Of these providers, the API gateway providers Google (Apigee), Kong, and Microsoft (Azure API Management) support policy write. APIs discovered from a scanner that has only read credentials appear as *Read-Only*, and policy actions are unavailable until you add write credentials to the scanner. For provider-specific read and write scopes, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. The specific providers available depend on your organization's enabled products and enhanced experience configuration. diff --git a/modules/ROOT/pages/exp-scanners-add-from-providers.adoc b/modules/ROOT/pages/exp-scanners-add-from-providers.adoc index d38570bcc..63f5258d2 100644 --- a/modules/ROOT/pages/exp-scanners-add-from-providers.adoc +++ b/modules/ROOT/pages/exp-scanners-add-from-providers.adoc @@ -40,7 +40,7 @@ When a scanner is enabled, it can discover and read policies from API configurat * Policy write + -For API gateway providers that support policy write (Amazon API Gateway, Azure API Management, Google Apigee, and Kong Gateway), a scanner configured with write credentials lets you apply, enable, disable, and delete policies on discovered APIs directly from Anypoint. For write scopes and requirements, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. +For API gateway providers that support policy write (Azure API Management, Google Apigee, and Kong Gateway), a scanner configured with write credentials lets you apply, enable, disable, and delete policies on discovered APIs directly from Anypoint. For write scopes and requirements, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. == Workflow Entry Points for Adding a Scanner diff --git a/modules/ROOT/pages/exp-scanners-prerequisites-reference.adoc b/modules/ROOT/pages/exp-scanners-prerequisites-reference.adoc index bbc17f556..46962a38c 100644 --- a/modules/ROOT/pages/exp-scanners-prerequisites-reference.adoc +++ b/modules/ROOT/pages/exp-scanners-prerequisites-reference.adoc @@ -143,11 +143,14 @@ a| * *Resource scope (REST APIs):* `arn:aws:apigateway:{region}::/restapis/*` * *Resource scope (HTTP APIs):* `arn:aws:apigateway:{region}::/apis/*` +// TODO: Amazon API Gateway policy write is deferred to a later release. Restore the write scope below when AWS write support ships. +//// *Write scope (policy apply):* IAM write permissions for API Gateway, in addition to the read permissions: * `apigateway:PUT` * `apigateway:POST` * `apigateway:DELETE` +//// [NOTE] For web application firewall (WAF) policies, the scanner also uses `software.amazon.awssdk:wafv2` and `software.amazon.awssdk:route53`. @@ -232,7 +235,7 @@ a| == Policy Write Prerequisites -Policy write lets you apply, enable, disable, and delete policies on connected third-party gateway APIs directly from Anypoint, with no Anypoint gateway in the request path. Policy write is available for API gateway providers only: Amazon API Gateway, Azure API Management, Google Apigee, and Kong Gateway. Agent, API Security, and MCP scanners don't support policy write. +Policy write lets you apply, enable, disable, and delete policies on connected third-party gateway APIs directly from Anypoint, with no Anypoint gateway in the request path. Policy write is available for API gateway providers only: Azure API Management, Google Apigee, and Kong Gateway. Agent, API Security, and MCP scanners don't support policy write. Before you can write policies, confirm these prerequisites in addition to the discovery prerequisites in the matrix: @@ -248,9 +251,12 @@ The following table summarizes the read and write scopes for each API gateway pr | Read Scope | Write Scope +// TODO: Amazon API Gateway policy write is deferred to a later release. Restore this row when AWS write support ships. +//// | Amazon API Gateway | `apigateway:GET` | `apigateway:PUT`, `apigateway:POST`, `apigateway:DELETE` +//// | Azure API Management | Reader role (ARM) diff --git a/modules/ROOT/pages/exp-scanners-view-details.adoc b/modules/ROOT/pages/exp-scanners-view-details.adoc index b699c75b5..fefd49baf 100644 --- a/modules/ROOT/pages/exp-scanners-view-details.adoc +++ b/modules/ROOT/pages/exp-scanners-view-details.adoc @@ -50,7 +50,7 @@ Akamai API Security scanner:: Shows correlation and governance enrichment activity for existing services, including risk and findings signals. API gateway scanner:: -For providers that support policy write (Amazon API Gateway, Azure API Management, Google Apigee, and Kong Gateway), the *Settings* tab additionally supports configuring separate write credentials to enable policy write on discovered APIs. +For providers that support policy write (Azure API Management, Google Apigee, and Kong Gateway), the *Settings* tab additionally supports configuring separate write credentials to enable policy write on discovered APIs. == See Also From 2099afa163b80bb7f825a09d25f0c29feb2f2af5 Mon Sep 17 00:00:00 2001 From: Luana Dos Santos Date: Fri, 21 Aug 2026 14:05:03 -0300 Subject: [PATCH 4/9] W-23907611 docs: document Activity log tab for tracked policy writes Add coverage for the Activity log tab surfaced by the two additional scope PRDs (Policy Write / Unified Policy Catalog) and verified in code (ActivitiesTab.tsx, activitiesTab i18n). Applies are asynchronous and tracked (Apply/Update/Toggle/Remove; Running/Completed/Failed). Cross-linked from the apply flow and the instance Policies tab. Left as DRAFT with a TODO on the feature-flag/external-provider gating and no actor field (not a full audit trail). Co-Authored-By: Claude Opus 4.8 --- .../exp-governance-policy-library-apply.adoc | 24 +++++++++++++++++++ .../ROOT/pages/exp-services-view-details.adoc | 2 ++ 2 files changed, 26 insertions(+) diff --git a/modules/ROOT/pages/exp-governance-policy-library-apply.adoc b/modules/ROOT/pages/exp-governance-policy-library-apply.adoc index 3962c947a..416195cb9 100644 --- a/modules/ROOT/pages/exp-governance-policy-library-apply.adoc +++ b/modules/ROOT/pages/exp-governance-policy-library-apply.adoc @@ -78,6 +78,8 @@ You can filter policies by category: When you apply a policy, the platform validates it against your governance configuration and then creates the corresponding native policy on each selected instance's gateway. +Applying a policy is an asynchronous, tracked operation, not a fire-and-forget action. A message confirms that the operation is running and directs you to the *Activity log* tab to check its status. When you apply a policy to more than one instance, each instance reports its own result, so you can see which instances succeeded and which failed. To review the outcome, see <>. + [NOTE] ==== While a policy operation is in progress on an instance, applying policies to that instance is paused and policy actions are unavailable until the operation completes or fails. This prevents conflicting changes while the vendor-native apply workflow runs. @@ -122,6 +124,28 @@ On gateways that support it, you can enable or disable a policy without removing Policies that are outside your instance's scope appear in a read-only state. For these policies, edit, delete, and enable/disable actions are not available. +[#track-policy-changes] +== Track Policy Changes + +Policy write actions run asynchronously and are tracked, so you can confirm whether a change landed on the gateway instead of assuming it did. Review recent policy operations for an instance on the *Activity log* tab of the instance detail page. + +The *Activity log* tab lists recent policy operations with these columns: + +* *Policy*: The policy the operation applied to. +* *Action*: The operation performed — *Apply*, *Update*, *Toggle*, or *Remove*. +* *Status*: The current state of the operation — *Running*, *Completed*, or *Failed*. + +The tab shows the most recent operations from the last 30 days. If no policy changes have been recorded for the instance in that window, the tab reports that no activity is available. + +Use the *Activity log* tab to confirm that an apply, edit, enable, disable, or delete completed, or to see which operations failed and need to be retried. + +// TODO(W-23907611): The Activity log tab is gated by a feature flag and, per the code, +// currently appears only for external (non-MuleSoft) provider instances. Confirm the GA +// availability (flag state and which provider instances show the tab) with engineering. +// Also confirm the exact column headers and the empty-state wording against the shipped UI. +// Note: the log records policy/action/status/time only — it does NOT record an actor +// ("who"), so do not describe it as a full audit trail. + == See Also * xref:exp-governance-create-strategy.adoc[] diff --git a/modules/ROOT/pages/exp-services-view-details.adoc b/modules/ROOT/pages/exp-services-view-details.adoc index cf3d8ae88..b164d1f21 100644 --- a/modules/ROOT/pages/exp-services-view-details.adoc +++ b/modules/ROOT/pages/exp-services-view-details.adoc @@ -81,6 +81,8 @@ Policy visibility depends on the last successful scanner run, not on a live prov On supported gateways, the *Policies* tab also lets you manage the native policies applied to an instance. Depending on the gateway and your permissions, you can edit, delete, or enable and disable a policy directly from this tab. Policies that are outside your instance's scope appear in a read-only state, without edit, delete, or enable/disable actions. +Policy write actions are tracked. To confirm whether an apply, edit, enable, disable, or delete completed on the gateway, review the *Activity log* tab of the instance detail page. See xref:exp-governance-policy-library-apply.adoc#track-policy-changes[Track Policy Changes]. + For the full apply and management workflow, see xref:exp-governance-policy-library-apply.adoc[]. == See Also From aab5970593e08a53696d030c21d9ab5f8fcaeffa Mon Sep 17 00:00:00 2001 From: Luana Dos Santos Date: Fri, 28 Aug 2026 13:05:56 -0300 Subject: [PATCH 5/9] W-23907611 docs: consolidate PR 556 policy content and apply SME corrections Consolidate the external/universal policies documentation from PR 556 into this branch, and apply the SME review corrections from PR 556: - Universal-derived native policies are editable, not view-only (glossary, exp-policies-universal, exp-policies-apply-manage) - Anypoint gateways are Omni (Flex) and Mule; fix gateway-type wording - Instance locking is Apigee/Azure-wide; Kong locks only the one policy - Policy naming is an Apigee-only feature - Acknowledge the additional supported native Kong policies alongside the universal use cases (soften absolute "view-only" statements) - Apigee roles are one option, not required (reword) Flag the internal-error edit-restriction case inline for PM/eng. Co-Authored-By: Claude Opus 4.8 --- modules/ROOT/nav.adoc | 6 + modules/ROOT/pages/exp-glossary.adoc | 12 ++ .../exp-governance-policy-library-apply.adoc | 131 ++++------------ modules/ROOT/pages/exp-instances-add.adoc | 2 +- modules/ROOT/pages/exp-overview.adoc | 4 +- .../ROOT/pages/exp-policies-activity-log.adoc | 46 ++++++ .../ROOT/pages/exp-policies-apply-manage.adoc | 74 +++++++++ modules/ROOT/pages/exp-policies-overview.adoc | 40 +++++ .../exp-policies-provider-reference.adoc | 143 ++++++++++++++++++ .../ROOT/pages/exp-policies-universal.adoc | 67 ++++++++ modules/ROOT/pages/exp-providers-manage.adoc | 2 +- .../exp-scanners-add-from-providers.adoc | 4 +- modules/ROOT/pages/exp-scanners-manage.adoc | 4 +- .../exp-scanners-prerequisites-reference.adoc | 28 ++-- .../ROOT/pages/exp-scanners-view-details.adoc | 4 +- .../ROOT/pages/exp-services-view-details.adoc | 11 +- 16 files changed, 450 insertions(+), 128 deletions(-) create mode 100644 modules/ROOT/pages/exp-policies-activity-log.adoc create mode 100644 modules/ROOT/pages/exp-policies-apply-manage.adoc create mode 100644 modules/ROOT/pages/exp-policies-overview.adoc create mode 100644 modules/ROOT/pages/exp-policies-provider-reference.adoc create mode 100644 modules/ROOT/pages/exp-policies-universal.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 39ec1cab6..4d5db8c6a 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -28,11 +28,17 @@ *** xref:exp-scanners-view-details.adoc[] *** xref:exp-scanners-manage.adoc[] *** xref:exp-providers-manage.adoc[] + ** xref:exp-policies-overview.adoc[] + *** xref:exp-policies-universal.adoc[] + *** xref:exp-policies-apply-manage.adoc[] + *** xref:exp-policies-activity-log.adoc[] + *** xref:exp-policies-provider-reference.adoc[] ** xref:exp-governance-view-cost-and-token-usage.adoc[] *** xref:model-proxy-token-reports.adoc[] ** xref:exp-akamai-risk-correlation.adoc[] ** xref:exp-governance-work-with-strategies.adoc[] *** xref:exp-governance-create-strategy.adoc[] + *** xref:exp-governance-policy-library-apply.adoc[] *** xref:exp-governance-manage-strategies.adoc[] *** xref:exp-governance-govern-third-party-apis.adoc[] *** xref:exp-governance-monitor-cross-gateway-conformance.adoc[] diff --git a/modules/ROOT/pages/exp-glossary.adoc b/modules/ROOT/pages/exp-glossary.adoc index e6dd52476..47f4bee43 100644 --- a/modules/ROOT/pages/exp-glossary.adoc +++ b/modules/ROOT/pages/exp-glossary.adoc @@ -30,9 +30,15 @@ A unified view of compliance status across APIs hosted on Anypoint Platform gate Enhanced experience:: The new MuleSoft UI for managing your AI portfolio, including governance, instance management, observability, and agentic experiences. +External gateway provider:: +A third-party API gateway connected through a provider scanner whose policies you can manage from Anypoint. Supported providers include Google Apigee, Azure API Management, and Kong Gateway, with partial support for Amazon API Gateway. Policy management reuses the scanner connection's credentials. + Gateway:: A runtime component that proxies traffic to backend services while enforcing policies. Supported types include Anypoint Omni Gateway (managed), external gateways, and unmanaged gateways. +Injection point:: +Where a policy runs relative to the request and response (for example request or response on Apigee, or inbound, outbound, and backend on Azure API Management). Each policy template declares which injection points it allows. + Governance > Cost Management:: A section under Governance that surfaces token usage, daily spend signals, and cost optimization recommendations across your portfolio. Apply tool mapping, tool sanitization, and related strategies here where the experience supports them. @@ -101,3 +107,9 @@ A governance control that filters or modifies tool inputs and outputs before the Unmanaged instance:: A lighter-weight instance deployment that does not route traffic through Omni Gateway. Choose unmanaged instances when a full managed path does not match your operating model. + +Universal (canonical) policy:: +A provider-agnostic policy you configure once and apply across a mix of gateway providers. Anypoint translates a universal policy into each provider's native policy. Universal is a creation experience, not a managed entity: after you apply it, only native policies exist. Those native policies behave like any other native policy on the provider. You can edit, remove, enable, or disable them where the provider supports those actions. In the UI, universal policies carry a *Universal* badge. + +View-only policy:: +A discovered policy that Anypoint displays but can't create or edit, such as any policy that isn't one of the supported universal-backed policies. Depending on the provider, a view-only policy can still be removed or enabled/disabled. diff --git a/modules/ROOT/pages/exp-governance-policy-library-apply.adoc b/modules/ROOT/pages/exp-governance-policy-library-apply.adoc index 416195cb9..c721b9fcb 100644 --- a/modules/ROOT/pages/exp-governance-policy-library-apply.adoc +++ b/modules/ROOT/pages/exp-governance-policy-library-apply.adoc @@ -1,25 +1,20 @@ -= Apply and Manage Policies from the Policy Library -:keywords: policy library, canonical policies, universal policies, governance policies, apply policy, edit policy, delete policy, policy catalog += Apply Universal Policies from the Policy Library +:keywords: policy library, universal policies, canonical policies, governance policies, apply policy, policy catalog // DRAFT: Policy Write (MS2026-08-R2 / Dreamforce). Tracked in W-23907611. -// This topic was previously a commented-out draft for the Policy Read GA. It has been -// rewritten for the Policy Write scope. Sections contain TODO(W-23907611) markers where a -// detail could not be grounded in code and must be confirmed with the PM before publishing. -// Blockers to resolve before removing this DRAFT banner and publishing: -// 1. Confirmed list of the universal policy templates and their per-gateway native mappings -// (APIM-owned; not enumerated in the Omni codebase). -// 2. Which feature flags are ON for GA, per gateway -// (W_23173868_CANONICAL_POLICIES_ENABLED for Kong, -// W_23308031_NONKONG_POLICIES_VIA_APIM_ENABLED for Apigee/Azure). -// 3. The enable/disable support matrix (which gateways expose the toggle at GA). -// 4. Human-readable required permission/role names for policy write actions. -// 5. Whether applying policies from the API Instance page is enabled at GA -// (listed as out of scope for MS2026-08-R2 in the program tracker). - -Use the Policy Library to apply a universal policy template to your API instances and to manage the resulting native policies. A universal template expresses a policy once and applies it as the correct vendor-native policy on each supported gateway, so you can enforce consistent controls across MuleSoft, Google Apigee, Kong Gateway, and Azure API Management without authoring a policy per gateway. - -// TODO(W-23907611): AWS API Gateway is excluded from the policy write flow for this release -// (deferred to a later release). Confirm the customer-facing framing of the AWS exclusion with the PM. +// This is the Governance-side entry point into the Policies documentation set +// (xref:exp-policies-overview.adoc[]). The detailed universal-policy model, apply and +// management workflow, activity tracking, and per-provider support live in the exp-policies-* +// topics; keep this topic thin and link out rather than duplicating that content. +// Open items to confirm with the PM before removing this DRAFT banner: +// 1. The Policy Library location in the Governance UI +// (*Governance* > *Governance Strategies* > *Policy Library*). +// 2. The category filter labels shown in the Policy Library. +// 3. Human-readable required permission/role names for policy write actions. + +The Policy Library is the Governance entry point for applying *universal policies*. A universal policy expresses a policy once and applies it as the correct vendor-native policy on each supported gateway, so you can enforce consistent controls across MuleSoft, Google Apigee, Kong Gateway, and Azure API Management without authoring a policy per gateway. + +This topic covers the Governance doorway and the apply flow. For the full universal policy model, the apply and management workflow, activity tracking, and per-provider support, see xref:exp-policies-overview.adoc[] and xref:exp-policies-universal.adoc[]. == Before You Begin @@ -33,21 +28,18 @@ Before getting started, make sure you have: ** API Manager: Manage Policies -- + -// TODO(W-23907611): Confirm the exact permission/role names required for apply, edit, delete, -// and enable/disable. The code enforces per-action permissions (create, update, enable, -// disable, delete) fetched per instance, but exposes only permission keys, not role labels. For more information, see xref:exp-home-start.adoc#permissions[Enhanced Experience Permissions]. * API instances registered in the portfolio on a supported gateway. [NOTE] ==== -Policy write actions respect your permissions. If you don't have permission for an action, that action is unavailable and the experience explains that the action isn't permitted. If the platform can't verify your permissions for an instance, the actions remain available and the gateway enforces authorization when you submit the request. +Policy write actions respect your permissions. If you don't have permission for an action, that action is unavailable and the experience explains that the action isn't permitted. If the platform can't verify your permissions for an instance, the actions remain available and the gateway enforces authorization when you submit the request. See xref:exp-policies-apply-manage.adoc[]. ==== == Browse the Policy Library -The Policy Library is a catalog of predefined policies that you can browse from *Governance* > *Governance Strategies* > *Policy Library*. Each policy appears with its name, category, and a short description of what it enforces. +Browse the Policy Library from *Governance* > *Governance Strategies* > *Policy Library*. Each policy appears with its name, category, and a short description of what it enforces. You can filter policies by category: @@ -57,98 +49,27 @@ You can filter policies by category: * *Data Privacy & Integrity* * *Compliance & Observability* -// TODO(W-23907611): Confirm the shipping list of universal policy templates and the native -// policy each maps to per gateway (for example, an API key template mapping to VerifyAPIKey -// on Apigee and key-auth on Kong). This mapping is served at runtime by API Manager and is -// not defined in the Omni codebase, so it must be confirmed with the PM / API Platform team -// before it is documented as a table. Do not transcribe the mapping from the planning tracker. - -== Apply a Policy +== Apply a Universal Policy -. Log in and go to *Governance* > *Governance Strategies* > *Policy Library*. +. Go to *Governance* > *Governance Strategies* > *Policy Library*. . Select the policy you want to apply. . Configure the policy parameters. Required and optional fields vary by policy type. . Select the API instances where you want to apply the policy. . Review the summary, then apply the policy. -// TODO(W-23907611): Confirm the exact wizard step labels and the primary action button label -// against the shipped UI before publishing (the apply flow is driven by the governance policy -// wizard). Applying policies directly from an API Instance page is listed as out of scope for -// MS2026-08-R2 — confirm whether that entry point is available at GA before documenting it. - When you apply a policy, the platform validates it against your governance configuration and then creates the corresponding native policy on each selected instance's gateway. -Applying a policy is an asynchronous, tracked operation, not a fire-and-forget action. A message confirms that the operation is running and directs you to the *Activity log* tab to check its status. When you apply a policy to more than one instance, each instance reports its own result, so you can see which instances succeeded and which failed. To review the outcome, see <>. - -[NOTE] -==== -While a policy operation is in progress on an instance, applying policies to that instance is paused and policy actions are unavailable until the operation completes or fails. This prevents conflicting changes while the vendor-native apply workflow runs. -==== - -== Manage Applied Policies - -Manage the native policies on an instance from the *Policies* tab of the instance detail page. The available actions depend on the gateway and on your permissions. For where to find this tab, see xref:exp-services-view-details.adoc[]. - -=== Edit a Policy - -For Apigee and Azure API Management native policies that originate from a universal template, select *Edit Configuration* to change the policy's settings. - -Editing uses a two-tier experience: - -* If the policy's configuration schema is available, the policy opens in an editable form. -* If no schema is available, the policy opens in a read-only view of its current configuration. - -Your changes are saved back to the vendor gateway. - -[NOTE] -==== -Editing Kong gateway-scope policies is not supported. -==== - -=== Delete a Policy - -To remove a native policy from an instance, select the remove action for the policy. A confirmation dialog appears before the policy is removed. Removing a policy detaches it from the instance, and traffic that the policy was filtering is no longer enforced. After you confirm, the policy no longer appears in the instance's policy list. - -// TODO(W-23907611): Confirm the exact remove action/menu label and confirmation button label -// against the shipped UI before publishing. - -=== Enable or Disable a Policy - -On gateways that support it, you can enable or disable a policy without removing it. The state change is reflected in the policy list. On gateways that don't support enabling and disabling, the toggle is unavailable. - -// TODO(W-23907611): Confirm the enable/disable support matrix (which gateways expose the -// toggle at GA) before publishing. Do not list specific gateways as supported or unsupported -// until engineering confirms the shipping behavior. - -=== View Policies Outside Your Scope - -Policies that are outside your instance's scope appear in a read-only state. For these policies, edit, delete, and enable/disable actions are not available. - -[#track-policy-changes] -== Track Policy Changes - -Policy write actions run asynchronously and are tracked, so you can confirm whether a change landed on the gateway instead of assuming it did. Review recent policy operations for an instance on the *Activity log* tab of the instance detail page. - -The *Activity log* tab lists recent policy operations with these columns: - -* *Policy*: The policy the operation applied to. -* *Action*: The operation performed — *Apply*, *Update*, *Toggle*, or *Remove*. -* *Status*: The current state of the operation — *Running*, *Completed*, or *Failed*. - -The tab shows the most recent operations from the last 30 days. If no policy changes have been recorded for the instance in that window, the tab reports that no activity is available. - -Use the *Activity log* tab to confirm that an apply, edit, enable, disable, or delete completed, or to see which operations failed and need to be retried. +Applying a policy is an asynchronous, tracked operation, not a fire-and-forget action. When you apply a policy to more than one instance, each instance reports its own result, so you can see which instances succeeded and which failed. To confirm the outcome on each target, review the *Activity log* tab of the instance. See xref:exp-policies-activity-log.adoc[]. -// TODO(W-23907611): The Activity log tab is gated by a feature flag and, per the code, -// currently appears only for external (non-MuleSoft) provider instances. Confirm the GA -// availability (flag state and which provider instances show the tab) with engineering. -// Also confirm the exact column headers and the empty-state wording against the shipped UI. -// Note: the log records policy/action/status/time only — it does NOT record an actor -// ("who"), so do not describe it as a full audit trail. +For how universal policies map to each provider's native policy, and which policies you can then edit, enable, disable, or remove afterward, see xref:exp-policies-universal.adoc[] and xref:exp-policies-apply-manage.adoc[]. == See Also +* xref:exp-policies-overview.adoc[] +* xref:exp-policies-universal.adoc[] +* xref:exp-policies-apply-manage.adoc[] +* xref:exp-policies-activity-log.adoc[] +* xref:exp-policies-provider-reference.adoc[] * xref:exp-governance-create-strategy.adoc[] * xref:exp-governance-work-with-strategies.adoc[] * xref:exp-services-view-details.adoc[] -* xref:exp-governance-govern-third-party-apis.adoc[] diff --git a/modules/ROOT/pages/exp-instances-add.adoc b/modules/ROOT/pages/exp-instances-add.adoc index 4743ae700..74f125d4e 100644 --- a/modules/ROOT/pages/exp-instances-add.adoc +++ b/modules/ROOT/pages/exp-instances-add.adoc @@ -59,7 +59,7 @@ After creating or updating an instance, you can continue managing the service th -- For a managed instance on an Omni Gateway, policies are enforced through the Omni Gateway. -For an instance discovered on a third-party API gateway (Azure API Management, Google Apigee, or Kong Gateway), the *Policies* tab applies policies directly to the provider through policy write, with no Omni Gateway in the request path. This requires a scanner configured with write credentials for the provider. If the scanner has read-only credentials, the instance appears as *Read-Only* and policy actions are unavailable. For write scopes and requirements, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. +For an instance discovered on a third-party API gateway (Azure API Management, Google Apigee, or Kong Gateway), the *Policies* tab applies policies directly to the provider through policy write, with no Omni Gateway in the request path. This requires a scanner connection whose credentials carry the provider's write scope. If the connection has only read access to the provider, the instance appears as *Read-Only* and policy actions are unavailable. For write scopes and requirements, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. For the apply and management workflow, see xref:exp-policies-apply-manage.adoc[]. If the instance uses a Kong gateway, applying a policy targets the gateway level and protects all services in that gateway. -- diff --git a/modules/ROOT/pages/exp-overview.adoc b/modules/ROOT/pages/exp-overview.adoc index ff627267a..4f5481497 100644 --- a/modules/ROOT/pages/exp-overview.adoc +++ b/modules/ROOT/pages/exp-overview.adoc @@ -11,7 +11,7 @@ The enhanced MuleSoft experience supports the full lifecycle of AI-connected int Entity Management:: Register and manage agents, REST and GraphQL APIs, MCP servers, Model proxies, and gateways, including Anypoint Omni Gateway, external gateways, and unmanaged gateways. Each type has a dedicated catalog under *Portfolio*. -Governance and Compliance:: Define and apply policies across domains such as access and security, performance and cost, data privacy and integrity, and compliance and observability. For connected third-party API gateways (Azure API Management, Google Apigee, and Kong Gateway), apply, enable, disable, and delete policies directly from Anypoint through policy write, with no Omni Gateway in the request path. Conformance reporting summarizes rule violations and severity so you can close gaps systematically. +Governance and Compliance:: Define and apply policies across domains such as access and security, performance and cost, data privacy and integrity, and compliance and observability. For connected third-party API gateways (Azure API Management, Google Apigee, and Kong Gateway), apply, enable, disable, and remove policies directly from Anypoint through policy write, with no Omni Gateway in the request path. Conformance reporting summarizes rule violations and severity so you can close gaps systematically. Cost and Performance Optimization:: Monitor token usage, per-instance signals, and daily cost where the product exposes them. Apply governance strategies and related controls, such as tool mapping and tool sanitization, to reduce spend and risk where the experience supports them. @@ -38,7 +38,7 @@ Under *Portfolio*, open *Agents*, *MCP Servers*, *Model Proxies*, *APIs*, or *Ga In *Portfolio*, open a service detail page from *Agents*, *MCP Servers*, *Model Proxies*, or *APIs*, then open the *Instances* tab to create managed or unmanaged deployments that match your needs. Managed instances on Omni Gateway give stronger governance and monitoring when the new experience exposes them. *Gateways* don't include an *Instances* tab on their detail page. For instance workflows, see xref:exp-instances-add.adoc[]. . Configure policies. + -On a service detail page in *Portfolio*, open the *Policies* tab for the service or one of its instances to apply governance policies that match access control, data privacy, performance, and compliance goals. For APIs discovered from third-party gateways, applying policies requires a scanner configured with write credentials for the provider; see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. Use top-level *Governance* for gateway-wide policy work, organization strategies, and cost tools. For governance policy workflows, see xref:exp-governance-work-with-strategies.adoc[]. +On a service detail page in *Portfolio*, open the *Policies* tab for the service or one of its instances to apply governance policies that match access control, data privacy, performance, and compliance goals. For APIs discovered from third-party gateways, applying policies requires a scanner connection whose credentials carry the provider's write scope; see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. Use top-level *Governance* for gateway-wide policy work, organization strategies, and cost tools. For governance policy workflows, see xref:exp-governance-work-with-strategies.adoc[]. . Review compliance. + In *Portfolio*, open a service detail page from *Agents*, *APIs*, or *MCP Servers*, then open the *Conformance Report* tab to review scores, violations, and warnings and address the findings your governance team prioritizes. For gateways, use top-level *Governance* for the same compliance story at the scope the experience supports. For service-level tabs and conformance context, see xref:exp-services-view-details.adoc[]. diff --git a/modules/ROOT/pages/exp-policies-activity-log.adoc b/modules/ROOT/pages/exp-policies-activity-log.adoc new file mode 100644 index 000000000..52700a986 --- /dev/null +++ b/modules/ROOT/pages/exp-policies-activity-log.adoc @@ -0,0 +1,46 @@ += Tracking Policy Operations in the Activity Log +:keywords: activity log, policy operations, asynchronous operations, policy status, api manager, anypoint platform + +Every policy change on an external provider runs asynchronously, so a request that Anypoint accepts isn't the same as a policy that's applied on the gateway. Use the *Activity log* tab on an API instance to confirm what actually happened. + +== Before You Begin + +Before getting started, make sure you have: + +* An Anypoint Platform account. +* Access to the API instance whose *Policies* and *Activity log* tabs you want to view. ++ +For more information, see xref:exp-home-start.adoc#permissions[Enhanced Experience Permissions]. + +== Asynchronous Operations and Eventual Consistency + +When you trigger a policy action, Anypoint accepts the request immediately and does the real work in the background: it talks to the provider, refreshes its view of the provider's state, and records the outcome. As a result, the policy list is eventually consistent, it sometimes doesn't reflect the change right after an action. The UI shows an optimistic view until the background job finishes and the state is reconciled. + +== Reading the Activity Log + +The *Activity log* tab lists recent policy operations for the API instance. By default, it shows the last 10 activities from the last 30 days. Select *Refresh* to reload. If no operations have run in that window, the tab indicates that there are no recorded policy changes. + +Each entry has these columns: + +* *Action*: the type of operation, such as *Apply*, *Update* (edit), *Toggle* (enable/disable), *Remove*, or *Universal* (a universal policy apply). +* *Policy*: the policy the operation applies to. +* *Status*: one of three states: +** *Running* +** *Completed* +** *Failed* + +Open an entry to see when it started and finished. + +== Interpreting a Failure + +For a failed operation, open it to see why. The failure detail explains the error and, when applicable, whether the operation is safe to retry: + +* Transient failures come from a temporary problem, such as an unreachable gateway or a scan error. Try the operation again. +* Other failures come from your configuration or the instance's state. For example, an invalid configuration, a conflict with the instance's current state, or a policy that can't be translated for the target gateway. Fix the underlying issue before retrying. + +== See Also + +* xref:exp-policies-overview.adoc[] +* xref:exp-policies-apply-manage.adoc[] +* xref:exp-policies-universal.adoc[] +* xref:exp-policies-provider-reference.adoc[] diff --git a/modules/ROOT/pages/exp-policies-apply-manage.adoc b/modules/ROOT/pages/exp-policies-apply-manage.adoc new file mode 100644 index 000000000..bb0ea0cbd --- /dev/null +++ b/modules/ROOT/pages/exp-policies-apply-manage.adoc @@ -0,0 +1,74 @@ += Applying and Managing Policies +:keywords: apply policy, edit policy, remove policy, enable policy, disable policy, external gateways, api manager, anypoint platform + +Apply, edit, enable, disable, and remove policies on an API instance from the *Policies* tab in *Portfolio*. These actions work on Anypoint gateways (Omni and Mule), and on external providers such as Google Apigee, Azure API Management, and Kong Gateway, subject to per-provider support. See xref:exp-policies-provider-reference.adoc[]. + +== Before You Begin + +Before getting started, make sure you have: + +* An Anypoint Platform account. +* The API Manager: Manage Policies permission. ++ +For more information, see xref:exp-home-start.adoc#permissions[Enhanced Experience Permissions]. +* For external providers, a connected scanner for that provider. Anypoint reuses the same connection and credentials you configured for scanning to authorize and perform policy changes. There's no second set of provider credentials to configure. The per-provider setup you must do on your side (for example, Apigee roles and permissions) is described in xref:exp-policies-provider-reference.adoc[]. + +[NOTE] +==== +Button state is a hint, not the final authorization. The *Policies* tab enables or disables actions based on what it believes you can do, but the real permission check happens when the background job talks to the provider. If you lack permission there, the operation fails and the failure appears in the *Activity log*. When Anypoint can't reliably determine your permissions, it keeps the actions available rather than blocking them; if you aren't authorized, the gateway rejects the request when the background job runs. For providers Anypoint can't check at all, actions can appear disabled. +==== + +== Apply a Policy + +. In *Portfolio*, open the API and select the instance. +. Open the *Policies* tab and select *Apply Policy*. +. Choose the policy and configure it. +. If the provider requires a policy name, enter one. ++ +Policy naming applies to Apigee only, where the name is the policy's unique identity on the gateway, not just a label. Choose it deliberately: the name is required at creation and you can't change it later. Other providers don't use policy names. See <>. +. Apply the policy. Anypoint accepts the request and performs it in the background. Confirm the outcome in the *Activity log* tab. See xref:exp-policies-activity-log.adoc[]. + +To apply a universal policy across multiple providers at once, use the *Policy Library* instead. See xref:exp-policies-universal.adoc[]. + +[[policy-edit-restrictions]] +== Policy Edit Restrictions + +Having permissions is necessary but not sufficient to edit a policy. Anypoint supports editing the curated set of policies that back the universal use cases, plus several additional native Kong policies (see xref:exp-policies-universal.adoc[]); other recognized policies are view-only. Native policies created from a universal use case are editable like any other supported native policy. When *Edit Configuration* is unavailable, the UI explains why. Common reasons include: + +* Anypoint doesn't recognize the policy's template, or doesn't yet support managing policies with its schema. +// TODO(W-23907611): SME (fedebrasburg) notes this case is an internal error the user can't act on; +// confirm with PM/eng whether to document it here or direct users to open a support case instead. +* The policy's configuration doesn't match its expected schema. +* The policy is scoped above the instance rather than to it. +* The policy has conditional rules. +* The policy has no provider reference. +* The provider doesn't support the action. +* Another operation is already in progress on the policy. + +== Enable, Disable, and Remove + +You can enable, disable, and remove policies more broadly than you can edit them, because these actions don't require a recognized configuration shape. It's normal to see a policy where *Edit Configuration* is unavailable while *Enable Policy*, *Disable Policy*, and *Remove Policy* remain available, as long as the provider supports that action. + +* *Enable Policy* / *Disable Policy* toggle a policy on or off. Apigee and Azure API Management have no native enable/disable state, so these actions aren't available there. See xref:exp-policies-provider-reference.adoc#supported-actions-by-provider[Supported Actions by Provider]. +* *Remove Policy* detaches the policy from the instance. + +While an operation is in progress, the provider locks further changes until it finishes. The scope of that lock differs by provider: Apigee and Azure API Management lock the entire instance, so no other policy operation on that instance can start until the current one completes; Kong Gateway locks only the policy being changed, so you can work with other policies on the same instance at the same time. You can track progress in the *Activity log*. See xref:exp-policies-provider-reference.adoc#instance-locking-during-operations[Instance Locking During Operations]. + +[[policy-naming-and-identity]] +== Policy Naming and Identity + +Policy naming applies to Apigee only. Other providers don't use policy names, and you aren't required to enter one. On Apigee, the name is the policy's unique identity on the gateway, not just a label: + +* The name is required at creation. +* The name can't be changed afterward. On a later edit, the name field is fixed: editing changes the policy's configuration, never its name. +* To change a name, remove the policy and create a new one. + +An Apigee edit that tries to change the name is rejected, because the name is the on-gateway identifier. + +== See Also + +* xref:exp-policies-overview.adoc[] +* xref:exp-policies-universal.adoc[] +* xref:exp-policies-activity-log.adoc[] +* xref:exp-policies-provider-reference.adoc[] +* xref:exp-services-view-details.adoc[] diff --git a/modules/ROOT/pages/exp-policies-overview.adoc b/modules/ROOT/pages/exp-policies-overview.adoc new file mode 100644 index 000000000..a69b610a7 --- /dev/null +++ b/modules/ROOT/pages/exp-policies-overview.adoc @@ -0,0 +1,40 @@ += Managing Policies on Gateway Providers +:keywords: policies, gateway policies, external gateways, apigee, azure api management, kong, api manager, anypoint platform + +Manage policies not only on Anypoint and Mule gateways but on external gateway providers, such as Google Apigee, Azure API Management, and Kong Gateway. You work with these policies entirely through the Anypoint UI, from the *Policies* tab of an API instance in *Portfolio*. + +== Before You Begin + +Before getting started, make sure you have: + +* An Anypoint Platform account. +* The API Manager: Manage Policies permission to apply, edit, enable, disable, or remove policies. ++ +For more information, see xref:exp-home-start.adoc#permissions[Enhanced Experience Permissions]. +* A provider scanner already connected for each external provider whose policies you want to manage. Policy management reuses the same connection you set up for scanning. See xref:exp-scanners-add-from-providers.adoc[]. + +== Reading Policies vs. Writing Policies + +There are two distinct ways you interact with provider policies: + +* Read (discover and display): Provider scanners import the full catalog of policies attached on the provider so you can see them on the *Policies* tab. This is view-only. See xref:exp-services-view-details.adoc#view-read-policies-discovered-by-scanners[View Read Policies Discovered by Scanners]. +* Write (create, edit, enable, disable, remove): From the same *Policies* tab, you can manage a curated subset of policies directly on the provider. This is the feature described in this section. + +== The Editability Rule + +Anypoint recognizes and displays every policy it discovers, but you can create and edit only a curated set: the policies that back the universal use cases, plus several additional native Kong policies. See xref:exp-policies-universal.adoc[]. Other recognized policies are view-only. + +You can remove, enable, and disable policies more broadly than you can edit them, so it's normal to see a policy where *Edit Configuration* is unavailable while *Remove Policy* and the enable and disable actions remain available, as long as the provider supports that action. See xref:exp-policies-apply-manage.adoc[] and xref:exp-policies-provider-reference.adoc[]. + +== How Policy Operations Work + +Every policy change on an external provider, such as apply, edit, enable, disable, or remove, runs asynchronously. When you trigger an action, Anypoint accepts the request and performs the work on the provider in the background, then reconciles its view of the provider's state. An accepted request isn't the same as an applied policy, so to confirm what actually happened, open the *Activity log* tab for the API instance. See xref:exp-policies-activity-log.adoc[]. + +== See Also + +* xref:exp-policies-universal.adoc[] +* xref:exp-policies-apply-manage.adoc[] +* xref:exp-policies-activity-log.adoc[] +* xref:exp-policies-provider-reference.adoc[] +* xref:exp-services-view-details.adoc[] +* xref:exp-scanners-add-from-providers.adoc[] diff --git a/modules/ROOT/pages/exp-policies-provider-reference.adoc b/modules/ROOT/pages/exp-policies-provider-reference.adoc new file mode 100644 index 000000000..b9cd6119b --- /dev/null +++ b/modules/ROOT/pages/exp-policies-provider-reference.adoc @@ -0,0 +1,143 @@ += Provider Support and Limitations for Policies +:keywords: policy provider support, apigee, azure api management, kong, aws, injection points, policy permissions, anypoint platform + +External gateways differ substantially in what they support and how they behave. This reference summarizes per-provider policy support, the setup each provider requires on your side, injection points, and locking behavior during operations. + +== Before You Begin + +Before getting started, make sure you have: + +* An Anypoint Platform account. +* A connected scanner for each external provider whose policies you want to manage. Policy management reuses the scanner connection's credentials. See xref:exp-scanners-add-from-providers.adoc[]. + +[[supported-actions-by-provider]] +== Supported Actions by Provider + +[cols="2,^1,^1,^1,^1",options="header"] +|=== +|Provider |Apply |Edit |Remove |Enable/Disable + +|Anypoint +|Yes |Yes |Yes |Yes + +|Kong Gateway +|Yes |Yes |Yes |Yes + +|Google Apigee +|Yes |Yes |Yes |No (no native concept) + +|Azure API Management +|Yes |Yes |Yes |No (no native concept) + +|Amazon API Gateway +|No |No |No |No (not supported yet) +|=== + +[NOTE] +==== +* Apply and Edit are further limited to the supported (universal-backed) policies. A Yes in the Edit column means the provider supports editing, not that every policy is editable. See xref:exp-policies-apply-manage.adoc#policy-edit-restrictions[Policy Edit Restrictions]. +* Apigee and Azure API Management have no native enabled/disabled state (a policy is either attached or not), so the enable/disable actions aren't available there. +* Amazon API Gateway is not supported for policy write yet. +==== + +== Per-Provider Permissions + +Because policy management reuses the scanner connection, the permissions you see reflect what that connection's identity is allowed to do on the provider, not a separate login. + +* Google Apigee: Anypoint checks the connected Google service account's actual permissions on Google Cloud. See <>. +* Azure API Management: Anypoint checks the connected Azure principal's role-based permissions on the API resource, including permissions inherited from higher scopes. +* Kong Gateway: access is based on your Kong Konnect roles and team memberships for the instance's control plane. Admin and power teams get full access; otherwise a matching role is required. +* Anypoint: uses the same Anypoint Platform permissions as elsewhere in the product, with no separate provider-side check. + +== Injection Points + +An injection point is where a policy runs relative to the request and response. Each policy template declares the injection points that it allows. If you choose an unsupported injection point, the system rejects the choice. + +* Google Apigee: you can choose request or response. On the Apigee side, both map to the proxy-level `PreFlow` (request and response map to the corresponding `PreFlow` section). +* Azure API Management: supports `inbound`, `outbound`, and `backend`. Azure's error-handling section is not editable through Anypoint. +* Kong Gateway: the injection point is informational only; Kong's plugin phase is fixed, so it doesn't change placement. + +[[instance-locking-during-operations]] +== Instance Locking During Operations + +To prevent conflicting concurrent changes, an in-progress operation takes a lock. The scope of that lock differs by provider: + +* Azure API Management and Google Apigee lock the entire API instance. While one policy operation is running, no other policy operation on that instance can start. Wait for the running one to finish. On Azure, an instance's policies live in a single document, so any change touches the whole thing. On Apigee, a change re-deploys the whole proxy, so it's inherently instance-wide. +* Kong Gateway locks only the specific policy that you modify. You can work with other policies on the same instance simultaneously. +* Anypoint takes no such lock. + +If an operation is already in progress, another operation is mid-flight on that instance (Azure or Apigee) or on that same policy (Kong). Wait for the operation to complete. You can track it in the *Activity log*. See xref:exp-policies-activity-log.adoc[]. + +[[apigee-required-permissions-and-roles]] +== Apigee Required Permissions and Roles + +For Apigee, the connected Google service account requires these permissions for policy create, edit, and remove operations to work. They cover the read-import-deploy cycle every Apigee change performs: + +* `apigee.proxies.get` +* `apigee.proxyrevisions.get` +* `apigee.proxies.create` +* `apigee.deployments.list` +* `apigee.deployments.create` + +To get these permissions, you can use one of these predefined Apigee roles: + +* Apigee API Admin +* Apigee Environment Admin + +Any custom role or higher-scope grant that includes the five permissions also works. Anypoint checks the account's effective permissions, not the role name. + +[[supported-policies-and-native-equivalents]] +== Supported Policies and Native Equivalents + +At launch, Anypoint supports five universal use cases. Each maps to a native policy on each provider. These native policies are the ones you can create and edit, along with the additional native Kong policies listed after this table. Other recognized policies are view-only. + +[cols="1,1,1,1,1",options="header"] +|=== +|Universal Use Case |Anypoint |Google Apigee |Azure API Management |Kong Gateway + +|API Key Enforcement +|Client ID Enforcement +|Verify API Key +|— (not available) +|Key Auth + +|CORS +|CORS +|CORS +|CORS +|CORS + +|Header Manipulation +|Header Injection + Header Removal +|Assign Message (request & response) +|Set Header (inbound & outbound) +|Request Transformer + Response Transformer + +|IP Allowlist +|IP Allowlist +|Access Control +|IP Filter +|IP Restriction + +|JWT Validation +|JWT Validation (Mule 4 & Flex Gateway) +|Verify JWT +|— (not available) +|JWT Signer +|=== + +[NOTE] +==== +* A dash (—) means that the provider doesn't offer the use case because it lacks a native equivalent. +* Some use cases map to more than one native policy. For example, Header Manipulation applies separate request/response (or inbound/outbound) policies, and Anypoint's Header Manipulation is two policies (injection and removal). +==== + +Beyond the universal use cases, Anypoint also supports these native Kong policies: `acl`, `acme`, `basic-auth`, `header-cert-auth`, `ldap-auth`, `ldap-auth-advanced`, `mtls-auth`, `opa`, `tls-handshake-modifier`, and `tls-metadata-headers`. + +== See Also + +* xref:exp-policies-overview.adoc[] +* xref:exp-policies-universal.adoc[] +* xref:exp-policies-apply-manage.adoc[] +* xref:exp-policies-activity-log.adoc[] +* xref:exp-scanners-add-from-providers.adoc[] diff --git a/modules/ROOT/pages/exp-policies-universal.adoc b/modules/ROOT/pages/exp-policies-universal.adoc new file mode 100644 index 000000000..a5d9966c1 --- /dev/null +++ b/modules/ROOT/pages/exp-policies-universal.adoc @@ -0,0 +1,67 @@ += Universal Policies +:keywords: universal policies, canonical policies, policy library, multi-provider policies, apigee, azure api management, kong, anypoint platform + +A universal policy is a provider-agnostic authoring experience. You configure one policy once, and Anypoint translates it into each provider's native policy and applies it across the instances you select, even a mix of Google Apigee, Azure API Management, Kong Gateway, and Anypoint instances at the same time. In the UI, universal policies carry a *Universal* badge, indicating that they work across all gateways. + +You apply universal policies from the *Policy Library*, which walks you through four steps: *Select Policy*, *Configure Policy*, *Select Instances*, and *Review & Apply*. + +== Universal Use Cases + +At launch, there are five universal use cases. Each maps to a specific native policy per provider. See xref:exp-policies-provider-reference.adoc#supported-policies-and-native-equivalents[Supported Policies and Native Equivalents]: + +* API Key Enforcement +* CORS (Cross-Origin Resource Sharing) +* Header Manipulation +* IP Allowlist +* JWT Validation + +These are the primary policies you can create and edit across providers. Anypoint also supports several additional native Kong policies. See xref:exp-policies-provider-reference.adoc#supported-policies-and-native-equivalents[Supported Policies and Native Equivalents]. Other recognized policies are view-only. See xref:exp-policies-apply-manage.adoc#policy-edit-restrictions[Policy Edit Restrictions]. + +== Universal Is a Creation Experience + +Use a universal policy to implement a use case across multiple native gateways from a single starting point. Only native policies remain on each provider. No separate universal object exists, so you can't edit or remove it. + +After creation, the resulting native policies behave like any other native policy on each provider. From the *Policies* tab, you can edit, remove, enable, or disable them where the provider supports those actions. There is no universal object to manage separately. + +== Confirming What Happened + +Because universal is only a creation experience, there is no dedicated universal activity view. To see the outcome on each target, open that instance's *Activity log* tab. Universal applies appear there with the *Universal* action type. See xref:exp-policies-activity-log.adoc[]. + +[NOTE] +==== +When a universal policy targets Anypoint instances, there is currently no Activity log record for those targets, so there's no in-product way to confirm the outcome on Anypoint targets. This is a known limitation. For external providers (Apigee, Azure, and Kong), you can follow the outcome in each instance's *Activity log*. +==== + +== Universal vs. Automated vs. Governance + +These three are easy to confuse. Use this comparison to choose the right tool: + +[cols="1,2,2,2",options="header"] +|=== +| | Universal | Automated Policies | Governance + +|What it is +|A create-only authoring experience: configure once, applied as each provider's native policy across many instances, including external providers. +|Policies that auto-attach to any API matching a set of criteria (runtime, technology, environment, and so on), applied by rule, not to one hand-picked target. +|Reporting and compliance only: conformance reports for an API or instance. Doesn't apply policies. + +|Lifecycle +|None after creation. There's no universal object to edit or delete. +|Fully managed: create, edit, delete, and coverage changes as APIs come in and out of scope. +|Read-only reports. + +|Scope +|Multi-provider, applied to the instances you select. +|Anypoint native (Omni and Mule), applied automatically by matching rules. +|Across APIs and instances. +|=== + +For automated policies and governance strategies, see xref:exp-governance-work-with-strategies.adoc[]. + +== See Also + +* xref:exp-policies-overview.adoc[] +* xref:exp-policies-apply-manage.adoc[] +* xref:exp-policies-activity-log.adoc[] +* xref:exp-policies-provider-reference.adoc[] +* xref:exp-governance-work-with-strategies.adoc[] diff --git a/modules/ROOT/pages/exp-providers-manage.adoc b/modules/ROOT/pages/exp-providers-manage.adoc index 2ab7de7c4..4e5a4f3de 100644 --- a/modules/ROOT/pages/exp-providers-manage.adoc +++ b/modules/ROOT/pages/exp-providers-manage.adoc @@ -100,7 +100,7 @@ When scanning Kong, the enhanced experience discovers gateway-level plugin infor *Akamai API Security* is available only when your administrator has enabled the feature for your organization. When enabled, it appears in the *Not Connected* section of the Providers sidebar. ==== -Of these providers, the API gateway providers Google (Apigee), Kong, and Microsoft (Azure API Management) support policy write. APIs discovered from a scanner that has only read credentials appear as *Read-Only*, and policy actions are unavailable until you add write credentials to the scanner. For provider-specific read and write scopes, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. +Of these providers, the API gateway providers Google (Apigee), Kong, and Microsoft (Azure API Management) support policy write. APIs discovered by a connection that has only read access to the provider appear as *Read-Only*, and policy actions are unavailable until the connection's identity is granted the provider's write scope. For provider-specific read and write scopes, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. The specific providers available depend on your organization's enabled products and enhanced experience configuration. diff --git a/modules/ROOT/pages/exp-scanners-add-from-providers.adoc b/modules/ROOT/pages/exp-scanners-add-from-providers.adoc index 63f5258d2..d8e071c96 100644 --- a/modules/ROOT/pages/exp-scanners-add-from-providers.adoc +++ b/modules/ROOT/pages/exp-scanners-add-from-providers.adoc @@ -40,7 +40,7 @@ When a scanner is enabled, it can discover and read policies from API configurat * Policy write + -For API gateway providers that support policy write (Azure API Management, Google Apigee, and Kong Gateway), a scanner configured with write credentials lets you apply, enable, disable, and delete policies on discovered APIs directly from Anypoint. For write scopes and requirements, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. +For API gateway providers that support policy write (Azure API Management, Google Apigee, and Kong Gateway), a scanner connection whose credentials carry the provider's write scope lets you apply, enable, disable, and remove policies on discovered APIs directly from Anypoint. For write scopes and requirements, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. == Workflow Entry Points for Adding a Scanner @@ -86,7 +86,7 @@ If some environments show no policy binding, select *Check again* to retry the p Regardless of entry point, adding a scanner establishes trust and scope. You specify which provider platform to reach, how the system authenticates, and how you validate connectivity. You also name and schedule the scanner—or configure another trigger—so discovery runs on the cadence your team expects. Saving the configuration activates the scanner for the catalogs and features your administrator enabled. -For API gateway providers that support policy write, supply credentials that include the provider's write scope during setup. Discovery credentials alone enable read-only access: the scanner discovers and reads policies, but the affected APIs appear as *Read-Only* and policy actions are unavailable until you add write credentials. For provider-specific read and write scopes, see xref:exp-scanners-prerequisites-reference.adoc[]. +For API gateway providers that support policy write, supply connection credentials that include the provider's write scope during setup. If the connection has only read access, the scanner discovers and reads policies, but the affected APIs appear as *Read-Only* and policy actions are unavailable until the connection's identity is granted the provider's write scope. For provider-specific read and write scopes, see xref:exp-scanners-prerequisites-reference.adoc[]. == After the Scanner Runs diff --git a/modules/ROOT/pages/exp-scanners-manage.adoc b/modules/ROOT/pages/exp-scanners-manage.adoc index f1e6991da..eb60a2fc5 100644 --- a/modules/ROOT/pages/exp-scanners-manage.adoc +++ b/modules/ROOT/pages/exp-scanners-manage.adoc @@ -21,14 +21,14 @@ Re-enable scheduled scanning after a pause. + Change names, descriptions, credentials, provider scope, or scan-related settings your product exposes, then save, so future runs use the new definition. + -For API gateway providers that support policy write, adding write credentials to a read-only scanner enables policy write (apply, enable, disable, and delete) on the scanner's discovered APIs. Read and write credentials are configured separately. For provider-specific write scopes, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. +For API gateway providers that support policy write, granting the scanner connection's identity the provider's write scope enables policy write (apply, enable, disable, and remove) on the scanner's discovered APIs. Policy write reuses the same connection you use for scanning. For provider-specific write scopes, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. * *Delete Scanner* + Remove the scanner from *Providers* when the provider link is no longer authorized or useful. Consider the impact on discovered services in *Portfolio* and on dependent teams before you delete the scanner. + NOTE: When you delete an Akamai API Security scanner, the system attempts to remove the Akamai correlation policy from the scanner's environments. If the removal fails, the correlation policy may remain applied; check *Automated Policies* to verify. Discovered services remain in your portfolio regardless. + -NOTE: Deleting a write-enabled API gateway scanner doesn't remove policies that were previously applied to the provider's APIs through policy write. Those policies remain active on the gateway. Anypoint stops tracking them, and you lose the ability to manage them from Anypoint until you reconnect a scanner with write credentials. +NOTE: Deleting an API gateway scanner used for policy write doesn't remove policies that were previously applied to the provider's APIs through policy write. Those policies remain active on the gateway. Anypoint stops tracking them, and you lose the ability to manage them from Anypoint until you reconnect a scanner with the provider's write scope. == See Also diff --git a/modules/ROOT/pages/exp-scanners-prerequisites-reference.adoc b/modules/ROOT/pages/exp-scanners-prerequisites-reference.adoc index 46962a38c..a8c1fa093 100644 --- a/modules/ROOT/pages/exp-scanners-prerequisites-reference.adoc +++ b/modules/ROOT/pages/exp-scanners-prerequisites-reference.adoc @@ -3,7 +3,7 @@ Scanner prerequisites by provider help you confirm required roles, credentials, and permissions before creating a scanner. Use this reference to prevent connection test failures and incomplete discovery by validating provider-specific access in advance. Each scanner also requires Exchange Administrator permission and the correct business group context. -For API gateway providers that support policy write, discovery credentials aren't enough to apply policies. Supply credentials with the write scope for the gateway, and review the additional write prerequisites in xref:_policy_write_prerequisites[]. Write scopes are noted in the matrix as *Write scope (policy apply)*. +For API gateway providers that support policy write, discovery access alone isn't enough to apply policies. Policy write reuses the same scanner connection you configure here, so the connection's credentials must also carry the provider's write permissions (write scope). Review the additional write prerequisites in xref:_policy_write_prerequisites[]. Write scopes are noted in the matrix as *Write scope (policy apply)*. == Before You Begin @@ -187,7 +187,7 @@ a| * *Apply read scope:* Admin API read permission required to read policy in target environments -*Write scope (policy apply):* Admin API write permission required to apply, enable, disable, or delete policy in target environments +*Write scope (policy apply):* Admin API write permission required to apply, enable, disable, or remove policy in target environments | Akamai Security | API Security @@ -235,12 +235,19 @@ a| == Policy Write Prerequisites -Policy write lets you apply, enable, disable, and delete policies on connected third-party gateway APIs directly from Anypoint, with no Anypoint gateway in the request path. Policy write is available for API gateway providers only: Azure API Management, Google Apigee, and Kong Gateway. Agent, API Security, and MCP scanners don't support policy write. +Policy write lets you apply, enable, disable, and remove policies on connected third-party gateway APIs directly from Anypoint, with no Anypoint gateway in the request path. Policy write is available for API gateway providers only: Azure API Management, Google Apigee, and Kong Gateway. Agent, API Security, and MCP scanners don't support policy write. -Before you can write policies, confirm these prerequisites in addition to the discovery prerequisites in the matrix: +// TODO(W-23907611): Credential-model discrepancy to confirm with PM/eng. This section was +// grounded in the Omni-app code (separate read vs. write credentials, an explicit Read-Only +// state until write credentials are added). The External Policies Documentation Guide instead +// describes policy write as reusing the SAME scanner connection, with write gated only by the +// permissions granted to that connection's identity on the provider. The text below follows +// the guide (single reused connection). Confirm which model ships before publishing. -* *Write credentials:* Provide credentials that have the write scope for the target gateway. Configure read and write credentials separately in the scanner. Read-only credentials allow discovery only. -* *Write scope:* The write scope covers enabling, disabling, and deleting existing vendor-native policies, and creating and editing universal (canonical) policies, at both the instance and service scope. Creating and editing native vendor policies isn't supported. +Policy write reuses the same connection you configure for scanning; there's no separate policy-write connection. Before you can write policies, confirm these prerequisites in addition to the discovery prerequisites in the matrix: + +* *Write permissions on the connection:* The scanner connection's identity must have the provider's write scope, not just read access. A connection with read-only access to the provider can discover and read policies, but policy actions remain unavailable. +* *Write scope:* The write scope covers enabling, disabling, and removing existing vendor-native policies, and creating and editing universal (canonical) policies, at both the instance and service scope. Creating and editing native vendor policies isn't supported. * *Provider write permissions:* Grant the provider-specific *Write scope (policy apply)* listed for each API gateway provider in the xref:_scanner_prerequisite_matrix[]. The following table summarizes the read and write scopes for each API gateway provider that supports policy write. @@ -273,11 +280,14 @@ The following table summarizes the read and write scopes for each API gateway pr === Read-Only APIs -When a scanner has only read credentials for a gateway, its API instances appear as *Read-Only* and policy actions are unavailable. To enable policy write, update the scanner with write credentials by using the credential update link on the API instance. +When a scanner connection has only read access to a gateway, its API instances appear as *Read-Only* and policy actions are unavailable. To enable policy write, grant the connection's identity the provider's write scope, then update the connection from the API instance. + +=== Tracked Applies -=== Tracked Applies and Audit Trail +Every policy write is tracked and records an applied or failed state alongside the scanner-read configuration. Anypoint logs each write as compliance evidence, including the policy, the target, the vendor, the timestamp, and the result. To follow the outcome of a policy operation, use the *Activity log* tab on the API instance. See xref:exp-policies-activity-log.adoc[]. -Every policy write is tracked and records an applied or failed state alongside the scanner-read configuration. Anypoint also logs each write as compliance evidence, including who made the change, the policy, the target, the vendor, the timestamp, and the result. +// NOTE(W-23907611): The Activity log records action, policy, status, and time only — it does +// not record an actor ("who"). Do not describe it as a full who-did-what audit trail. [NOTE] Anypoint doesn't manage vendor policy lifecycle, versioning, or CI/CD. diff --git a/modules/ROOT/pages/exp-scanners-view-details.adoc b/modules/ROOT/pages/exp-scanners-view-details.adoc index fefd49baf..e934f3531 100644 --- a/modules/ROOT/pages/exp-scanners-view-details.adoc +++ b/modules/ROOT/pages/exp-scanners-view-details.adoc @@ -39,7 +39,7 @@ For import scanners, this tab reflects discovered services imported by scan runs Use *Settings* to review and update scanner configuration values, such as provider connection details, run schedule, and scanner metadata. You can also delete the scanner from this tab. -For API gateway providers that support policy write, the scanner stores read and write credentials separately. Read credentials enable discovery and policy read; write credentials enable policy write (apply, enable, disable, and delete). Use *Settings* to add or update write credentials—for example, to change an API scanner from read-only to write-enabled. For provider-specific read and write scopes, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. +For API gateway providers that support policy write, the scanner uses a single connection, and what you can do depends on the permissions granted to that connection's identity on the provider. Read access enables discovery and policy read; the provider's write scope additionally enables policy write (apply, enable, disable, and remove). Use *Settings* to review and update the connection credentials—for example, after you grant the connection the provider's write scope. For provider-specific read and write scopes, see xref:exp-scanners-prerequisites-reference.adoc#_policy_write_prerequisites[Policy Write Prerequisites]. == Tab Content by Scanner Type @@ -50,7 +50,7 @@ Akamai API Security scanner:: Shows correlation and governance enrichment activity for existing services, including risk and findings signals. API gateway scanner:: -For providers that support policy write (Azure API Management, Google Apigee, and Kong Gateway), the *Settings* tab additionally supports configuring separate write credentials to enable policy write on discovered APIs. +For providers that support policy write (Azure API Management, Google Apigee, and Kong Gateway), the *Settings* tab is where you review and update the connection credentials used for policy write on discovered APIs. == See Also diff --git a/modules/ROOT/pages/exp-services-view-details.adoc b/modules/ROOT/pages/exp-services-view-details.adoc index b164d1f21..95624b787 100644 --- a/modules/ROOT/pages/exp-services-view-details.adoc +++ b/modules/ROOT/pages/exp-services-view-details.adoc @@ -41,7 +41,7 @@ tab can differ by service type and release. For end-to-end portfolio tasks that |Yes |Yes |Yes |Each Model Proxy is exactly one instance so there is no *Instances* tab. |No |*Policies* -|Governance policies attached to the service or its instances (access, data, performance, compliance, and related domains your organization uses). For APIs discovered by scanners, this tab shows read policies from Amazon API Gateway, Google Apigee, Azure API Management, and Kong Gateway. If the instance uses a Kong gateway, the listed policies are gateway-level policies (plugins). Other service-level policies (plugins) can also apply. On supported gateways, you can also manage native policies from this tab. See xref:exp-governance-policy-library-apply.adoc[]. +|Governance policies attached to the service or its instances (access, data, performance, compliance, and related domains your organization uses). For APIs discovered by scanners, this tab shows read policies from Amazon API Gateway, Google Apigee, Azure API Management, and Kong Gateway. If the instance uses a Kong gateway, the listed policies are gateway-level policies (plugins). Other service-level policies (plugins) can also apply. On supported gateways, you can also manage native policies from this tab. See xref:exp-policies-apply-manage.adoc[]. |Yes |Yes |Yes |Yes |No |*Monitoring* @@ -66,6 +66,7 @@ tab can differ by service type and release. For end-to-end portfolio tasks that . Use the search box to find the service by name or description, or scan the list or grid. . Select the service card to open its detail page. +[[view-read-policies-discovered-by-scanners]] == View Read Policies Discovered by Scanners If a provider scanner has policy-read scopes configured, the *Policies* tab shows discovered policy entries for that API instance. The tab lists policy names and mapped governance context, such as category and apply level, when the provider returns that metadata. For providers that expose policy status, the tab also shows whether a policy is enabled so teams can validate scanner coverage and conformance inputs from the latest scan snapshot. @@ -77,13 +78,15 @@ If a provider scanner has policy-read scopes configured, the *Policies* tab show Policy visibility depends on the last successful scanner run, not on a live provider query. If required provider scopes or roles are missing, policy results can be incomplete or unavailable. Policy fields such as status, apply level, and detail can vary by provider. If expected policies are missing, check scanner run status and history in *Providers*. +Reading policies is view-only. To create, edit, enable, disable, or remove policies on Anypoint and external gateway providers from this tab, see xref:exp-policies-apply-manage.adoc[] and xref:exp-policies-overview.adoc[]. + == Manage Native Policies -On supported gateways, the *Policies* tab also lets you manage the native policies applied to an instance. Depending on the gateway and your permissions, you can edit, delete, or enable and disable a policy directly from this tab. Policies that are outside your instance's scope appear in a read-only state, without edit, delete, or enable/disable actions. +On supported gateways, the *Policies* tab also lets you manage the native policies applied to an instance. Depending on the gateway and your permissions, you can edit, remove, or enable and disable a policy directly from this tab. Policies that are outside your instance's scope appear in a read-only (view-only) state, without edit, remove, or enable/disable actions. -Policy write actions are tracked. To confirm whether an apply, edit, enable, disable, or delete completed on the gateway, review the *Activity log* tab of the instance detail page. See xref:exp-governance-policy-library-apply.adoc#track-policy-changes[Track Policy Changes]. +Policy write actions are tracked. To confirm whether an apply, edit, enable, disable, or remove completed on the gateway, review the *Activity log* tab of the instance detail page. See xref:exp-policies-activity-log.adoc[]. -For the full apply and management workflow, see xref:exp-governance-policy-library-apply.adoc[]. +For the full apply and management workflow, see xref:exp-policies-apply-manage.adoc[]. == See Also From e9452c480256f7c6f0b6a3fde70fbe64827a88ed Mon Sep 17 00:00:00 2001 From: Luana Dos Santos <84200607+luanamulesoft@users.noreply.github.com> Date: Fri, 28 Aug 2026 14:52:34 -0300 Subject: [PATCH 6/9] Update exp-policies-apply-manage.adoc --- modules/ROOT/pages/exp-policies-apply-manage.adoc | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/modules/ROOT/pages/exp-policies-apply-manage.adoc b/modules/ROOT/pages/exp-policies-apply-manage.adoc index bb0ea0cbd..31a4138f5 100644 --- a/modules/ROOT/pages/exp-policies-apply-manage.adoc +++ b/modules/ROOT/pages/exp-policies-apply-manage.adoc @@ -36,9 +36,7 @@ To apply a universal policy across multiple providers at once, use the *Policy L Having permissions is necessary but not sufficient to edit a policy. Anypoint supports editing the curated set of policies that back the universal use cases, plus several additional native Kong policies (see xref:exp-policies-universal.adoc[]); other recognized policies are view-only. Native policies created from a universal use case are editable like any other supported native policy. When *Edit Configuration* is unavailable, the UI explains why. Common reasons include: * Anypoint doesn't recognize the policy's template, or doesn't yet support managing policies with its schema. -// TODO(W-23907611): SME (fedebrasburg) notes this case is an internal error the user can't act on; -// confirm with PM/eng whether to document it here or direct users to open a support case instead. -* The policy's configuration doesn't match its expected schema. +* The policy's configuration doesn't match its expected schema. To resolve this issue, open a support case. * The policy is scoped above the instance rather than to it. * The policy has conditional rules. * The policy has no provider reference. From ae4be75f2b9aee7453b765ba53ef7e63c2cba8b1 Mon Sep 17 00:00:00 2001 From: Luana Dos Santos <84200607+luanamulesoft@users.noreply.github.com> Date: Fri, 28 Aug 2026 15:39:04 -0300 Subject: [PATCH 7/9] Update exp-policies-overview.adoc --- modules/ROOT/pages/exp-policies-overview.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/exp-policies-overview.adoc b/modules/ROOT/pages/exp-policies-overview.adoc index a69b610a7..c988f88dc 100644 --- a/modules/ROOT/pages/exp-policies-overview.adoc +++ b/modules/ROOT/pages/exp-policies-overview.adoc @@ -28,7 +28,7 @@ You can remove, enable, and disable policies more broadly than you can edit them == How Policy Operations Work -Every policy change on an external provider, such as apply, edit, enable, disable, or remove, runs asynchronously. When you trigger an action, Anypoint accepts the request and performs the work on the provider in the background, then reconciles its view of the provider's state. An accepted request isn't the same as an applied policy, so to confirm what actually happened, open the *Activity log* tab for the API instance. See xref:exp-policies-activity-log.adoc[]. +Every policy change on an external provider, such as apply, edit, enable, disable, or remove, runs asynchronously: Anypoint accepts the request and performs the work on the provider in the background. Because an accepted request isn't the same as an applied policy, confirm the outcome in the Activity log tab for the API instance. See xref:exp-policies-activity-log.adoc[]. == See Also From a85d10642cf42e61b51cc40e478594db933f4e69 Mon Sep 17 00:00:00 2001 From: Luana Dos Santos Date: Fri, 28 Aug 2026 16:13:18 -0300 Subject: [PATCH 8/9] fixed apply policy steps --- .../exp-governance-policy-library-apply.adoc | 56 +++++++++++++------ 1 file changed, 38 insertions(+), 18 deletions(-) diff --git a/modules/ROOT/pages/exp-governance-policy-library-apply.adoc b/modules/ROOT/pages/exp-governance-policy-library-apply.adoc index c721b9fcb..94e1be81f 100644 --- a/modules/ROOT/pages/exp-governance-policy-library-apply.adoc +++ b/modules/ROOT/pages/exp-governance-policy-library-apply.adoc @@ -7,14 +7,17 @@ // management workflow, activity tracking, and per-provider support live in the exp-policies-* // topics; keep this topic thin and link out rather than duplicating that content. // Open items to confirm with the PM before removing this DRAFT banner: -// 1. The Policy Library location in the Governance UI -// (*Governance* > *Governance Strategies* > *Policy Library*). -// 2. The category filter labels shown in the Policy Library. +// 1. Entry points and wizard step labels verified against mulesoft-omni-app source +// (Governance Strategies > Add Strategy > Apply Policy, and the instance-level +// Apply Policy action that opens the Policy Library); confirm with PM. +// 2. Category filter labels verified against source (Access and Security, +// Compliance and Observability, Data Privacy and Integrity, Performance and Cost, +// plus the All Domains and Custom filters); confirm with PM. // 3. Human-readable required permission/role names for policy write actions. -The Policy Library is the Governance entry point for applying *universal policies*. A universal policy expresses a policy once and applies it as the correct vendor-native policy on each supported gateway, so you can enforce consistent controls across MuleSoft, Google Apigee, Kong Gateway, and Azure API Management without authoring a policy per gateway. +Governance provides two entry points for applying *universal policies*: the *Apply Policy* flow on the Governance Strategies page, and the *Policy Library* on an individual API instance. A universal policy expresses a policy once and applies it as the correct vendor-native policy on each supported gateway, so you can enforce consistent controls across MuleSoft, Google Apigee, Kong Gateway, and Azure API Management without authoring a policy per gateway. -This topic covers the Governance doorway and the apply flow. For the full universal policy model, the apply and management workflow, activity tracking, and per-provider support, see xref:exp-policies-overview.adoc[] and xref:exp-policies-universal.adoc[]. +This topic covers both entry points and the apply flow. For the full universal policy model, the apply and management workflow, activity tracking, and per-provider support, see xref:exp-policies-overview.adoc[] and xref:exp-policies-universal.adoc[]. == Before You Begin @@ -37,25 +40,42 @@ For more information, see xref:exp-home-start.adoc#permissions[Enhanced Experien Policy write actions respect your permissions. If you don't have permission for an action, that action is unavailable and the experience explains that the action isn't permitted. If the platform can't verify your permissions for an instance, the actions remain available and the gateway enforces authorization when you submit the request. See xref:exp-policies-apply-manage.adoc[]. ==== -== Browse the Policy Library +== Browse Universal Policies -Browse the Policy Library from *Governance* > *Governance Strategies* > *Policy Library*. Each policy appears with its name, category, and a short description of what it enforces. +You can start applying a universal policy from two places: -You can filter policies by category: +* On the Governance Strategies page, select *Add Strategy*, then *Apply Policy*. +* On an API instance, select the *Apply Policy* action to open the Policy Library. -* *Access & Security* -* *Performance & Cost* -* *Quality of Service* -* *Data Privacy & Integrity* -* *Compliance & Observability* +Each policy appears with its name, category, and a short description of what it enforces. You can filter policies by category: + +* *Access and Security* +* *Compliance and Observability* +* *Data Privacy and Integrity* +* *Performance and Cost* + +Select *All Domains* to see every policy, or *Custom* to see policies that don't fall into the preceding categories. Each filter shows the number of policies it contains. == Apply a Universal Policy -. Go to *Governance* > *Governance Strategies* > *Policy Library*. -. Select the policy you want to apply. -. Configure the policy parameters. Required and optional fields vary by policy type. -. Select the API instances where you want to apply the policy. -. Review the summary, then apply the policy. +The apply steps vary depending on where you start. + +=== From the Governance Strategies Page + +. On the Governance Strategies page, select *Add Strategy*, then *Apply Policy*. +. On the *Select Policy* step, select the policy you want to apply. +. On the *Configure Policy* step, set the policy parameters. Required and optional fields vary by policy type. +. On the *Scope* step, choose whether to apply the policy globally or to specific API instances. +. On the *Name & Description* step, name the policy. This step appears only when you apply the policy globally. +. On the *Review* step, review the summary, then apply the policy. + +=== From an API Instance + +. On the API instance, select the *Apply Policy* action to open the Policy Library. +. On the *Select Policy* step, select the policy you want to apply. +. On the *Configure Policy* step, set the policy parameters. Required and optional fields vary by policy type. +. On the *Select Instances* step, select the API instances where you want to apply the policy. +. On the *Review & Apply* step, review the summary, then apply the policy. When you apply a policy, the platform validates it against your governance configuration and then creates the corresponding native policy on each selected instance's gateway. From afc87853dbb59dc4420fdb6aa7b61a951a047252 Mon Sep 17 00:00:00 2001 From: Luana Dos Santos Date: Fri, 28 Aug 2026 16:15:46 -0300 Subject: [PATCH 9/9] changed title --- modules/ROOT/pages/exp-governance-policy-library-apply.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/exp-governance-policy-library-apply.adoc b/modules/ROOT/pages/exp-governance-policy-library-apply.adoc index 94e1be81f..17d3366bb 100644 --- a/modules/ROOT/pages/exp-governance-policy-library-apply.adoc +++ b/modules/ROOT/pages/exp-governance-policy-library-apply.adoc @@ -1,4 +1,4 @@ -= Apply Universal Policies from the Policy Library += Apply Universal Policies :keywords: policy library, universal policies, canonical policies, governance policies, apply policy, policy catalog // DRAFT: Policy Write (MS2026-08-R2 / Dreamforce). Tracked in W-23907611.