Use a autenticação do Microsoft Entra para o gateway auto-hospedado

APLICA-SE A: Desenvolvedor | Premium

O gateway auto-hospedado do Gerenciamento de API do Azure precisa de conectividade com sua instância de Gerenciamento de API baseada em nuvem associada para relatar status, verificar e aplicar atualizações de configuração, e enviar métricas e eventos.

Além de usar um token de acesso de gateway (chave de autenticação) para se conectar com sua instância de Gerenciamento de API baseada em nuvem, você pode habilitar o gateway auto-hospedado para se autenticar em sua instância de nuvem associada usando um aplicativo do Microsoft Entra. Com a autenticação do Microsoft Entra, você pode configurar tempos de expiração mais longos para segredos e usar etapas padrão para gerenciar e rotacionar segredos no Active Directory.

Visão geral do cenário

A API de configuração de gateway auto-hospedada pode verificar o RBAC (controle de acesso baseado em função) do Azure para determinar quem tem permissões para ler a configuração do gateway. Depois de criar um aplicativo do Microsoft Entra com essas permissões, o gateway auto-hospedado pode se autenticar na instância de Gerenciamento de API usando o aplicativo.

Para habilitar a autenticação do Microsoft Entra, conclua as seguintes etapas:

Crie duas funções personalizadas para:
- Permitir que a API de configuração obtenha acesso às informações do RBAC do cliente
- Conceder permissões para ler a configuração do gateway autogerenciado
Conceder acesso de RBAC à identidade gerenciada da instância de Gerenciamento de API
Criar um aplicativo do Microsoft Entra e conceder-lhe acesso para ler a configuração do gateway
Implantar o gateway com novas opções de configuração

Pré-requisitos

Uma instância de Gerenciamento de API na camada de serviço do desenvolvedor ou premium. Se necessário, conclua o seguinte início rápido: criar uma instância de Gerenciamento de API do Azure.
Provisione um recurso de gateway na instância.
Habilite uma identidade gerenciada atribuída pelo sistema na instância.
Imagem de contêiner de gateway auto-hospedada versão 2.2 ou posterior

Notas sobre limitações

Há suporte apenas para a identidade gerenciada atribuída pelo sistema.

Criar funções personalizadas

Crie as duas funções personalizadas a seguir atribuídas em etapas posteriores. Você pode usar as permissões listadas nos seguintes modelos JSON para criar as funções personalizadas usando o portal do Azure, a CLI do Azure, o Azure PowerShell ou outras ferramentas do Azure.

Ao configurar as funções personalizadas, atualize a propriedade AssignableScopes com valores de escopo apropriados para seu diretório, como uma assinatura na qual sua instância de Gerenciamento de APIs está implantada.

Função de serviço validador de acesso à API de configuração do Gerenciamento de 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}"
  ]
}

Função de Leitor de Configuração do Gateway de Gerenciamento de 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}"
  ]
}

Adicionar atribuições de função

Atribuir a função de serviço validador de acesso à API de configuração do Gerenciamento de API

Atribua a função de serviço validador de acesso à API de configuração do Gerenciamento de API à identidade gerenciada da instância do Gerenciamento de API. Para obter etapas detalhadas para atribuir uma função, consulte Atribuir funções do Azure usando o portal.

Escopo: o grupo de recursos ou a assinatura na qual a instância de Gerenciamento de API é implantada
Função: função de serviço validador de acesso à API de configuração do Gerenciamento de API
Atribuir acesso a: Identidade gerenciada da instância de Gerenciamento de API

Atribuir função de Leitor de Configuração do Gateway de Gerenciamento de API

Etapa 1: Registrar o aplicativo Microsoft Entra

Crie um novo aplicativo do Microsoft Entra. Para as etapas, consulte Criar um aplicativo Microsoft Entra e uma entidade de serviço que possa acessar os recursos. O aplicativo Microsoft Entra é usado pelo gateway auto-hospedado para autenticar na instância de Gerenciamento de API.

Gerar um segredo do cliente
Anote os seguintes valores de aplicativo para uso na próxima seção ao implantar o gateway auto-hospedado: ID do aplicativo (cliente), ID do diretório (locatário) e segredo do cliente

Etapa 2: Atribuir a função de Serviço de Leitor de Configuração do Gateway de Gerenciamento de API

Atribua ao aplicativo a função de Leitor de Configuração do Gateway de Gerenciamento de API.

Escopo: a instância de Gerenciamento de API (ou grupo de recursos ou assinatura na qual o aplicativo é implantado)
Função: Leitor de configuração do Gateway de Gerenciamento de API
Atribuir acesso a: aplicativo Microsoft Entra

Implantar um gateway auto-hospedado

Implante o gateway auto-hospedado no Kubernetes, adicionando as configurações de registro do aplicativo Microsoft Entra ao dataelemento dos gatewaysConfigMap. No exemplo a seguir, no arquivo de configuração YAML, o gateway é chamado mygw e o arquivo é nomeado mygw.yaml.

Importante

Se você estiver seguindo as diretrizes de implantação existentes do Kubernetes:

Omita a etapa para armazenar a chave de autenticação padrão usando o kubectl create secret generic comando.
Substitua o arquivo de configuração básico a seguir pelo arquivo YAML padrão gerado pelo portal do Azure para você. O arquivo a seguir adiciona a configuração do Microsoft Entra no lugar da configuração para usar uma chave de autenticação.

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

Implante o gateway no Kubernetes com o seguinte comando:

kubectl apply -f mygw.yaml

Confirme se o gateway está em execução

Execute o comando a seguir para verificar se a implantação foi bem-sucedida. Pode levar um pouco de tempo para que todos os objetos sejam criados e que os pods sejam inicializados.
```
kubectl get deployments
```
Ele deve retornar
```
NAME             READY   UP-TO-DATE   AVAILABLE   AGE
<gateway-name>   1/1     1            1           18s
```

Execute o comando a seguir para verificar se os serviços foram criados com êxito. Seus IPs e portas de serviço serão diferentes.

kubectl get services

Ele deve retornar

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

Volte para o portal do Azure e selecione Visão geral.
Confirme se o status mostra uma marca de seleção verde seguida por uma contagem de nós que corresponde ao número de réplicas especificado no arquivo YAML. Esse status significa que os pods de gateway auto-hospedado implantados estão se comunicando com êxito com o serviço de Gerenciamento de API e têm uma "pulsação" regular.

Dica

Execute o kubectl logs deployment/<gateway-name> comando para exibir logs de um pod selecionado aleatoriamente se houver mais de um.
Execute o kubectl logs -h para um conjunto completo de opções de comando, como exibir logs para um pod ou contêiner específico.

Saiba mais sobre o Gerenciamento de API com o gateway autogerenciado.
Saiba mais sobre as orientações para executar o gateway autogerenciado no Kubernetes em produção.
Saiba como implantar o gateway auto-hospedado do Gerenciamento de API em clusters do Kubernetes habilitados para o Azure Arc.

Comentários

Esta página foi útil?

Last updated on 2025-10-10