Skip to content

Commit 56f38a1

Browse files
ttorblettorble
authored
Merge pull request #237925 from dlepow/shgwaad
[APIM] Azure AD authentication by SHGW
2 parents 67234d2 + 94ed078 commit 56f38a1

File tree

6 files changed

+304
-29
lines changed

6 files changed

+304
-29
lines changed

‎articles/api-management/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -208,6 +208,8 @@
208208
href: how-to-configure-local-metrics-logs.md
209209
- name: Enable Dapr support on self-hosted gateway
210210
href: self-hosted-gateway-enable-dapr.md
211+
- name: Use Azure AD authentication on self-hosted gateway
212+
href: self-hosted-gateway-enable-azure-ad.md
211213
- name: Guidance for running on Kubernetes
212214
href: how-to-self-hosted-gateway-on-kubernetes-in-production.md
213215
- name: Migrate to self-hosted gateway v2

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

Lines changed: 5 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ ms.service: api-management
77
ms.workload: mobile
88
ms.topic: article
99
ms.author: danlep
10-
ms.date: 05/25/2021
10+
ms.date: 05/22/2023
1111
---
1212
# Deploy a self-hosted gateway to Kubernetes with YAML
1313

@@ -30,6 +30,9 @@ This article describes the steps for deploying the self-hosted gateway component
3030

3131
## Deploy to Kubernetes
3232

33+
> [!TIP]
34+
> 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 [Azure AD](self-hosted-gateway-enable-azure-ad.md).
35+
3336
1. Select **Gateways** under **Deployment and infrastructure**.
3437
2. Select the self-hosted gateway resource that you want to deploy.
3538
3. Select **Deployment**.
@@ -40,34 +43,8 @@ This article describes the steps for deploying the self-hosted gateway component
4043
8. When using Azure Kubernetes Service (AKS), run `az aks get-credentials --resource-group <resource-group-name> --name <resource-name> --admin` in a new terminal session.
4144
9. Run the commands to create the necessary Kubernetes objects in the [default namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) and start self-hosted gateway pods from the [container image](https://aka.ms/apim/shgw/registry-portal) downloaded from the Microsoft Artifact Registry.
4245
- The first step creates a Kubernetes secret that contains the access token generated in step 4. Next, it creates a Kubernetes deployment for the self-hosted gateway which uses a ConfigMap with the configuration of the gateway.
43-
10. Run the following command to check if the deployment succeeded. Note that it might take a little time for all the objects to be created and for the pods to initialize.
44-
45-
```console
46-
kubectl get deployments
47-
```
48-
It should return
49-
```console
50-
NAME READY UP-TO-DATE AVAILABLE AGE
51-
<gateway-name> 1/1 1 1 18s
52-
```
53-
11. Run the following command to check if the service was successfully created. Note that your service IPs and ports will be different.
5446

55-
```console
56-
kubectl get services
57-
```
58-
It should return
59-
```console
60-
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
61-
<gateway-name> LoadBalancer 10.99.236.168 <pending> 80:31620/TCP,443:30456/TCP 9m1s
62-
```
63-
1. Go back to the Azure portal and select **Overview**.
64-
1. Confirm that **Status** shows a green check mark, followed by a node count that matches the number of replicas specified in the YAML file. This status means the deployed self-hosted gateway pods are successfully communicating with the API Management service and have a regular "heartbeat."
65-
66-
![Gateway status](media/how-to-deploy-self-hosted-gateway-kubernetes/status.png)
67-
68-
> [!TIP]
69-
> Run the `kubectl logs deployment/<gateway-name>` command to view logs from a randomly selected pod if there's more than one.
70-
> Run `kubectl logs -h` for a complete set of command options, such as how to view logs for a specific pod or container.
47+
[!INCLUDE [api-management-self-hosted-gateway-kubernetes-services](../../includes/api-management-self-hosted-gateway-kubernetes-services.md)]
7148

7249
## Next steps
7350

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

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,9 @@ Without a valid access token, a self-hosted gateway can't access and download co
2525

2626
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).
2727

28+
> [!TIP]
29+
> You can also deploy the self-hosted gateway to Kubernetes and enable authentication to the API Management instance by using [Azure AD](self-hosted-gateway-enable-azure-ad.md).
30+
2831
## Autoscaling
2932

