Guia de instalação: implantar o SDK do Microsoft Entra para AgentID

O SDK Microsoft Entra para ID do Agente é um serviço de autenticação containerizado pronto para ser implantado que simplifica a aquisição de tokens seguros para seus aplicativos. Este guia de instalação fornece instruções passo a passo para implantar o contêiner do SDK em ambientes kubernetes, docker e Azure, eliminando a necessidade de inserir credenciais confidenciais diretamente no código do aplicativo.

Pré-requisitos

Acesso ao Registro de Artefatos Microsoft
Runtime do contêiner (Docker, Kubernetes ou serviço de contêiner)
Registre um novo aplicativo no centro de administração do Microsoft Entra, configurado para Contações somente neste diretório organizacional. Consulte Registrar um aplicativo para obter mais detalhes. Registre os seguintes valores na página visão geral do aplicativo para uso posterior:
- ID do aplicativo (cliente)
- ID do diretório (locatário)
Credenciais para o aplicativo:
- Segredo do Cliente ou Certificado armazenado com segurança (por exemplo, Azure Key Vault)
Para implantações Azure: CLI do Azure ou acesso ao portal Azure

Imagem do contêiner

O SDK do Microsoft Entra para ID de Agente é distribuído como uma imagem de contêiner do registro de artefatos

mcr.microsoft.com/entra-sdk/auth-sidecar

Padrões de implantação

O SDK do Microsoft Entra para ID do Agente foi projetado para ser executado como um contêiner complementar ao lado do aplicativo. Isso permite que seu aplicativo descarrega a aquisição e o gerenciamento de tokens para o SDK por meio de chamadas HTTP e mantém as credenciais confidenciais fora do código do aplicativo. A seguir estão padrões de implantação comuns e devem ser adaptados ao seu ambiente específico.

Padrão do Kubernetes

Implante o SDK do Microsoft Entra para a Identidade do Agente no mesmo pod do contêiner do aplicativo para comunicação local segura no pod. Esse padrão garante que o serviço de autenticação seja executado junto com seu aplicativo, permitindo a aquisição rápida de token baseado em HTTP, mantendo as credenciais isoladas do código do aplicativo:

apiVersion: v1
kind: Pod
metadata:
  # Your application container
  name: myapp
spec:
  containers:
  - name: app
    image: myregistry/myapp:latest
    ports:
    - containerPort: 8080
    env:
    - name: SIDECAR_URL
      value: "http://localhost:5000"
  # Microsoft Entra SDK for Agent ID container
  - name: sidecar
    image: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0
    ports:
    - containerPort: 5000
    env:
    - name: AzureAd__TenantId
      value: "your-tenant-id"
    - name: AzureAd__ClientId
      value: "your-client-id"
    - name: AzureAd__ClientCredentials__0__SourceType
      value: "KeyVault"
    - name: AzureAd__ClientCredentials__0__KeyVaultUrl
      value: "https://your-keyvault.vault.azure.net"
    - name: AzureAd__ClientCredentials__0__KeyVaultCertificateName
      value: "your-cert-name"

Implantação do Kubernetes

Consulte o tutorial Kubernetes no Azure – Preparar um aplicativo para o AKS (Serviço de Kubernetes do Azure) se quiser direcionar para o Azure Kubernetes Service. Esse padrão usa um recurso de implantação para gerenciar o aplicativo e Microsoft Entra SDK para contêineres de ID do agente, permitindo dimensionamento e atualizações. A implantação também lida com verificações de integridade e alocação de recursos, garantindo uma operação segura em ambientes de produção:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      serviceAccountName: myapp-sa
      containers:
      - name: app
        image: myregistry/myapp:latest
        ports:
        - containerPort: 8080
        env:
        - name: SIDECAR_URL
          value: "http://localhost:5000"
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"
      
      - name: sidecar
        image: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0
        ports:
        - containerPort: 5000
        env:
        - name: AzureAd__TenantId
          valueFrom:
            configMapKeyRef:
              name: app-config
              key: tenant-id
        - name: AzureAd__ClientId
          valueFrom:
            configMapKeyRef:
              name: app-config
              key: client-id
        - name: AzureAd__Instance
          value: "https://login.microsoftonline.com/"
        resources:
          requests:
            memory: "128Mi"
            cpu: "100m"
          limits:
            memory: "256Mi"
            cpu: "250m"
        livenessProbe:
          httpGet:
            path: /health
            port: 5000
          initialDelaySeconds: 10
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 5000
          initialDelaySeconds: 5
          periodSeconds: 5

