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

O Microsoft Entra SDK for Agent ID é um serviço de autenticação containerizada pronto a ser implementado que simplifica a aquisição segura de tokens para as suas aplicações. Este guia de instalação fornece instruções passo a passo para implementar o contentor SDK em ambientes Kubernetes, Docker e Azure, eliminando a necessidade de incorporar credenciais sensíveis diretamente no seu código de aplicação.

Pré-requisitos

Acesso ao Registo de Artefactos Microsoft
Tempo de execução do contêiner (Docker, Kubernetes ou serviço de contêiner)
Registe uma nova aplicação no centro de administração Microsoft Entra, configurada apenas para Contas neste diretório organizacional. Consulte Registar uma candidatura para obter mais detalhes. Registre os seguintes valores na página Visão geral do aplicativo para uso posterior:
- ID da aplicação (cliente)
- ID do diretório (inquilino)
Credenciais para o aplicativo:
- Segredo do Cliente ou Certificado armazenado de forma segura (por exemplo, Azure Key Vault)
Para implementações Azure: CLI do Azure ou acesso ao portal Azure

Imagem de container

O Microsoft Entra SDK para ID de Agente é distribuído como uma imagem de contentor a partir do registo de artefatos

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

Padrões de implantação

O Microsoft Entra SDK para ID de Agente foi concebido para funcionar como um contentor companheiro juntamente com a sua aplicação. Isso permite que seu aplicativo descarregue 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 Kubernetes

Implemente o Microsoft Entra SDK para Agent ID no mesmo pod que o seu contentor de aplicação para uma comunicação pod-local segura. Esse padrão garante que o serviço de autenticação seja executado junto com seu aplicativo, permitindo a aquisição rápida de tokens baseados em HTTP enquanto mantém 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

Veja o tutorial do Kubernetes no Azure - Prepare uma aplicação para o Serviço de Kubernetes do Azure (AKS) se quiser direcionar o Serviço de Kubernetes do Azure. Este padrão utiliza um recurso de Deployment para gerir a aplicação e o Microsoft Entra SDK para contentores de ID de Agente, permitindo escalabilidade 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 Docker, você pode usar o Docker Compose para definir e executar aplicativos de vários contêineres. O exemplo seguinte demonstra como configurar o Microsoft Entra SDK para Agent ID juntamente com o seu contentor de aplicação num 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

Serviço Azure Kubernetes (AKS) com Identidade Gerida

Ao implementar no AKS, pode usar Azure Identidade Gerida para autenticar o SDK Microsoft Entra para o ID do Agente sem armazenar credenciais na configuração. Primeiro, terá de ativar o ID de carga de trabalho Microsoft Entra no seu cluster AKS e criar uma credencial de identidade federada para a sua identidade gerida. Em seguida, configure o SDK para usar a identidade gerenciada para autenticação.

Etapa 1: Criar identidade gerenciada

Crie uma identidade gerenciada e atribua-lhe as 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)

Etapa 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

Crie uma conta de serviço com federação de identidades 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 implementação seguinte, o Microsoft Entra SDK para Agent ID está configurado para usar ID de carga de trabalho Microsoft Entra para autenticação usando projeção de token baseada em ficheiros. O SignedAssertionFilePath tipo de credencial lê o token do arquivo projetado pelo webhook de identidade da 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"

Nota: O webhook de identidade de workload projeta automaticamente o token federado para /var/run/secrets/azure/tokens/azure-identity-token ou uma variável de ambiente quando o pod tem o rótulo e a anotação de conta de serviço necessários.

Configuração de rede

A configuração correta da rede é essencial para garantir uma comunicação segura entre o Microsoft Entra SDK para o ID do Agente e serviços externos, restringindo ao mesmo tempo o acesso não autorizado. Uma configuração adequada previne vulnerabilidades de segurança e garante uma conectividade fiável aos endpoints do Microsoft Entra ID. Use as diretrizes a seguir para configurar o acesso à rede para o SDK, dependendo do seu ambiente de implantação.

Apenas comunicação interna

Para configurar o SDK do Microsoft Entra para o ID do Agente, apenas para comunicação interna local no pod, configure o URL do endpoint na sua aplicação 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

Atenção

Nunca exponha o SDK do Microsoft Entra para ID de Agente externamente via LoadBalancer ou Ingress. Ele só deve ser acessível a partir do 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 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

Controlos sanitários

O Microsoft Entra SDK para Agent ID expõe um endpoint /health para verificação de vivacidade e prontidão, assegurando que o contentor está a operar de forma segura. Configure 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, no número de APIs downstream configuradas e nos requisitos de tamanho de cache:

Perfil de Recurso	Memory	CPU
Mínimo	128Mi	100 metros
Recomendado	256 Mi	250m
Tráfego elevado	512 Mi	500m

Considerações sobre o dimensionamento

O Microsoft Entra SDK para Agent ID foi concebido para escalar com a sua aplicação:

Design sem estado: cada instância do SDK mantém seu próprio cache de token
Dimensionamento horizontal: escalone adicionando mais pods de aplicações (cada um com a sua própria instância SDK)
Aquecimento de cache: considere a implementação de estratégias de aquecimento de cache para cenários de alto tráfego

Solução de problemas de implantação

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

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

O container não inicia

Verifique os logs do contêiner:

kubectl logs <pod-name> -c sidecar

Falhas na verificação de saúde

Verifique se o SDK Microsoft Entra para ID de Agente está a responder:

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

Para passos mais detalhados sobre resolução de problemas, consulte o guia de resolução de problemas.

Comentários

Esta página foi útil?

Last updated on 2026-04-19