Microsoft Entra-verificatie gebruiken voor de zelf-hostende gateway

2025-04-04

VAN TOEPASSING OP: Ontwikkelaar | Premie

De zelf-hostende gateway van Azure API Management heeft connectiviteit nodig met het bijbehorende API Management-exemplaar in de cloud voor het rapporteren van de status, het controleren en toepassen van configuratie-updates en het verzenden van metrische gegevens en gebeurtenissen.

Naast het gebruik van een gatewaytoegangstoken (verificatiesleutel) om verbinding te maken met het cloudexemplaar van API Management, kunt u de zelf-hostende gateway inschakelen voor verificatie bij het bijbehorende cloudexemplaar met behulp van een Microsoft Entra-app. Met Microsoft Entra-verificatie kunt u langere verlooptijden voor geheimen configureren en standaardstappen gebruiken voor het beheren en roteren van geheimen in Active Directory.

Overzicht van scenario

De zelf-hostende gatewayconfiguratie-API kan Azure RBAC controleren om te bepalen wie machtigingen heeft om de gatewayconfiguratie te lezen. Nadat u een Microsoft Entra-app met deze machtigingen hebt gemaakt, kan de zelf-hostende gateway worden geverifieerd bij het API Management-exemplaar met behulp van de app.

Voer de volgende stappen uit om Microsoft Entra-verificatie in te schakelen:

Maak twee aangepaste rollen om:
- De configuratie-API toegang geven tot de RBAC-gegevens van de klant
- Machtigingen verlenen voor het lezen van zelf-gehoste gatewayconfiguratie
RBAC toegang verlenen tot de beheerde identiteit van het API Management-exemplaar
Een Microsoft Entra-app maken en deze toegang verlenen om de gatewayconfiguratie te lezen
De gateway implementeren met nieuwe configuratieopties

Vereiste voorwaarden

Een API Management-exemplaar in de servicelaag Developer of Premium. Voltooi zo nodig de volgende quickstart: Een Azure API Management-exemplaar maken.
Richt een gatewayresource in op het exemplaar.
Schakel een door het systeem toegewezen beheerde identiteit in op het exemplaar.
Zelfgehoste containerimage van de gateway versie 2.2 of hoger

Opmerkingen bij beperkingen

Alleen door het systeem toegewezen beheerde identiteit wordt ondersteund.

Aangepast rollen maken

Maak de volgende twee aangepaste rollen die in latere stappen worden toegewezen. U kunt de machtigingen in de volgende JSON-sjablonen gebruiken om de aangepaste rollen te maken met behulp van Azure Portal, Azure CLI, Azure PowerShell of andere Azure-hulpprogramma's.

Wanneer u de aangepaste rollen configureert, werkt u de AssignableScopes eigenschap bij met de juiste bereikwaarden voor uw directory, zoals een abonnement waarin uw API Management-exemplaar wordt geïmplementeerd.

API-beheerconfiguratie API-toegangsvalidator-servicerol

{
  "Description": "Can access RBAC permissions on the API Management resource to authorize requests in Configuration API.",
  "IsCustom": true,
  "Name": "API Management Configuration API Access Validator Service Role",
  "Permissions": [
    {
      "Actions": [
        "Microsoft.Authorization/*/read"
      ],
      "NotActions": [],
      "DataActions": [],
      "NotDataActions": []
    }
  ],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/{subscriptionID}"
  ]
}

Rol van configuratielezer voor API Management Gateway

{
  "Description": "Can read self-hosted gateway configuration from Configuration API",
  "IsCustom": true,
  "Name": "API Management Gateway Configuration Reader Role",
  "Permissions": [
    {
      "Actions": [],
      "NotActions": [],
      "DataActions": [
        "Microsoft.ApiManagement/service/gateways/getConfiguration/action"
      ],
      "NotDataActions": []
    }
  ],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/{subscriptionID}"
  ]
}

Roltoewijzingen toevoegen

Api Management Configuration API Access Validator-servicerol toewijzen

Wijs de API Management Configuration API Access Validator-servicerol toe aan de beheerde identiteit van de API Management-instantie. Zie Azure-rollen toewijzen met behulp van de portal voor gedetailleerde stappen voor het toewijzen van een rol.

Bereik: De resourcegroep of het abonnement waarin het API Management-exemplaar wordt geïmplementeerd
Rol: Servicerol voor API Management Configuratie API-toegangsvalidator
Toegang toewijzen aan: Beheerde identiteit van API Management-instance

API Management Gateway-configuratielezer rol toewijzen

Stap 1: Microsoft Entra-app registreren

Maak een nieuwe Microsoft Entra-app. Zie voor de stappen Een Microsoft Entra-toepassing en service-principal maken die toegang heeft tot resources. Deze app wordt gebruikt door de zelfgehoste gateway om te authentiseren bij het API Management-exemplaar.

Een clientgeheim genereren
Noteer de volgende toepassingswaarden voor gebruik in de volgende sectie bij het implementeren van de zelf-hostende gateway: toepassings-id (client),map-id (tenant) en clientgeheim

Stap 2: Servicerol API Management Gateway Configuratielezer toewijzen

Wijs de servicerol API Management Gateway Configuration Reader toe aan de app.

Bereik: het API Management-exemplaar (of de resourcegroep of het abonnement waarin het is geïmplementeerd)
Rol: Rol van API Management Gateway-configuratielezer
Toegang toewijzen aan: Microsoft Entra-app