Docker Compose

Ao trabalhar em um ambiente do Docker, você pode usar o Docker Compose para definir e executar aplicativos de vários contêineres. O exemplo a seguir demonstra como configurar o SDK do Microsoft Entra para a ID do Agente junto com o contêiner do aplicativo em um ambiente de desenvolvimento local:

version: '3.8'

services:
  app:
    image: myregistry/myapp:latest
    ports:
      - "8080:8080"
    environment:
      - AzureAd__TenantId=${TENANT_ID}
      - AzureAd__ClientId=${CLIENT_ID}
      - AzureAd__ClientCredentials__0__SourceType=ClientSecret
      - AzureAd__ClientCredentials__0__ClientSecret=${CLIENT_SECRET}
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

Azure AKS (serviço Kubernetes) com Identidade Gerenciada

Ao implantar no AKS, você pode usar Azure Managed Identity para autenticar o SDK do Microsoft Entra para a ID do Agente sem armazenar credenciais na configuração. Primeiro, você precisará habilitar ID de carga de trabalho do Microsoft Entra no cluster do AKS e criar uma credencial de identidade federada para sua identidade gerenciada. Em seguida, configure o SDK para usar a identidade gerenciada para autenticação.

Etapa 1: Criar Identidade Gerenciada

Criar uma identidade gerenciada e atribuí-la às permissões apropriadas

# Create managed identity
az identity create \
  --resource-group myResourceGroup \
  --name myapp-identity

# Get the identity details
IDENTITY_CLIENT_ID=$(az identity show \
  --resource-group myResourceGroup \
  --name myapp-identity \
  --query clientId -o tsv)

IDENTITY_OBJECT_ID=$(az identity show \
  --resource-group myResourceGroup \
  --name myapp-identity \
  --query principalId -o tsv)

Passo 2: Atribuir permissões

Conceda as permissões de identidade gerenciada para acessar APIs downstream:

# Example: Grant permission to call Microsoft Graph
az ad app permission add \
  --id $IDENTITY_CLIENT_ID \
  --api 00000003-0000-0000-c000-000000000000 \
  --api-permissions e1fe6dd8-ba31-4d61-89e7-88639da4683d=Scope

Etapa 3: Configurar a identidade da carga de trabalho

Criar uma conta de serviço com federação de identidade de carga de trabalho:

export AKS_OIDC_ISSUER=$(az aks show \
  --resource-group myResourceGroup \
  --name myAKSCluster \
  --query "oidcIssuerProfile.issuerUrl" -o tsv)

az identity federated-credential create \
  --name myapp-federated-identity \
  --identity-name myapp-identity \
  --resource-group myResourceGroup \
  --issuer $AKS_OIDC_ISSUER \
  --subject system:serviceaccount:default:myapp-sa

Etapa 4: Implantar com Identidade de Trabalho

No exemplo de implantação a seguir, o SDK do Microsoft Entra para ID do Agente é configurado para usar o ID de carga de trabalho do Microsoft Entra para autenticação, utilizando a projeção de tokens baseada em arquivos. O SignedAssertionFilePath tipo de credencial lê o token do arquivo projetado pelo webhook de identidade de carga de trabalho:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: myapp-sa
  namespace: default
  annotations:
    azure.workload.identity/client-id: "<MANAGED_IDENTITY_CLIENT_ID>"

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp-deployment
spec:
  template:
    metadata:
      labels:
        azure.workload.identity/use: "true"
    spec:
      serviceAccountName: myapp-sa
      containers:
      - name: app
        image: myregistry/myapp:latest
        env:
        - name: SIDECAR_URL
          value: "http://localhost:5000"
      
      - name: sidecar
        image: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0
        ports:
        - containerPort: 5000
        env:
        - name: AzureAd__TenantId
          value: "your-tenant-id"
        - name: AzureAd__ClientId
          value: "<MANAGED_IDENTITY_CLIENT_ID>"
        
        # Workload Identity credentials - uses file-based token projection
        - name: AzureAd__ClientCredentials__0__SourceType
          value: "SignedAssertionFilePath"

