Merge pull request #311760 from dlepow/shgwauth

[APIM] Workload identity auth for SHGW

Author: ttorble

articles/api-management/TOC.yml

@@ -403,12 +403,20 @@
       href: how-to-configure-local-metrics-logs.md
     - name: Enable Dapr support on self-hosted gateway
       href: self-hosted-gateway-enable-dapr.md
-    - name: Use Microsoft Entra authentication on self-hosted gateway
-      href: self-hosted-gateway-enable-azure-ad.md
-  - name: Run self-hosted gateway in production
-    href: how-to-self-hosted-gateway-on-kubernetes-in-production.md
-  - name: Self-hosted gateway support policy
-    href: self-hosted-gateway-support-policies.md
+    - name: Configure authentication to cloud instance
+      items:
+        - name: Self-hosted gateway authentication options
+          href: self-hosted-gateway-authentication-options.md
+        - name: Authenticate with Microsoft Entra ID - workload identity
+          href: self-hosted-gateway-enable-workload-identity.md
+        - name: Authenticate with Microsoft Entra ID - client secret
+          href: self-hosted-gateway-enable-azure-ad.md
+        - name: Authenticate with an access token
+          href: self-hosted-gateway-default-authentication.md  
+    - name: Run self-hosted gateway in production
+      href: how-to-self-hosted-gateway-on-kubernetes-in-production.md
+    - name: Self-hosted gateway support policy
+      href: self-hosted-gateway-support-policies.md
 - name: Developer portal and publishing
   items:
   - name: Manage users, groups, and subscriptions

articles/api-management/how-to-deploy-self-hosted-gateway-azure-arc.md

@@ -4,7 +4,9 @@ description: Enable Azure Arc to deploy your self-hosted Azure API Management ga
 author: dlepow
 ms.author: danlep
 ms.service: azure-api-management
-ms.custom: devx-track-azurecli
+ms.custom: 
+  - devx-track-azurecli
+  - references_regions
 ms.topic: how-to 
 ms.date: 10/06/2025
 ---
@@ -42,6 +44,8 @@ Deploying the API Management gateway on an Azure Arc-enabled Kubernetes cluster
 
 ## Deploy the API Management gateway extension using Azure CLI
 
+[!INCLUDE [api-management-self-hosted-gateway-authentication](../../includes/api-management-self-hosted-gateway-authentication.md)]
+
 1. In the Azure portal, navigate to your API Management instance.
 1. Select **Deployment + infrastructure** > **Gateways** from the side navigation menu.
 1. Select and open your provisioned gateway resource from the list.
@@ -125,3 +129,4 @@ To enable monitoring of the self-hosted gateway, configure the following Log Ana
 * Learn more about [Azure Arc-enabled Kubernetes](/azure/azure-arc/kubernetes/overview).
 * Learn more about guidance to [run the self-hosted gateway on Kubernetes in production](how-to-self-hosted-gateway-on-kubernetes-in-production.md).
 * For configuration options, see the [self-hosted gateway extension reference](self-hosted-gateway-arc-reference.md).
+`

articles/api-management/how-to-deploy-self-hosted-gateway-azure-kubernetes-service.md

@@ -25,6 +25,8 @@ This article provides the steps for deploying self-hosted gateway component of A
 
 ## Deploy the self-hosted gateway to AKS
 
+[!INCLUDE [api-management-self-hosted-gateway-authentication](../../includes/api-management-self-hosted-gateway-authentication.md)]
+
 1. Select **Gateways** from under **Deployment and infrastructure**.
 1. Select the self-hosted gateway resource you intend to deploy.
 1. Select **Deployment**.

articles/api-management/how-to-deploy-self-hosted-gateway-kubernetes-helm.md

@@ -48,11 +48,13 @@ This article provides the steps for deploying self-hosted gateway component of A
    ```console
    $ helm search repo azure-apim-gateway
    NAME                                            CHART VERSION   APP VERSION     DESCRIPTION