De zelf-hostende gateway implementeren

Implementeer de zelf-hostende gateway naar Kubernetes, waarbij u registratie-instellingen voor Microsoft Entra-apps toevoegt aan het data element van de gateways ConfigMap. In het volgende voorbeeld van het YAML-configuratiebestand heeft de gateway de naam mygw en heeft het bestand de naam mygw.yaml.

Belangrijk

Als u de bestaande Richtlijnen voor Kubernetes-implementatie volgt:

Zorg ervoor dat u de stap weglaat om de standaardverificatiesleutel op te slaan met behulp van de kubectl create secret generic opdracht.
Vervang het volgende basisconfiguratiebestand door het standaard YAML-bestand dat voor u is gegenereerd in Azure Portal. In het volgende bestand wordt microsoft Entra-configuratie toegevoegd in plaats van configuratie om een verificatiesleutel te gebruiken.

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: mygw-env
  labels:
    app: mygw
data:
  config.service.endpoint: "<service-name>.configuration.azure-api.net"
  config.service.auth: azureAdApp 
  config.service.auth.azureAd.authority: "https://login.microsoftonline.com"  
  config.service.auth.azureAd.tenantId: "<Azure AD tenant ID>" 
  config.service.auth.azureAd.clientId: "<Azure AD client ID>" 
  config.service.auth.azureAd.clientSecret: "<Azure AD client secret>"
  gateway.name: <gateway-id>
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mygw
  labels:
    app: mygw
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mygw
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 0
      maxSurge: 25%
  template:
    metadata:
      labels:
        app: mygw
    spec:
      terminationGracePeriodSeconds: 60
      containers:
      - name: mygw
        image: mcr.microsoft.com/azure-api-management/gateway:v2
        ports:
        - name: http
          containerPort: 8080
        - name: https
          containerPort: 8081
          # Container port used for rate limiting to discover instances
        - name: rate-limit-dc
          protocol: UDP
          containerPort: 4290
          # Container port used for instances to send heartbeats to each other
        - name: dc-heartbeat
          protocol: UDP
          containerPort: 4291
        readinessProbe:
          httpGet:
            path: /status-0123456789abcdef
            port: http
            scheme: HTTP
          initialDelaySeconds: 0
          periodSeconds: 5
          failureThreshold: 3
          successThreshold: 1
        envFrom:
        - configMapRef:
            name: mygw-env
---
apiVersion: v1
kind: Service
metadata:
  name: mygw-live-traffic
  labels:
    app: mygw
spec:
  type: LoadBalancer
  externalTrafficPolicy: Local
  ports:
  - name: http
    port: 80
    targetPort: 8080
  - name: https
    port: 443
    targetPort: 8081
  selector:
    app: mygw
---
apiVersion: v1
kind: Service
metadata:
  name: mygw-instance-discovery
  labels:
    app: mygw
  annotations:
    azure.apim.kubernetes.io/notes: "Headless service being used for instance discovery of self-hosted gateway"
spec:
  clusterIP: None
  type: ClusterIP
  ports:
  - name: rate-limit-discovery
    port: 4290
    targetPort: rate-limit-dc
    protocol: UDP
  - name: discovery-heartbeat
    port: 4291
    targetPort: dc-heartbeat
    protocol: UDP
  selector:
    app: mygw

Implementeer de gateway naar Kubernetes met de volgende opdracht:

kubectl apply -f mygw.yaml

Controleer of de gateway draait

Voer de volgende opdracht uit om te controleren of de implementatie is geslaagd. Het kan even duren voordat alle objecten zijn gemaakt en de pods zijn geïnitialiseerd.
```
kubectl get deployments
```
Het moet worden geretourneerd
```
NAME             READY   UP-TO-DATE   AVAILABLE   AGE
<gateway-name>   1/1     1            1           18s
```

Voer de volgende opdracht uit om te controleren of de services met succes zijn aangemaakt. Uw service-IP-adressen en poorten zijn anders.

kubectl get services

Het zou moeten terugkeren

NAME                                TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)                      AGE
<gateway-name>-live-traffic         ClusterIP      None            <none>        4290/UDP,4291/UDP   9m1s
<gateway-name>-instance-discovery   LoadBalancer   10.99.236.168   <pending>     80:31620/TCP,443:30456/TCP   9m1s

Ga terug naar Azure Portal en selecteer Overzicht.
Controleer of de status een groen vinkje weergeeft, gevolgd door een aantal knooppunten dat overeenkomt met het aantal replica's dat is opgegeven in het YAML-bestand. Deze status betekent dat de geïmplementeerde zelf-gehoste gateway-pods succesvol communiceren met de API Management-service en regelmatig een 'heartbeat'-signaal hebben.

Hint

Voer de kubectl logs deployment/<gateway-name> opdracht uit om logboeken van een willekeurig geselecteerde pod weer te geven als er meer dan één pod is.
Uitvoeren kubectl logs -h voor een volledige set opdrachtopties, zoals het weergeven van logboeken voor een specifieke pod of container.

Meer informatie over het overzicht van de zelf-hostende gateway van API Management.
Meer informatie over richtlijnen voor het uitvoeren van de zelf-hostende gateway op Kubernetes in productie.
Meer informatie over het implementeren van zelf-hostende API Management-gateway naar Kubernetes-clusters met Azure Arc.