Usare l'autenticazione Di Microsoft Entra per il gateway self-hosted

Articolo
10/18/2023

SI APPLICA A: Sviluppatore | Premium

Il gateway self-hosted di Azure Gestione API necessita della connettività con l'istanza di Gestione API basata sul cloud associata per la creazione di report, il controllo e l'applicazione degli aggiornamenti della configurazione e l'invio di metriche ed eventi.

Oltre a usare un token di accesso gateway (chiave di autenticazione) per connettersi alla relativa istanza di Gestione API basata sul cloud, è possibile abilitare il gateway self-hosted per l'autenticazione all'istanza cloud associata usando un'app Microsoft Entra. Con l'autenticazione di Microsoft Entra, è possibile configurare tempi di scadenza più lunghi per i segreti e usare i passaggi standard per gestire e ruotare i segreti in Active Directory.

Panoramica dello scenario

L'API di configurazione del gateway self-hosted può controllare il controllo degli accessi in base al ruolo di Azure per determinare chi ha le autorizzazioni per leggere la configurazione del gateway. Dopo aver creato un'app Microsoft Entra con tali autorizzazioni, il gateway self-hosted può eseguire l'autenticazione all'istanza di Gestione API usando l'app.

Per abilitare l'autenticazione di Microsoft Entra, seguire questa procedura:

Creare due ruoli personalizzati per:
- Consentire all'API di configurazione di ottenere l'accesso alle informazioni di controllo degli accessi in base al ruolo del cliente
- Concedere le autorizzazioni per leggere la configurazione del gateway self-hosted
Concedere l'accesso controllo degli accessi in base al ruolo all'identità gestita dell'istanza di Gestione API
Creare un'app Microsoft Entra e concedergli l'accesso per leggere la configurazione del gateway
Distribuire il gateway con nuove opzioni di configurazione

Prerequisiti

Istanza di Gestione API nel livello di servizio Developer o Premium. Se necessario, completare la guida introduttiva seguente: Creare un'istanza di Azure Gestione API.
Effettuare il provisioning di una risorsa gateway nell'istanza di .
Abilitare un'identità gestita assegnata dal sistema nell'istanza di .
Immagine del contenitore del gateway self-hosted versione 2.2 o successiva

Note sulle limitazioni

È supportata solo l'identità gestita assegnata dal sistema.

Creare ruoli personalizzati

Creare i due ruoli personalizzati seguenti assegnati nei passaggi successivi. È possibile usare le autorizzazioni elencate nei modelli JSON seguenti per creare i ruoli personalizzati usando il portale di Azure, l'interfaccia della riga di comando di Azure, Azure PowerShell o altri strumenti di Azure.

Quando si configurano i ruoli personalizzati, aggiornare la proprietà con i valori di ambito appropriati per la AssignableScopes directory, ad esempio una sottoscrizione in cui viene distribuita l'istanza di Gestione API.

Ruolo del servizio Di convalida dell'accesso all'API di configurazione Gestione API

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

Ruolo lettore configurazione gateway Gestione API

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

Aggiungere assegnazioni di ruolo

Assegnare Gestione API ruolo del servizio di convalida dell'accesso all'API di configurazione

Assegnare il ruolo del servizio di convalida dell'accesso all'API di configurazione Gestione API all'identità gestita dell'istanza di Gestione API. Per i passaggi dettagliati per assegnare un ruolo, vedere Assegnare ruoli di Azure usando il portale.

Ambito: gruppo di risorse o sottoscrizione in cui viene distribuita l'istanza di Gestione API
Ruolo: Gestione API ruolo del servizio di convalida dell'accesso all'API di configurazione
Assegnare l'accesso a: identità gestita dell'istanza di Gestione API

Assegnare Gestione API ruolo lettore configurazione gateway

Passaggio 1: Registrare l'app Microsoft Entra

Creare una nuova app Microsoft Entra. Per la procedura, vedere Creare un'applicazione Microsoft Entra e un'entità servizio in grado di accedere alle risorse. Questa app verrà usata dal gateway self-hosted per l'autenticazione nell'istanza di Gestione API.

Generare un segreto client
Prendere nota dei valori dell'applicazione seguenti da usare nella sezione successiva quando si distribuisce il gateway self-hosted: ID applicazione (client), ID directory (tenant) e segreto client

Passaggio 2: Assegnare Gestione API ruolo del servizio lettore di configurazione del gateway

Assegnare il ruolo del servizio lettore configurazione gateway Gestione API all'app.

Ambito: istanza di Gestione API (o gruppo di risorse o sottoscrizione in cui è distribuita)
Ruolo: ruolo lettore configurazione gateway Gestione API
Assegnare l'accesso a: App Microsoft Entra

Distribuire il gateway self-hosted

Distribuire il gateway self-hosted in Kubernetes, aggiungendo le impostazioni di registrazione dell'app Microsoft Entra all'elemento data dei gateway ConfigMap. Nel file di configurazione YAML di esempio seguente il gateway è denominato mygw e il file è denominato mygw.yaml.

Importante

Se si seguono le linee guida per la distribuzione di Kubernetes esistenti:

Assicurarsi di omettere il passaggio per archiviare la chiave di autenticazione predefinita usando il kubectl create secret generic comando .
Sostituire il file di configurazione di base seguente per il file YAML predefinito generato automaticamente nella portale di Azure. Il file seguente aggiunge la configurazione di Microsoft Entra al posto della configurazione per l'uso di una chiave di autenticazione.

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

Distribuire il gateway in Kubernetes con il comando seguente:

kubectl apply -f mygw.yaml

Verificare che il gateway sia in esecuzione

Eseguire il comando seguente per verificare se la distribuzione è riuscita. La creazione di tutti gli oggetti e l'inizializzazione dei pod potrebbero richiedere un po' di tempo.
```
kubectl get deployments
```
Dovrebbe restituire
```
NAME             READY   UP-TO-DATE   AVAILABLE   AGE
<gateway-name>   1/1     1            1           18s
```

Eseguire il comando seguente per verificare se i servizi sono stati creati correttamente. Gli INDIRIZZI IP e le porte del servizio saranno diversi.

kubectl get services

Dovrebbe restituire

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

Tornare al portale di Azure e selezionare Panoramica.
Verificare che status mostri un segno di spunta verde, seguito da un conteggio dei nodi corrispondente al numero di repliche specificate nel file YAML. Questo stato indica che i pod gateway self-hosted distribuiti comunicano correttamente con il servizio Gestione API e hanno un normale "heartbeat".

Suggerimento

Eseguire il kubectl logs deployment/<gateway-name> comando per visualizzare i log da un pod selezionato in modo casuale se sono presenti più pod.
Eseguire kubectl logs -h per un set completo di opzioni di comando, ad esempio come visualizzare i log per un pod o un contenitore specifico.

Passaggi successivi

Altre informazioni sulla panoramica del gateway self-hosted Gestione API.
Altre informazioni sulle linee guida per l'esecuzione del gateway self-hosted in Kubernetes nell'ambiente di produzione.
Informazioni su come distribuire il gateway self-hosted di Gestione API nei cluster Kubernetes abilitati per Azure Arc.