-   azure-apim-gateway/azure-api-management-gateway 1.0.0           2.0.0           A Helm chart to deploy an Azure API Management ...
+   azure-apim-gateway/azure-api-management-gateway 1.15.0           2.11.0           A Helm chart to deploy an Azure API Management ...
    ```
 
 ## Deploy the self-hosted gateway to Kubernetes
 
+[!INCLUDE [api-management-self-hosted-gateway-authentication](../../includes/api-management-self-hosted-gateway-authentication.md)]
+
 1. Select **Gateways** from under **Deployment and infrastructure**.
 2. Select the self-hosted gateway resource you intend to deploy.
 3. Select **Deployment**.
@@ -77,26 +79,6 @@ This article provides the steps for deploying self-hosted gateway component of A
    > 
    > For example, you can expose it through a load balancer by adding `--set service.type=LoadBalancer`
 
-8. Run the following command to check the gateway pod is running. Your pod name will be different.
-
-   ```console
-   kubectl get pods
-   NAME                                           READY     STATUS    RESTARTS   AGE
-   azure-api-management-gateway-59f5fb94c-s9stz   1/1       Running   0          1m
-   ```
-
-9. Run the following command to check the gateway service is running. Your service name and IP addresses will be different.
-
-    ```console
-    kubectl get services
-    NAME                           TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)               AGE
-    azure-api-management-gateway   ClusterIP   10.0.229.55     <none>        8080/TCP,8081/TCP     1m
-    ```
-
-10. Return to the Azure portal and confirm that gateway node you deployed is reporting healthy status.
-
-> [!TIP]
-> Use `kubectl logs <gateway-pod-name>` command to view a snapshot of self-hosted gateway log.
 
 ## Related content
 

articles/api-management/how-to-deploy-self-hosted-gateway-kubernetes-opentelemetry.md

@@ -147,6 +147,8 @@ With our OpenTelemetry Collector installed, we can now deploy the self-hosted ga
 
 In this section, we will deploy the self-hosted gateway to our cluster with Helm and configure it to send OpenTelemetry metrics to the OpenTelemetry Collector.
 
+[!INCLUDE [api-management-self-hosted-gateway-authentication](../../includes/api-management-self-hosted-gateway-authentication.md)]
+
 1. Install the Helm chart and configure it to use OpenTelemetry metrics:
 
    ```console

articles/api-management/how-to-deploy-self-hosted-gateway-kubernetes.md

@@ -30,8 +30,7 @@ This article describes the steps for deploying the self-hosted gateway component
 
 ## Deploy to Kubernetes
 
-> [!TIP]
-> The following steps deploy the self-hosted gateway to Kubernetes and enable authentication to the API Management instance by using a gateway access token (authentication key). You can also deploy the self-hosted gateway to Kubernetes and enable authentication to the API Management instance by using [Microsoft Entra ID](self-hosted-gateway-enable-azure-ad.md).
+[!INCLUDE [api-management-self-hosted-gateway-authentication](../../includes/api-management-self-hosted-gateway-authentication.md)]
 
 1. Select **Gateways** under **Deployment and infrastructure**.
 1. Select the self-hosted gateway resource that you want to deploy.

articles/api-management/how-to-self-hosted-gateway-on-kubernetes-in-production.md

@@ -19,13 +19,15 @@ In order to run the self-hosted gateway in production, there are various aspects
 
 This article provides guidance on how to run [self-hosted gateway](./self-hosted-gateway-overview.md) on Kubernetes for production workloads to ensure that it will run smoothly and reliably.
 
-## Access token
+## Authentication
+
+By default, an access token (also called an authentication key) is used by the self-hosted gateway to authenticate with the API Management instance.
+
 Without a valid access token, a self-hosted gateway can't access and download configuration data from the endpoint of the associated API Management service. The access token can be valid for a maximum of 30 days. It must be regenerated, and the cluster configured with a fresh token, either manually or via automation before it expires.
 
 When you're automating token refresh, use [this management API operation](/rest/api/apimanagement/current-ga/gateway/generate-token) to generate a new token. For information on managing Kubernetes secrets, see the [Kubernetes website](https://kubernetes.io/docs/concepts/configuration/secret).
 