3033
While we provide [guidance on the minimum number of replicas](#number-of-replicas) for the self-hosted gateway, we recommend that you use autoscaling for the self-hosted gateway to meet the demand of your traffic more proactively.
@@ -110,7 +113,7 @@ The YAML file provided in the Azure portal applies the default [ClusterFirst](ht
110113
To learn about name resolution in Kubernetes, see the [Kubernetes website](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service). Consider customizing [DNS policy](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#pod-s-dns-policy) or [DNS configuration](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#pod-s-dns-config) as appropriate for your setup.
111114

112115
## External traffic policy
113-
The YAML file provided in the Azure portal sets `externalTrafficPolicy` field on the [Service](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#service-v1-core) object to `Local`. This preserves caller IP address (accessible in the [request context](api-management-policy-expressions.md#ContextVariables)) and disables cross node load balancing, eliminating network hops caused by it. Be aware, that this setting might cause asymmetric distribution of traffic in deployments with unequal number of gateway pods per node.
116+
The YAML file provided in the Azure portal sets `externalTrafficPolicy` field on the [Service](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/service-v1/) object to `Local`. This preserves caller IP address (accessible in the [request context](api-management-policy-expressions.md#ContextVariables)) and disables cross node load balancing, eliminating network hops caused by it. Be aware, that this setting might cause asymmetric distribution of traffic in deployments with unequal number of gateway pods per node.
114117

115118
## High availability
116119
The self-hosted gateway is a crucial component in the infrastructure and has to be highly available. However, failure will and can happen.

‎articles/api-management/self-hosted-gateway-enable-azure-ad.md

Lines changed: 256 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,256 @@
1+
---
2+
title: Azure API Management self-hosted gateway - Azure AD authentication
3+
description: Enable the Azure API Management self-hosted gateway to authenticate with its associated cloud-based API Management instance using Azure Active Directory authentication.
4+
services: api-management
5+
author: dlepow
6+
7+
ms.service: api-management
8+
ms.topic: article
9+
ms.date: 05/22/2023
10+
ms.author: danlep
11+
---
12+
13+
# Use Azure AD authentication for the self-hosted gateway
14+
15+
The Azure API Management [self-hosted gateway](self-hosted-gateway-overview.md) needs connectivity with its associated cloud-based API Management instance for reporting status, checking for and applying configuration updates, and sending metrics and events.
16+
17+
In addition to using a gateway access token (authentication key) to connect with its cloud-based API Management instance, you can enable the self-hosted gateway to authenticate to its associated cloud instance by using an [Azure AD app](../active-directory/develop/app-objects-and-service-principals.md). With Azure AD authentication, you can configure longer expiry times for secrets and use standard steps to manage and rotate secrets in Active Directory.
18+
19+
## Scenario overview
20+
21+
The self-hosted gateway configuration API can check Azure RBAC to determine who has permissions to read the gateway configuration. After you create an Azure AD app with those permissions, the self-hosted gateway can authenticate to the API Management instance using the app.
22+
23+
To enable Azure AD authentication, complete the following steps:
24+
1. Create two custom roles to:
25+
* Let the configuration API get access to customer's RBAC information
26+
* Grant permissions to read self-hosted gateway configuration
27+
1. Grant RBAC access to the API Management instance's managed identity
28+
1. Create an Azure AD app and grant it access to read the gateway configuration
29+
1. Deploy the gateway with new configuration options
30+
31+
## Prerequisites
32+
33+
* An API Management instance in the Developer or Premium service tier. If needed, complete the following quickstart: [Create an Azure API Management instance](get-started-create-service-instance.md).
34+
* Provision a [gateway resource](api-management-howto-provision-self-hosted-gateway.md) on the instance.
35+
* Enable a [managed identity](api-management-howto-use-managed-service-identity.md) on the instance.
36+
37+
## Create custom roles
38+
39+
Create the following two [custom roles](../role-based-access-control/custom-roles.md) that are assigned in later steps. You can use the permissions listed in the following JSON templates to create the custom roles using the [Azure portal](../role-based-access-control/custom-roles-portal.md), [Azure CLI](../role-based-access-control/custom-roles-cli.md), [Azure PowerShell](../role-based-access-control/custom-roles-powershell.md), or other Azure tools.
40+
41+
When configuring the custom roles, update the [`AssignableScopes`](../role-based-access-control/role-definitions.md#assignablescopes) property with appropriate scope values for your directory, such as a subscription in which your API Management instance is deployed.
42+
43+
**API Management Configuration API Access Validator Service Role**
44+
45+
```json
46+
{
47+
"Description": "Can access RBAC permissions on the API Management resource to authorize requests in Configuration API.",
48+
"IsCustom": true,
49+
"Name": "API Management Configuration API Access Validator Service Role",
50+
"Permissions": [
51+
{
52+
"Actions": [
53+
"Microsoft.Authorization/denyAssignments/read",
54+
"Microsoft.Authorization/roleAssignments/read",
55+
"Microsoft.Authorization/roleDefinitions/read"
56+
],
57+
"NotActions": [],
58+
"DataActions": [],
59+
"NotDataActions": []
60+
}
61+
],
62+
"NotDataActions": [],
63+
"AssignableScopes": [
64+
"/subscriptions/{subscriptionID}"
65+
]
66+
}
67+
```
68+
69+
**API Management Gateway Configuration Reader Role**
70+
71+
```json
72+
{
73+
"Description": "Can read self-hosted gateway configuration from Configuration API",
74+
"IsCustom": true,
75+
"Name": "API Management Gateway Configuration Reader Role",
76+
"Permissions": [
77+
{
78+
"Actions": [],
79+
"NotActions": [],
80+
"DataActions": [
81+
"Microsoft.ApiManagement/service/gateways/getConfiguration/action"
82+
],
83+
"NotDataActions": []
84+
}
85+
],
86+
"NotDataActions": [],
87+
"AssignableScopes": [
88+
"/subscriptions/{subscriptionID}"
89+
]
90+
}
91+
```
92+
93+
## Add role assignments
94+
95+
### Assign API Management Configuration API Access Validator Service Role
96+
97+
Assign the API Management Configuration API Access Validator Service Role to the managed identity of the API Management instance. For detailed steps to assign a role, see [Assign Azure roles using the portal](../role-based-access-control/role-assignments-portal.md).
98+
99+
* Scope: The resource group or subscription in which the API Management instance is deployed
100+
* Role: API Management Configuration API Access Validator Service Role
101+
* Assign access to: Managed identity of API Management instance
102+
103+
### Assign API Management Gateway Configuration Reader Role
104+
105+
#### Step 1. Register Azure AD app
106+
107+
Create a new Azure AD app. For steps, see [Create an Azure Active Directory application and service principal that can access resources](../active-directory/develop/howto-create-service-principal-portal.md). This app will be used by the self-hosted gateway to authenticate to the API Management instance.
108+
109+
* Generate a [client secret](../active-directory/develop/howto-create-service-principal-portal.md#option-3-create-a-new-application-secret)
110+
* Take note of the following application values for use in the next section when deploying the self-hosted gateway: application (client) ID, directory (tenant) ID, and client secret
111+
112+
#### Step 2. Assign API Management Gateway Configuration Reader Service Role
113+
114+
[Assign](../active-directory/develop/howto-create-service-principal-portal.md#assign-a-role-to-the-application) the API Management Gateway Configuration Reader Service Role to the app.
115+
116+
* Scope: The API Management instance (or resource group or subscription in which it's deployed)
117+
* Role: API Management Gateway Configuration Reader Role
118+
* Assign access to: Azure AD app
119+
120+
## Deploy the self-hosted gateway
121+
122+
Deploy the self-hosted gateway to Kubernetes, adding Azure AD app registration settings to the `data` element of the gateways `ConfigMap`. In the following example YAML configuration file, the gateway is named *mygw* and the file is named `mygw.yaml`.
123+
124+
> [!IMPORTANT]
125+
> If you're following the existing Kubernetes [deployment guidance](how-to-deploy-self-hosted-gateway-kubernetes.md):
126+
> * Make sure to omit the step to store the default authentication key using the `kubectl create secret generic` command.
127+
> * Substitute the following basic configuration file for the default YAML file that's generated for you in the Azure portal. The following file adds Azure AD configuration in place of configuration to use an authentication key.
128+
129+
```yml
130+
---
131+
apiVersion: v1
132+
kind: ConfigMap
133+
metadata:
134+
name: mygw-env
135+
labels:
136+
app: mygw
137+
data:
138+
config.service.endpoint: "<service-name>.configuration.azure-api.net"
139+
config.service.auth: azureAdApp
140+
config.service.auth.azureAd.authority: "https://login.microsoftonline.com"
141+
config.service.auth.azureAd.tenantId: "<Azure AD tenant ID>"
142+
config.service.auth.azureAd.clientId: "<Azure AD client ID>"
143+
config.service.auth.azureAd.clientSecret: "<Azure AD client secret>"
144+
gateway.name: <gateway-id>
145+
---
146+
apiVersion: apps/v1
147+
kind: Deployment
148+
metadata:
149+
name: mygw
150+
labels:
151+
app: mygw
152+
spec:
153+
replicas: 1
154+
selector:
155+
matchLabels:
156+
app: mygw
157+
strategy:
158+
type: RollingUpdate
159+
rollingUpdate:
160+
maxUnavailable: 0
161+
maxSurge: 25%
162+
template:
163+
metadata:
164+
labels:
165+
app: mygw
166+
spec:
167+
terminationGracePeriodSeconds: 60
168+
containers:
169+
- name: mygw
170+
image: mcr.microsoft.com/azure-api-management/gateway:v2
171+
ports:
172+
- name: http
173+
containerPort: 8080
174+
- name: https
175+
containerPort: 8081
176+
# Container port used for rate limiting to discover instances
177+
- name: rate-limit-dc
178+
protocol: UDP
179+
containerPort: 4290
180+
# Container port used for instances to send heartbeats to each other
181+
- name: dc-heartbeat
182+
protocol: UDP
183+
containerPort: 4291
184+
readinessProbe:
185+
httpGet:
186+
path: /status-0123456789abcdef
187+
port: http
188+
scheme: HTTP
189+
initialDelaySeconds: 0
190+
periodSeconds: 5
191+
failureThreshold: 3
192+
successThreshold: 1
193+
envFrom:
194+
- configMapRef:
195+
name: mygw-env
196+
---
197+
apiVersion: v1
198+
kind: Service
199+
metadata:
200+
name: mygw-live-traffic
201+
labels:
202+
app: mygw
203+
spec:
204+
type: LoadBalancer
205+
externalTrafficPolicy: Local
206+
ports:
207+
- name: http
208+
port: 80
209+
targetPort: 8080
210+
- name: https
211+
port: 443
212+
targetPort: 8081
213+
selector:
214+
app: mygw
215+
---
216+
apiVersion: v1
217+
kind: Service
218+
metadata:
219+
name: mygw-instance-discovery
220+
labels:
221+
app: mygw
222+
annotations:
223+
azure.apim.kubernetes.io/notes: "Headless service being used for instance discovery of self-hosted gateway"
224+
spec:
225+
clusterIP: None
226+
type: ClusterIP
227+
ports:
228+
- name: rate-limit-discovery
229+
port: 4290
230+
targetPort: rate-limit-dc
231+
protocol: UDP
232+
- name: discovery-heartbeat
233+
port: 4291
234+
targetPort: dc-heartbeat
235+
protocol: UDP
236+
selector:
237+
app: mygw
238+
```
239+
240+
Deploy the gateway to Kubernetes with the following command:
241+
242+
```Console
243+
kubectl apply -f mygw.yaml
244+
```
245+
246+
[!INCLUDE [api-management-self-hosted-gateway-kubernetes-services](../../includes/api-management-self-hosted-gateway-kubernetes-services.md)]
247+
248+
249+
## Next steps
250+
251+
* Learn more about the API Management [self-hosted gateway overview](self-hosted-gateway-overview.md).
252+
* Learn more about guidance for [running the self-hosted gateway on Kubernetes in production](how-to-self-hosted-gateway-on-kubernetes-in-production.md).
253+
* Learn [how to deploy API Management self-hosted gateway to Azure Arc-enabled Kubernetes clusters](how-to-deploy-self-hosted-gateway-azure-arc.md).
254+
255+
[helm]: https://helm.sh/
256+
[helm-install]: https://helm.sh/docs/intro/install/

‎includes/api-management-self-hosted-gateway-kubernetes-services.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
author: dlepow
3+
ms.service: api-management
4+
ms.topic: include
5+
ms.date: 05/22/2023
6+
ms.author: danlep
7+
---
8+
## Confirm that the gateway is running
9+
10+
1. Run the following command to check if the deployment succeeded. It might take a little time for all the objects to be created and for the pods to initialize.
11+
12+
```console
13+
kubectl get deployments
14+
```
15+
It should return
16+
```console
17+
NAME READY UP-TO-DATE AVAILABLE AGE
18+
<gateway-name> 1/1 1 1 18s
19+
```
20+
1. Run the following command to check if the services were successfully created. Your service IPs and ports will be different.
21+
22+
```console
23+
kubectl get services
24+
```
25+
It should return
26+
```console
27+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
28+
<gateway-name>-live-traffic ClusterIP None <none> 4290/UDP,4291/UDP 9m1s
29+
<gateway-name>-instance-discovery LoadBalancer 10.99.236.168 <pending> 80:31620/TCP,443:30456/TCP 9m1s
30+
```
31+
1. Go back to the Azure portal and select **Overview**.
32+
1. Confirm that **Status** shows a green check mark, followed by a node count that matches the number of replicas specified in the YAML file. This status means the deployed self-hosted gateway pods are successfully communicating with the API Management service and have a regular "heartbeat."
33+
:::image type="content" source="./media/api-management-self-hosted-gateway-kubernetes-services/status.png" alt-text="Screenshot showing status of self-hosted gateway in the portal.":::
34+
35+
> [!TIP]
36+
> * Run the `kubectl logs deployment/<gateway-name>` command to view logs from a randomly selected pod if there's more than one.
37+
> * Run `kubectl logs -h` for a complete set of command options, such as how to view logs for a specific pod or container.

‎articles/api-management/media/how-to-deploy-self-hosted-gateway-kubernetes/status.png renamed to ‎includes/media/api-management-self-hosted-gateway-kubernetes-services/status.png

File renamed without changes.

0 commit comments

Comments
 (0)