Verwenden der Microsoft Entra-Authentifizierung auf selbstgehosteten Gateways

Artikel
12/12/2023

GILT FÜR: Entwickler | Premium

Das selbstgehostete Azure API Management-Gateway benötigt Konnektivität mit der zugehörigen cloudbasierten API-Management-Instanz, um den Status zu melden, Konfigurationsupdates zu überprüfen und anzuwenden und Metriken und Ereignisse zu senden.

Zusätzlich zur Verwendung eines Gatewayzugriffstokens (Authentifizierungsschlüssels) für die Verbindung mit der cloudbasierten API Management-Instanz können Sie das selbstgehostete Gateway mithilfe einer Microsoft Entra-App für die Authentifizierung bei seiner zugeordneten Cloud-Instanz aktivieren. Mit der Microsoft Entra-Authentifizierung können Sie längere Ablaufzeiträume für Geheimnisse konfigurieren und Standardschritte verwenden, um Geheimnisse in Active Directory zu verwalten und zu rotieren.

Übersicht über das Szenario

Die Konfigurations-API für selbstgehostete Gateways kann in Azure RBAC nachschlagen, um zu ermitteln, wer über Berechtigungen zum Lesen der Gatewaykonfiguration verfügt. Nachdem Sie eine Microsoft Entra-App mit diesen Berechtigungen erstellt haben, kann sich das selbstgehostete Gateway mithilfe der Anwendung bei der API Management-Instanz authentifizieren.

Um die Microsoft Entra-Authentifizierung zu aktivieren, führen Sie die folgenden Schritte aus:

Erstellen Sie zwei benutzerdefinierte Rollen für die folgenden Aufgaben:
- Zulassen, dass die Konfigurations-API Zugriff auf die RBAC-Informationen des Kunden erhält
- Erteilen von Berechtigungen zum Lesen der Konfiguration des selbstgehosteten Gateways
Gewähren von RBAC-Zugriff auf die verwaltete Identität der API-Management-Instanz
Erstellen einer Microsoft Entra-Anwendung und Gewähren von Zugriff zum Lesen der Gatewaykonfiguration
Bereitstellen des Gateways mit neuen Konfigurationsoptionen

Voraussetzungen

Eine API-Management-Instanz in den Dienstebenen „Developer“ oder „Premium“. Absolvieren Sie bei Bedarf den folgenden Schnellstart: Erstellen einer Azure API Management-Instanz.
Stellen Sie eine Gatewayressource auf der Instanz bereit.
Aktivieren Sie eine systemseitig zugewiesene verwaltete Identität auf der Instanz.
Selbstgehostetes Gatewaycontainerimage Version 2.2 oder höher

Hinweise zu Einschränkungen

Nur eine systemseitig zugewiesene verwaltete Identität wird unterstützt.

Erstellen von benutzerdefinierten Rollen

Erstellen Sie die folgenden beiden benutzerdefinierten Rollen, die in späteren Schritten zugewiesen werden. Sie können die in den folgenden JSON-Vorlagen aufgeführten Berechtigungen verwenden, um die benutzerdefinierten Rollen mithilfe des Azure-Portals, der Azure CLI, von Azure PowerShell oder von anderen Azure-Tools zu erstellen.

Aktualisieren Sie beim Konfigurieren der benutzerdefinierten Rollen die Eigenschaft AssignableScopes mit geeigneten Bereichswerten für Ihr Verzeichnis, z. B. ein Abonnement, in dem Ihre API-Management-Instanz bereitgestellt wird.

API-Management – Konfiguration der Rolle für den API-Zugriffsprüfungsdienst

{
  "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}"
  ]
}

API-Management-Gateway – Konfiguration der Rolle des Lesers

{
  "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}"
  ]
}

Hinzufügen von Rollenzuweisungen

Zuweisen der Rolle für den API-Zugriffsprüfungsdienst in der API-Management-Konfiguration

Weisen Sie der verwalteten Identität der API-Management-Instanz die Rolle für den API-Zugriffsprüfungsdienst in der API-Management-Konfiguration zu. Schritte zum Zuweisen von Rollen finden Sie unter Azure-Rollen über das Azure-Portal zuweisen.

Bereich: Die Ressourcengruppe oder das Abonnement, in der die API-Management-Instanz bereitgestellt wird
Rolle: Rolle für den API-Zugriffsprüfungsdienst in der API-Management-Konfiguration
Zuweisen des Zugriffs zu: Verwaltete Identität der API-Management-Instanz

Zuweisen der Rolle „Gatewaykonfigurationsleser“ im API-Management

