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

O SDK do Microsoft Entra para AgentID é um serviço de autenticação em contêineres pronto para implantação que simplifica a aquisição de token seguro 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 MCR (Registro de Contêiner da 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 apenas para Contas 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 do Azure: CLI do Azure ou acesso ao portal do Azure

Imagem de contêiner

O SDK do Microsoft Entra para AgentID é distribuído como uma imagem de contêiner do MCR.

mcr.microsoft.com/entra-sdk/auth-sidecar:<tag>

Marcas de versão

• latest – Versão estável mais recente
• <version> – Versões específicas (por exemplo, 1.0.0)
• <version>-preview – Versões prévias

Padrões de implantação

O SDK do Microsoft Entra para AgentID 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 AgentID no mesmo pod que o contêiner do aplicativo para comunicação segura e local ao 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 AgentID 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

Confira o tutorial do Kubernetes no Azure – Preparar um aplicativo para o AKS (Serviço de Kubernetes do Azure) se você quiser direcionar os Serviços de Kubernetes do Azure. Esse padrão usa um recurso de implantação para gerenciar o aplicativo e o SDK do Microsoft Entra para contêineres AgentID, 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 AgentID ao lado do contêiner do aplicativo em um ambiente de desenvolvimento local:

version: '3.8'

services:
  app:
    image: myregistry/myapp:latest
    ports:
      - "8080:8080"
    en - sidecar 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

AKS (Serviço de Kubernetes do Azure) com Identidade Gerenciada

Ao implantar no AKS, você pode usar a Identidade Gerenciada do Azure para autenticar o SDK do Microsoft Entra para AgentID sem armazenar credenciais na configuração. Primeiro, você precisará habilitar a Identidade de Carga de Trabalho do Azure AD em seu 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 AgentID está configurado para usar a Identidade de Carga de Trabalho do Azure AD para autenticação usando a projeção de token baseada em arquivo. 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 AgentID 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 os endereços de extremidade do 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 AgentID somente para comunicação local interna do pod, defina a URL do ponto de extremidade no 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

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

Verificações de Saúde

O SDK do Microsoft Entra para AgentID expõe um /health endpoint para sondas de vivacidade e prontidã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:

Considerações sobre dimensionamento

O SDK do Microsoft Entra para AgentID foi projetado para escalar junto com seu aplicativo.

1. Design sem estado: cada instância do SDK mantém seu próprio cache de token
2. Dimensionamento horizontal: dimensionar adicionando mais pods de aplicativo (cada um com sua própria instância do SDK)
3. 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 a ID do Microsoft Entra 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 inicia

Verifique os logs de contêineres:

kubectl logs <pod-name> -c sidecar

Falhas na checagem de integridade

Verifique se o SDK do Microsoft Entra para AgentID 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.

Próximas etapas

• Definir configurações – Configurar a configuração de identidade
• Examinar pontos de extremidade – Explorar a API HTTP
• Práticas recomendadas de segurança – proteger sua implantação
• Escolher um cenário – Comece com um exemplo guiado