Utiliser l’authentification Microsoft Entra pour la passerelle auto-hébergée

S'APPLIQUE À : Développeur | Premium

La passerelle auto-hébergée Gestion des API Azure a besoin d’une connectivité avec son instance de gestion des API basée sur le cloud associée pour la création de rapports, la vérification et l’application des mises à jour de configuration, et l’envoi de métriques et d’événements.

Outre l’utilisation d’un jeton d’accès de passerelle (clé d’authentification) pour vous connecter à son instance gestion des API basée sur le cloud, vous pouvez activer la passerelle auto-hébergée pour s’authentifier auprès de son instance cloud associée à l’aide d’une application Microsoft Entra. Avec l’authentification Microsoft Entra, vous pouvez configurer des délais d’expiration plus longs pour les secrets et utiliser des étapes standard pour gérer et faire pivoter les secrets dans Active Directory.

Vue d’ensemble du scénario

L’API de configuration de passerelle auto-hébergée peut vérifier le contrôle d’accès en fonction du rôle Azure (RBAC) pour déterminer qui a les autorisations nécessaires pour lire la configuration de la passerelle. Après avoir créé une application Microsoft Entra avec ces autorisations, la passerelle auto-hébergée peut s’authentifier auprès de l’instance Gestion des API à l’aide de l’application.

Pour activer l’authentification Microsoft Entra, procédez comme suit :

Créez deux rôles personnalisés pour :
- Laissez l’API de configuration accéder aux informations RBAC du client
- Accorder des autorisations pour lire la configuration de la passerelle auto-hébergée
Accorder l’accès RBAC à l’identité managée de l’instance Gestion des API
Créer une application Microsoft Entra et lui accorder l’accès pour lire la configuration de la passerelle
Déployer la passerelle avec de nouvelles options de configuration

Prerequisites

Instance Gestion des API dans le niveau de service Développeur ou Premium. Si nécessaire, suivez le guide de démarrage rapide suivant : Créer une instance Gestion des API Azure.
Provisionnez une ressource de passerelle sur l’instance.
Activez une identité managée affectée par le système sur l’instance.
Image de conteneur de passerelle auto-hébergé version 2.2 ou ultérieure

Notes de limitations

Seule l’identité gérée par le système est prise en charge.

Créer des rôles personnalisées

Créez les deux rôles personnalisés suivants qui sont attribués dans les étapes ultérieures. Vous pouvez utiliser les autorisations répertoriées dans les modèles JSON suivants pour créer les rôles personnalisés à l’aide du portail Azure, d’Azure CLI, d’Azure PowerShell ou d’autres outils Azure.

Lors de la configuration des rôles personnalisés, mettez à jour la AssignableScopes propriété avec les valeurs d’étendue appropriées pour votre annuaire, par exemple un abonnement dans lequel votre instance Gestion des API est déployée.

Rôle de service validateur d’accès à l’API de configuration de gestion des 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}"
  ]
}

Rôle de lecteur de configuration de la passerelle de gestion des 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}"
  ]
}

Ajouter des attributions de rôle

Assigner un rôle de service validateur d’accès à l’API de configuration Gestion des API

Attribuez le rôle de service de validateur d'accès à la configuration de gestion des API à l'identité managée de l'instance de gestion des API. Pour obtenir des étapes détaillées pour attribuer un rôle, consultez Affecter des rôles Azure à l’aide du portail.

Étendue : groupe de ressources ou abonnement dans lequel l’instance Gestion des API est déployée
Rôle : Service de validation d'accès à l'API pour la configuration de la gestion des API
Attribuer l’accès à : identité managée de l’instance Gestion des API

Attribuer le rôle lecteur de configuration de la passerelle Gestion des API

Étape 1 : Inscrire l’application Microsoft Entra

Créez une application Microsoft Entra. Pour connaître les étapes à suivre, consultez Créer une application Microsoft Entra et un principal de service qui peuvent accéder aux ressources. L’application Microsoft Entra est utilisée par la passerelle auto-hébergée pour s’authentifier auprès de l’instance Gestion des API.

Générer une clé secrète client
Notez les valeurs d’application suivantes à utiliser dans la section suivante lors du déploiement de la passerelle auto-hébergée : ID d’application (client), ID d’annuaire (locataire) et clé secrète client

Étape 2 : Attribuer un rôle de service lecteur de configuration de passerelle de gestion des API

Attribuez le rôle de service lecteur de configuration de la passerelle de gestion des API à l’application.

Étendue : Instance gestion des API (ou groupe de ressources ou abonnement dans lequel l’application est déployée)
Rôle : Lecteur de configuration de la passerelle de gestion des API
Attribuer l’accès à : application Microsoft Entra

Déployer la passerelle auto-hébergée

Déployez la passerelle auto-hébergée sur Kubernetes, en ajoutant les paramètres d’inscription d’application Microsoft Entra à l’élément data des passerelles ConfigMap. Dans l’exemple de fichier de configuration YAML suivant, la passerelle est nommée mygw et le fichier est nommé mygw.yaml.

Important

Si vous suivez les instructions de déploiement Kubernetes existantes :

Veillez à omettre l’étape pour stocker la clé d’authentification par défaut à l’aide de la kubectl create secret generic commande.
Remplacez le fichier de configuration de base suivant pour le fichier YAML par défaut généré par le portail Azure. Le fichier suivant ajoute la configuration Microsoft Entra à la place de la configuration pour utiliser une clé d’authentification.

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

Déployez la passerelle sur Kubernetes avec la commande suivante :

kubectl apply -f mygw.yaml

Vérifiez que la passerelle est en cours d’exécution

Exécutez la commande suivante pour vérifier si le déploiement a réussi. La création de tous les objets et l’initialisation des pods peuvent prendre un peu de temps.
```
kubectl get deployments
```
Il devrait retourner
```
NAME             READY   UP-TO-DATE   AVAILABLE   AGE
<gateway-name>   1/1     1            1           18s
```

Exécutez la commande suivante pour vérifier si les services ont été correctement créés. Vos adresses IP de service et vos ports seront différents.

kubectl get services

Il devrait retourner

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

Revenez au portail Azure et sélectionnez Vue d’ensemble.
Vérifiez qu’État affiche une coche verte, suivie d’un nombre de nœuds qui correspond au nombre de réplicas spécifiés dans le fichier YAML. Cela signifie que les pods de passerelle auto-hébergés déployés communiquent correctement avec le service de gestion des API et ont un « battement de cœur » régulier.

Conseil / Astuce

Exécutez la commande kubectl logs deployment/<gateway-name> pour afficher les logs d'un pod sélectionné aléatoirement s'il y en a plusieurs.
Exécutez kubectl logs -h pour un ensemble complet d’options de commande, telles que la façon d’afficher les journaux d’un pod ou d’un conteneur spécifique.

En savoir plus sur la gestion des API pour la passerelle auto-hébergée.
En savoir plus sur les conseils relatifs à l’exécution de la passerelle auto-hébergée sur Kubernetes en production.
Découvrez comment déployer une passerelle auto-hébergée Gestion des API sur des clusters Kubernetes avec Azure Arc.

Rétroaction

Cette page a-t-elle été utile ?

Last updated on 2025-10-10