Schritt 1: Registrieren einer Microsoft Entra-App

Erstellen Sie eine neue Microsoft Entra-App. Eine Beschreibung der Schritte finden Sie unter Erstellen einer Microsoft Entra-Anwendung und eines Dienstprinzipals mit Zugriff auf Ressourcen. Diese Anwendung wird vom selbstgehosteten Gateway verwendet, um sich bei der API-Management-Instanz zu authentifizieren.

Erstellen eines geheimen Clientschlüssels
Notieren Sie sich bei der Bereitstellung des selbstgehosteten Gateways die folgenden Anwendungswerte zur Verwendung im nächsten Abschnitt : Anwendungs-ID (Client-ID), Verzeichnis-ID (Mandanten-ID) und geheimer Clientschlüssel.

Schritt 2: Zuweisen der Dienstrolle „Gatewaykonfigurationsleser“ in der API-Verwaltung

Weisen Sie der Anwendung die Rolle „Gatewaykonfigurationslesedienst“ im API-Management zu.

Bereich: Die API-Management-Instanz (oder Ressourcengruppe oder Abonnement, in der sie bereitgestellt wird)
Rolle: Rolle „Gatewaykonfigurationsleser“ im API-Management
Gewähren Sie Zugriff auf: Microsoft Entra-App

Bereitstellen des selbstgehosteten Gateways

Stellen Sie das selbstgehostete Gateway in Kubernetes bereit und fügen Sie die Einstellungen für die Microsoft Entra-Anwendungsregistrierung dem Element data des Gateways ConfigMap hinzu. In der folgenden YAML-Beispielkonfigurationsdatei heißt das Gateway mygw und die Datei heißt mygw.yaml.

Wichtig

Wenn Sie die vorhandene Kubernetes-Bereitstellungsanleitung befolgen:

Achten Sie darauf, den Schritt zum Speichern des Standardauthentifizierungsschlüssels mithilfe des Befehls kubectl create secret generic wegzulassen.
Ersetzen Sie die folgende Basis-Konfigurationsdatei durch die standardmäßige YAML-Datei, die für Sie im Azure-Portal generiert wird. In der folgenden Datei wird anstelle der Konfiguration für die Verwendung eines Authentifizierungsschlüssels die Microsoft Entra-Konfiguration hinzugefügt.

---
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

Stellen Sie das Gateway mit dem folgenden Befehl in Kubernetes bereit:

kubectl apply -f mygw.yaml

Sicherstellen, dass das Gateway ausgeführt wird

Führen Sie den folgenden Befehl aus, um zu prüfen, ob die Bereitstellung erfolgreich war. Es kann einige Zeit dauern, bis alle Objekte erstellt sind und die Pods initialisiert wurden.
```
kubectl get deployments
```
Die Rückgabe sollte wie folgt lauten:
```
NAME             READY   UP-TO-DATE   AVAILABLE   AGE
<gateway-name>   1/1     1            1           18s
```

Führen Sie den folgenden Befehl aus, um zu überprüfen, ob die Dienste erfolgreich erstellt wurden. Die IP-Adressen und Ports Ihrer Dienste werden sich unterscheiden.

kubectl get services

Die Rückgabe sollte wie folgt lauten:

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

Kehren Sie zurück zum Azure-Portal, und wählen Sie Übersicht aus.
Vergewissern Sie sich, dass in Status ein grünes Häkchen angezeigt wird, gefolgt von einer Knotenanzahl, die der Anzahl der in der YAML-Datei angegebenen Replikate entspricht. Dieser Status bedeutet, dass die bereitgestellten selbstgehosteten Gatewaypods erfolgreich mit dem API Management-Dienst kommunizieren und einen regelmäßigen „Takt“ (Heartbeat) aufweisen.

Tipp

Führen Sie den Befehl kubectl logs deployment/<gateway-name> aus, um Protokolle von einem zufällig ausgewählten Pod anzuzeigen, falls es mehrere gibt.
Führen Sie kubectl logs -h aus, um eine vollständige Übersicht über alle Befehlsoptionen zu erhalten, wie z. B. Protokolle für einen bestimmten Pod oder Container.

Nächste Schritte

Weitere Informationen zum API-Management finden Sie unter Übersicht über das selbstgehostete Gateway.
Erfahren Sie mehr über Anleitungen zum Ausführen des selbstgehosteten Gateways in Kubernetes in der Produktion.
Hier erfahren Sie, wie Sie das selbstgehostete API Management-Gateway für Kubernetes-Cluster mit Azure Arc-Unterstützung bereitstellen.