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

Artigo
10/20/2023

APLICA-SE A: Desenvolvedor | Premium

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

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

Visão geral do cenário

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

Conclua as etapas a seguir para habilitar a autenticação do Microsoft Entra:

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

Pré-requisitos

Uma instância do Gerenciamento de API na camada de serviço Desenvolvedor ou Premium. Se necessário, conclua o seguinte início rápido: Criar uma instância do 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, que serão 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 os valores de escopo apropriados para o seu diretório, como uma assinatura na qual a instância do Gerenciamento de API 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 do 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, confira Atribuir funções do Azure usando o portal.

Escopo: O grupo de recursos ou a assinatura na qual a instância do Gerenciamento de API está 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 do Gerenciamento de API

Atribuir função de leitor de configuração do gateway do Gerenciamento de API

Etapa 1: Registrar um aplicativo Microsoft Entra

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

Gerar um segredo de cliente
Anote os seguintes valores do 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 função de serviço do leitor de configuração do gateway do Gerenciamento de API

Atribua a função de serviço do leitor de configuração do gateway do Gerenciamento de API ao aplicativo.

Escopo: a instância do Gerenciamento de API (ou o grupo de recursos ou a assinatura na qual ele está implantado)
Função: Função de leitor de configuração do gateway do Gerenciamento de API
Atribua o 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 de arquivo de configuração YAML a seguir, o gateway é denominado mygw e o arquivo é denominado mygw.yaml.

Importante

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

Certifique-se de omitir a etapa para armazenar a chave de autenticação padrão usando o comando kubectl create secret generic.
Substitua o seguinte arquivo de configuração básica pelo arquivo YAML padrão que é gerado para você no portal do Azure. 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. Poderá levar algum tempo para que todos os objetos sejam criados e os pods sejam inicializados.
```
kubectl get deployments
```
Isso 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. Os seus IPs de serviço e as portas serão diferentes.

kubectl get services

Isso 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 ao 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 do gateway auto-hospedado implantados estão se comunicando com êxito com o serviço do Gerenciamento de API e têm uma "pulsação" regular.

Dica

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

Próximas etapas

Saiba mais sobre a visão geral do gateway auto-hospedado do Gerenciamento de API.
Saiba mais sobre as diretrizes para executar o gateway auto-hospedado no Kubernetes em produção.
Saiba como implantar o gateway auto-hospedado do Gerenciamento de API em clusters do Kubernetes habilitados para Azure Arc.

Compartilhar via