Usare l'autenticazione Microsoft Entra per il gateway autogestito

SI APPLICA A: Sviluppatore | Premium

Il gateway self-hosted di Azure API Management necessita di connettività con la sua istanza di Gestione API basata sul cloud associata per monitorare lo stato, verificare e applicare aggiornamenti della configurazione e inviare metriche ed eventi.

Questo articolo illustra come abilitare il gateway self-hosted per autenticarsi all'istanza cloud associata utilizzando un'app Microsoft Entra ID con un segreto del client o un certificato. Usando Microsoft Entra'autenticazione, è possibile configurare tempi di scadenza più lunghi per i segreti e usare i passaggi standard per gestire e ruotare i segreti. Per altre opzioni di autenticazione, vedere Opzioni di autenticazione del gateway autogestito.

Panoramica dello scenario

L'API di configurazione del gateway autogestito può controllare il controllo degli accessi basato sui ruoli di Azure per determinare chi possiede le autorizzazioni per la lettura della 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 Microsoft Entra, completare la procedura seguente:

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 seguente esercitazione rapida: Creare un'istanza di Azure API Management.
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

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 Azure, Azure CLI, 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 validatore di accesso dell'API per la configurazione della gestione delle 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 di lettore della configurazione del gateway di 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 il ruolo di servizio di Validatore dell'accesso API nella Configurazione di Gestione API

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 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 Lettore di configurazione del gateway di API Management

Passaggio 1: Registrare Microsoft Entra'app

Creare una nuova app Microsoft Entra. Per i passaggi, vedere Creare un'applicazione Microsoft Entra e un principale servizio in grado di accedere alle risorse. L'app Microsoft Entra viene usata dal gateway self-hosted per l'autenticazione nell'istanza di Gestione API.

Generare un segreto client per l'app.
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.

Annotazioni

Anziché usare un segreto client, è possibile scegliere di usare un certificato per l'autenticazione. Per i passaggi per caricare un certificato nell'app Microsoft Entra, vedere Use certificates for Azure AD app authentication.

Passaggio 2: Assegnare il ruolo del servizio di lettore della configurazione del gateway di gestione API

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

Ambito: istanza di Gestione API (o gruppo di risorse o sottoscrizione in cui viene distribuita l'app)
Ruolo: Lettore della configurazione del gateway di gestione delle API
Assegnare l'accesso all'app Microsoft Entra

Distribuire il gateway self-hosted

Distribuire il gateway self-hosted in un ambiente containerizzato, ad esempio Kubernetes, aggiungendo le impostazioni di registrazione dell'app di Microsoft Entra.

Timone
YAML

È possibile distribuire il gateway self-hosted con l'autenticazione Microsoft Entra utilizzando uno schema Helm.

Sostituire i valori seguenti nel helm install comando con i valori effettivi:

<gateway-name>: nome dell'istanza di Azure API Management
<gateway-url>: URL del gateway, nel formato https://<gateway-name>.configuration.azure-api.net
<entra-id-tenant-id>: ID tenant di Microsoft Entra (ID directory)
<entra-id-app-id>: ID dell'applicazione (client) dell'app Microsoft Entra registrata
<entra-id-secret>: segreto del client generato per l'app Microsoft Entra

helm install --name azure-api-management-gateway azure-apim-gateway/azure-api-management-gateway \
             --set gateway.name=='<gateway-name>' \
             --set gateway.configuration.uri='<gateway-url>' \
             --set gateway.auth.type='AzureAdApp' \
             --set gateway.auth.azureAd.tenant.id='<entra-id-tenant-id>' \
             --set gateway.auth.azureAd.app.id='<entra-id-app-id>'
             --set config.service.auth.azureAd.clientSecret='<entra-id-secret>'

Per i prerequisiti e i dettagli, vedere Distribuire un gateway self-hosted di API Management con Helm.

Verificare che il gateway sia in esecuzione

Eseguire il comando seguente per verificare che il pod del gateway sia in esecuzione. Il nome del pod sarà diverso.

kubectl get pods
NAME                                           READY     STATUS    RESTARTS   AGE
azure-api-management-gateway-59f5fb94c-s9stz   1/1       Running   0          1m

Eseguire il comando seguente per verificare che il servizio gateway sia in esecuzione. Il nome del servizio e gli indirizzi IP saranno diversi.

kubectl get services
NAME                           TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)               AGE
azure-api-management-gateway   ClusterIP   10.0.229.55     <none>        8080/TCP,8081/TCP     1m

Tornare al portale di Azure e verificare che lo stato del nodo del gateway distribuito sia Integro.

Suggerimento

Usare il comando kubectl logs <gateway-pod-name> per visualizzare uno snapshot del log del gateway self-hosted.

Nel seguente file di configurazione YAML di esempio, le impostazioni di registrazione dell'app Microsoft Entra vengono aggiunte all'elemento data del ConfigMap del gateway. Il gateway è denominato mygw.

Importante

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

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 dal portale di Azure. Il seguente file aggiunge la configurazione di Microsoft Entra in sostituzione della configurazione per usare una chiave di autenticazione.

Annotazioni

Assicurarsi di sostituire i valori segnaposto con la configurazione effettiva:

<entra-id-app-id>: ID dell'applicazione di Microsoft Entra (client)
<entra-id-tenant-id>: ID tenant di Microsoft Entra (ID directory)
<entra-id-client-secret>: segreto client generato per l'app Microsoft Entra
<gateway-id>: nome del gateway self-hosted
<service-name>.configuration.azure-api.net: endpoint di configurazione del tuo Gestione API

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: mygw-env
  labels:
    app: apim-gateway
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: "<entra-id-tenant-id>" 
  config.service.auth.azureAd.clientId: "<entra-id-app-id>" 
  config.service.auth.azureAd.clientSecret: "<entra-id-client-secret>"
  gateway.name: <gateway-id>
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mygw
  labels:
    app: apim-gateway
spec:
  replicas: 1
  selector:
    matchLabels:
      app: apim-gateway
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 0
      maxSurge: 25%
  template:
    metadata:
      labels:
        app: apim-gateway
    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: apim-gateway
spec:
  type: LoadBalancer
  externalTrafficPolicy: Local
  ports:
  - name: http
    port: 80
    targetPort: 8080
  - name: https
    port: 443
    targetPort: 8081
  selector:
    app: apim-gateway
---
apiVersion: v1
kind: Service
metadata:
  name: mygw-instance-discovery
  labels:
    app: apim-gateway
  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: apim-gateway

Distribuire in Kubernetes

Salvare la configurazione YAML in un file (ad esempio, apim-gateway-entra-id.yaml) e distribuirla nel cluster del servizio Azure Kubernetes:

kubectl apply -f apim-gateway-entra-id.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 la scheda Panoramica del gateway.
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.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-03-11

Condividi tramite

Usare l'autenticazione Microsoft Entra per il gateway autogestito

Panoramica dello scenario

Prerequisiti

Limitazioni

Creare ruoli personalizzati

Aggiungere assegnazioni di ruolo

Assegnare il ruolo di servizio di Validatore dell'accesso API nella Configurazione di Gestione API

Assegnare il ruolo Lettore di configurazione del gateway di API Management

Passaggio 1: Registrare Microsoft Entra'app

Passaggio 2: Assegnare il ruolo del servizio di lettore della configurazione del gateway di gestione API

Distribuire il gateway self-hosted

Verificare che il gateway sia in esecuzione

Contenuti correlati

Commenti e suggerimenti

Risorse aggiuntive