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

Article
10/25/2023

S’APPLIQUE À : Développeur | Premium

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

En plus d’utiliser un jeton d’accès de passerelle (clé d’authentification) pour vous connecter à son instance Gestion des API cloud, vous pouvez autoriser la passerelle auto-hébergée à s’authentifier sur son instance cloud associée avec 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 permuter les secrets dans Active Directory.

Présentation du scénario

L’API de configuration de passerelle auto-hébergée peut examiner RBAC Azure pour déterminer qui dispose des autorisations nécessaires pour lire la configuration de la passerelle. Une fois que vous avez créé une application Microsoft Entra avec ces autorisations, la passerelle auto-hébergée peut s’authentifier sur l’instance Gestion des API avec l’application.

Pour activer l’authentification Microsoft Entra, effectuez les étapes suivantes :

Créez deux rôles personnalisés pour :
- Permettre à l’API de configuration d’accéder aux informations RBAC du client
- Accorder des autorisations de lecture de 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 en lecture sur la configuration de la passerelle
Déployer la passerelle avec de nouvelles options de configuration

Prérequis

Une instance Gestion des API dans le niveau de service Développeur ou Premium. Si besoin, consultez ce guide de démarrage rapide : Créer une instance Gestion des API Azure.
Approvisionnez une ressource de passerelle sur l’instance.
Activez une identité managée affectée par le système sur l'instance.
Image du conteneur de la passerelle auto-hébergée version 2.2 ou ultérieure

Remarques sur les limitations

Seule l’identité managée affecté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 propriété AssignableScopes avec les valeurs d’étendue appropriées pour votre répertoire, comme 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 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 lecteur de configuration de la passerelle 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 validateur d’accès à l’API de configuration Gestion des API à l’identité managée de l’instance Gestion des API. Pour les étapes détaillées d’attribution d’un rôle, consultez Attribuer 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 : rôle de service validateur d’accès à l’API de configuration 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 une application Microsoft Entra

Créez une application Microsoft Entra. Pour connaître les étapes, consultez Créer une application et un principal de service Microsoft Entra pouvant accéder aux ressources. Cette application sera 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
Prenez note des valeurs d’application suivantes à utiliser dans la section d’après lors du déploiement de la passerelle auto-hébergée : ID d’application (client), ID de répertoire (locataire) et clé secrète client

Étape 2 : Attribuer le rôle de service lecteur de configuration de la passerelle Gestion des API

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

Étendue : l’instance Gestion des API (ou groupe de ressources ou abonnement dans lequel elle est déployée)
Rôle : rôle lecteur de configuration de la passerelle 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 de stockage de la clé d’authentification par défaut à l’aide de la commande kubectl create secret generic.
Remplacez le fichier de configuration de base suivant par le fichier YAML par défaut généré pour vous dans le portail Azure. Le fichier suivant ajoute la configuration Microsoft Entra à la place de la configuration qui permet d’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érifier que la passerelle est en cours d’exécution

Exécutez la commande suivante pour vérifier si le déploiement a réussi. Notez que le temps nécessaire à la création de tous les objets et à l’initialisation des pods peut être long.
```
kubectl get deployments
```
Il devrait y avoir un retour
```
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 bien été créés. Les adresses IP et les ports de votre service seront différents.

kubectl get services

Il devrait y avoir un retour

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, puis 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. Cet état signifie que les pods de passerelle auto-hébergés déployés communiquent avec le service API management et présentent une « pulsation » normale.

Conseil

Exécutez la commande kubectl logs deployment/<gateway-name> pour afficher les journaux d’un pod sélectionné de manière aléatoire, s’il en existe plusieurs.
Exécutez kubectl logs -h pour obtenir un ensemble complet d’options de commande, par exemple, comment afficher les journaux d’un pod ou d’un conteneur spécifique.

Étapes suivantes

Découvrez-en plus avec la vue d’ensemble de la passerelle auto-hébergée Gestion des API.
Découvrez les conseils pour exécuter 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.