Usare l'autenticazione di Microsoft Entra per il gateway autogestito

SI APPLICA A: Sviluppatore | Premium

Il gateway self-hosted di Gestione API di Azure richiede la connettività con l'istanza di Gestione API basata sul cloud associata per segnalare lo stato, verificare e applicare gli aggiornamenti della configurazione e inviare metriche ed eventi.

Oltre a usare un token di accesso gateway (chiave di autenticazione) per connettersi con l'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 accedere alle informazioni di RBAC del cliente
- Concedere le autorizzazioni per leggere la configurazione del gateway autogestito
Concedere l'accesso RBAC all'identità gestita dell'istanza di Gestione delle 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 Gestione API di Azure.
Effettuare il provisioning di una risorsa gateway nell'istanza.
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à AssignableScopes con i valori di ambito appropriati per la directory, ad esempio una sottoscrizione in cui viene distribuita l'istanza di API Management.

Ruolo del servizio di convalida dell'accesso all'API di gestione delle configurazioni

{
  "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 del gateway di API Management

{
  "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 il ruolo del servizio Validator dell'accesso API di configurazione di API Management

Assegnare il ruolo del servizio Validator dell'accesso API di configurazione di API Management all'identità gestita dell'istanza di API Management. 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: Configurazione di Gestione API e Servizio di Convalida Accesso API
Assegnare l'accesso a: Identità gestita dell'istanza di Gestione API

Assegnare il ruolo di Lettore di Configurazione del Gateway di Gestione API

Passaggio 1: Registrare l'app Microsoft Entra

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

Generare un client secret
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 il ruolo del servizio di lettore della configurazione del gateway di gestione API

Assegnare il ruolo Lettore configurazione del gateway di API Management Management all'app.

Ambito: istanza di Gestione API (o gruppo di risorse o sottoscrizione in cui viene distribuita l'app)
Ruolo: Ruolo lettore della configurazione del gateway di 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 dal 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 "heartbeat" regolare.

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.

Scopri di più sul gateway autogestito di Gestione API.
Ulteriori informazioni sulle linee guida per l'esecuzione del gateway self-hosted in Kubernetes in produzione.
Informazioni su come distribuire il gateway self-hosted di API Management nei cluster Kubernetes abilitati per Azure Arc.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-10-12