-> [!TIP]
-> You can also deploy the self-hosted gateway to Kubernetes and enable authentication to the API Management instance by using [Microsoft Entra ID](self-hosted-gateway-enable-azure-ad.md).
+You can also deploy the self-hosted gateway to Kubernetes and enable authentication to the API Management instance by using Microsoft Entra ID. For more information and considerations, see [Self-hosted gateway authentication options](self-hosted-gateway-authentication-options.md).
 
 ## Autoscaling
 
@@ -48,7 +50,7 @@ Kubernetes allows you to autoscale the self-hosted gateway based on resource usa
 An alternative is to use Kubernetes Event-driven Autoscaling (KEDA) allowing you to scale workloads based on a [variety of scalers](https://keda.sh/docs/latest/scalers/), including CPU and memory.
 
 > [!TIP]
-> If you are already using KEDA to scale other workloads, we recommend using KEDA as a unified app autoscaler. If that is not the case, then we strongly suggest to rely on the native Kubernetes functionality through Horizontal Pod Autoscaler.
+> If you are already using KEDA to scale other workloads, we recommend using KEDA as a unified app autoscaler. If that is not the case, then we strongly suggest relying on the native Kubernetes functionality through Horizontal Pod Autoscaler.
 
 ### Traffic-based autoscaling
 

articles/api-management/self-hosted-gateway-authentication-options.md

@@ -0,0 +1,31 @@
+---
+title: Authentication Options for Self-hosted Gateway - Azure API Management
+description: Options for the Azure API Management self-hosted gateway to authenticate to the cloud-based API Management instance.
+services: api-management
+author: dlepow
+
+ms.service: azure-api-management
+ms.topic: concept-article
+ms.date: 02/19/2026
+ms.author: danlep
+---
+
+# Self-hosted gateway authentication options
+
+The gateway container's [configuration settings](self-hosted-gateway-settings-reference.md) provide options for authenticating the connection between the self-hosted gateway and the cloud-based API Management instance's configuration endpoint.
+
+## Options and considerations
+
+The following table lists authentication options for the self-hosted gateway and considerations for each option. The linked articles provide step-by-step instructions for how to configure each authentication method.
+
+|Option  |Considerations  |
+|---------|---------|
+| [Microsoft Entra ID workload identity authentication](self-hosted-gateway-enable-workload-identity.md)   | No secrets or certificates to manage - uses federated identity credentials.<br/><br/>Automatic token rotation with short-lived tokens.<br/><br/>Native integration with Azure Kubernetes Service.        |
+| [Microsoft Entra ID authentication with client secret](self-hosted-gateway-enable-azure-ad.md)   | Configure Microsoft Entra apps with client secrets or certificates.<br/><br/>Manage access per app with custom role assignments.<br/><br/>Configure secret expiration times per your organization's policies.<br/><br/>Use standard Microsoft Entra procedures to rotate secrets.        |
+| [Access token](self-hosted-gateway-default-authentication.md) (also called *gateway token* or an *authentication key*)    |  Token expires at least every 30 days and must be renewed.<br/><br/>Backed by a gateway key that you can rotate independently.<br/><br/>Regenerating the gateway key invalidates all access tokens.<br/><br/>System events are generated when a self-hosted gateway access token is near expiration or expires.      |
+
+## Related content
+
+- Learn more about the API Management [self-hosted gateway](self-hosted-gateway-overview.md).
+- Learn more about [Microsoft Entra workload identity for AKS](/azure/aks/workload-identity-overview).
+- Learn more about guidance for [running the self-hosted gateway on Kubernetes in production](how-to-self-hosted-gateway-on-kubernetes-in-production.md).