Использование проверки подлинности Microsoft Entra для локального шлюза

Статья
2025-04-06

ОБЛАСТЬ ПРИМЕНЕНИЯ: Разработчик | Премия

Для локального шлюза управления API Azure требуется подключение к связанному облачному экземпляру службы управления API для создания отчетов, проверки и применения обновлений конфигурации, а также отправки метрик и событий.

Помимо использования токена доступа шлюза (ключа аутентификации) для подключения к экземпляру облачного управления API, можно разрешить локально размещенному шлюзу аутентифицироваться в связанном облачном экземпляре, используя приложение Microsoft Entra. При проверке подлинности Microsoft Entra можно настроить более длительное время истечения срока действия секретов и использовать стандартные шаги для управления секретами и смены секретов в Active Directory.

Обзор сценария

API конфигурации локального шлюза может проверить Azure RBAC, чтобы определить, кто имеет разрешения на чтение конфигурации шлюза. После того как вы создадите приложение Microsoft Entra с заданными разрешениями, локальный шлюз сможет аутентифицироваться в экземпляре управления API через это приложение.

Чтобы включить проверку подлинности Microsoft Entra, выполните следующие действия.

Создайте две пользовательские роли, чтобы:
- Разрешить API конфигурации получить доступ к данным RBAC клиента
- Предоставление разрешений на чтение конфигурации локального шлюза
Предоставление RBAC-доступа к управляемому удостоверению экземпляра управления API
Создание приложения Microsoft Entra и предоставление ему доступа для чтения конфигурации шлюза
Развертывание шлюза с новыми параметрами конфигурации

Предпосылки

Экземпляр службы "Управление API" в уровне "Разработчик" или "Премиум". При необходимости выполните следующее краткое руководство: Создайте экземпляр службы Управление API Azure.
Развертывание ресурса шлюза на экземпляре.
Включите системное управляемое удостоверение на экземпляре.
Образ контейнера локального шлюза версии 2.2 или более поздней

Заметки об ограничениях

Поддерживается только назначаемое системой управляемое удостоверение.

Создание настраиваемых ролей

Создайте следующие две пользовательские роли , назначенные на последующих шагах. Разрешения, перечисленные в следующих шаблонах JSON, можно использовать для создания пользовательских ролей с помощью портала Azure, Azure CLI, Azure PowerShell или других средств Azure.

При настройке настраиваемых ролей обновите свойство области AssignableScopes соответствующими значениями для вашего каталога, например, подписка, в которой развернут экземпляр API Management.

Роль службы проверки доступа к API управления конфигурацией 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}"
  ]
}

Роль читателя конфигурации шлюза управления 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}"
  ]
}

Добавление назначений ролей

Назначить роль службы проверки конфигурации управления API для проверки доступа к API

Назначьте роль службы проверки доступа к Configuration API в управляемом удостоверении экземпляра службы управления API. Подробные инструкции по назначению роли см. в статье "Назначение ролей Azure" с помощью портала.

Область: группа ресурсов или подписка, в которой развернут экземпляр службы управления API
Роль: служба проверки доступа к API в конфигурации управления API
Назначение доступа: управляемое удостоверение экземпляра службы управления API

Назначение роли читателя конфигурации шлюза управления API

Шаг 1. Регистрация приложения Microsoft Entra

Создайте новое приложение Microsoft Entra. См. инструкцию в статье "Создайте приложение Microsoft Entra и служебный принципал для доступа к ресурсам". Это приложение будет использоваться самостоятельно размещенным шлюзом для аутентификации в экземпляре API Management.

Создание секрета клиента
Запишите следующие значения приложения для использования в следующем разделе при развертывании локального шлюза: идентификатор приложения (клиента), идентификатор каталога (клиента) и секрет клиента.

Шаг 2. Назначение сервисной роли читателя конфигурации шлюза управления API

Назначьте приложению роль службы для чтения конфигурации шлюза управления API.

Область: экземпляр управления API (или группа ресурсов или подписка, в которой она развернута)
Роль: роль читателя конфигурации шлюза управления API
Назначить доступ к приложению Microsoft Entra

Развертывание локального шлюза

Разверните самостоятельно размещенный шлюз в Kubernetes, добавив параметры регистрации приложений Microsoft Entra в элемент data шлюзов ConfigMap. В следующем примере файла конфигурации YAML шлюз называется mygw , а файл называется mygw.yaml.

Это важно

Если вы используете существующие рекомендации по развертыванию Kubernetes:

Не забудьте пропустить шаг для хранения ключа проверки подлинности по умолчанию с помощью kubectl create secret generic команды.
Замените следующий базовый файл конфигурации для файла YAML по умолчанию, созданного на портале Azure. Следующий файл добавляет конфигурацию Microsoft Entra вместо конфигурации для использования ключа проверки подлинности.

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

Разверните шлюз в Kubernetes с помощью следующей команды:

kubectl apply -f mygw.yaml

Убедитесь, что шлюз запущен

Выполните следующую команду, чтобы проверить успешность развертывания. Для создания всех объектов и инициализации подов может потребоваться немного времени.
```
kubectl get deployments
```
Он должен возвращать
```
NAME             READY   UP-TO-DATE   AVAILABLE   AGE
<gateway-name>   1/1     1            1           18s
```

Выполните следующую команду, чтобы проверить успешность создания служб. IP-адреса и порты службы будут отличаться.

kubectl get services

Он должен возвращать

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

Вернитесь на портал Azure и выберите "Обзор".
Убедитесь, что состояние отображает зеленый флажок, за которым следует число узлов, которое соответствует количеству реплик, указанных в файле YAML. Это состояние означает, что развернутые модули pod с самостоятельным хостингом успешно взаимодействуют со службой управления API и имеют регулярный "пульс".

Подсказка

Выполните команду kubectl logs deployment/<gateway-name>, чтобы просмотреть журналы из случайно выбранного pod, если их существует несколько.
Запустите kubectl logs -h для полного набора параметров команды, например, чтобы просмотреть журналы для конкретного pod или контейнера.

Дополнительные сведения об локальном шлюзе управления API.
Узнайте больше о руководстве по запуску самостоятельно размещаемого шлюза в Kubernetes в рабочей среде.
Узнайте , как развернуть локальный шлюз управления API в кластерах Kubernetes с поддержкой Azure Arc.