Observação: O webhook de identidade de carga de trabalho projeta automaticamente o token federado em /var/run/secrets/azure/tokens/azure-identity-token ou em uma variável de ambiente quando o pod possui o rótulo necessário e a anotação da conta de serviço.

Configuração de rede

A configuração de rede correta é essencial para garantir a comunicação segura entre o SDK do Microsoft Entra para iD do agente e serviços externos, restringindo o acesso não autorizado. A configuração adequada impede vulnerabilidades de segurança e garante a conectividade confiável com endpoints Microsoft Entra ID. Use as diretrizes a seguir para configurar o acesso à rede para o SDK, dependendo do seu ambiente de implantação.

Somente comunicação interna

Para configurar o SDK do Microsoft Entra para a ID do Agente somente para comunicação local do pod interno, defina a URL do ponto de extremidade em seu aplicativo para apontar para localhost ou 127.0.0.1, dependendo do seu ambiente:

containers:
- name: sidecar
  env:
  - name: Kestrel__Endpoints__Http__Url
    value: "http://127.0.0.1:5000" # Same pod, localhost communication

Cuidado

Nunca exponha o SDK do Microsoft Entra para ID do agente externamente por meio de LoadBalancer ou Ingress. Ele só deve estar acessível no contêiner do aplicativo.

Políticas de rede

Para restringir ainda mais o acesso à rede, considere implementar políticas de rede do Kubernetes para limitar o tráfego de e para o contêiner do SDK:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: sidecar-network-policy
spec:
  podSelector:
    matchLabels:
      app: myapp
  policyTypes:
  - Ingress
  - Egress
  ingress:
  # No external ingress rules - only pod-local communication
  egress:
  - to:
    - namespaceSelector:
        matchLabels:
          name: kube-system
    ports:
    - protocol: TCP
      port: 53  # DNS
  - to:
    - podSelector: {}
  - to:
    # Allow outbound to Microsoft Entra ID
    ports:
    - protocol: TCP
      port: 443

Exames de saúde

O SDK Microsoft Entra para ID do Agente expõe um ponto de extremidade /health para investigações de disponibilidade e preparação, garantindo que o contêiner esteja sendo executado com segurança. Configurar sua implantação para incluir estas sondas.

livenessProbe:
  httpGet:
    path: /health
    port: 5000
  initialDelaySeconds: 10
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /health
    port: 5000
  initialDelaySeconds: 5
  periodSeconds: 5

Requisitos de recursos

As alocações de recursos recomendadas são as seguintes, mas certifique-se de ajustar com base na frequência de aquisição de token, número de APIs downstream configuradas e requisitos de tamanho de cache:

Perfil de Recurso	Memória	CPU
Mínimo	128Mi	100m
Recomendado	256Mi	250m
Tráfego alto	512Mi	500 m

Considerações de dimensionamento

O SDK do Microsoft Entra para Identificação do Agente foi projetado para escalar com o seu aplicativo.

Design sem estado: cada instância do SDK mantém seu próprio cache de token
Dimensionamento horizontal: dimensionar adicionando mais pods de aplicativo (cada um com sua própria instância do SDK)
Aquecimento de cache: considere implementar estratégias de aquecimento de cache para cenários de alto tráfego

Solução de problemas de implantação

Problemas comuns que você pode encontrar podem ser devido a valores de configuração inválidos, conectividade de rede com Microsoft Entra ID ou credenciais ou certificados ausentes. Verifique se a identidade gerenciada ou a entidade de serviço tem as permissões de aplicativo corretas, o consentimento do administrador concedido (se necessário) e as atribuições de função corretas.

Veja a seguir algumas etapas comuns de solução de problemas que podem ajudar a resolver problemas de implantação:

O contêiner não está iniciando.

Verifique os logs de contêineres:

kubectl logs <pod-name> -c sidecar

Falhas na checagem de saúde

Verifique se o SDK do Microsoft Entra para a ID do Agente está respondendo:

kubectl exec <pod-name> -c sidecar -- curl http://localhost:5000/health

Para obter etapas mais detalhadas sobre a solução de problemas, consulte o guia de solução de problemas.

Comentários

Esta página foi útil?

Last updated on 2026-04-19