Práticas recomendadas de segurança: proteção do SDK do Microsoft Entra para AgentID

Este guia fornece configuração de segurança abrangente e práticas recomendadas de proteção para implantar e operar com segurança o SDK do Microsoft Entra para ID do Agente em ambientes de produção. Ele abrange controles de segurança essenciais, incluindo isolamento de rede, gerenciamento de credenciais, validação de token, segurança de runtime e monitoramento para garantir que sua implantação do SDK siga as práticas recomendadas de segurança.

É seguro executar o SDK?

O SDK Microsoft Entra para ID do Agente foi projetado com segurança em mente, mas sua segurança depende das práticas de configuração e implantação adequadas. Siga estas práticas recomendadas para garantir uma implantação segura:

Segurança de rede

O isolamento de rede é fundamental para proteger as operações de autenticação. O SDK do Microsoft Entra para ID do Agente deve ser executado dentro de limites confiáveis com controles de acesso estritos e filtragem de tráfego abrangente. Isso inclui vinculação apenas no localhost, comunicação interna do pod e políticas de rede que impedem o acesso não autorizado a endpoints de autenticação.

Restringir o acesso ao SDK

Configure o Kestrel para escutar apenas no localhost para impedir o acesso externo à rede aos pontos de extremidade de autenticação.

containers:
- name: sidecar
  image: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0
  env:
  - name: Kestrel__Endpoints__Http__Url
    value: "http://127.0.0.1:5000"

Como alternativa, use a filtragem de host do Kestrel com AllowedHosts para restringir o acesso:

containers:
- name: sidecar
  image: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0
  env:
  - name: AllowedHosts
    value: "localhost;127.0.0.1"

Usar a comunicação local do pod

Configure seu aplicativo para se comunicar com o SDK do Microsoft Entra para o Agent ID por meio de localhost, garantindo que o tráfego permaneça dentro do mesmo pod e não se desloque pela rede.

containers:
- name: app
  env:
  - name: SIDECAR_URL
    value: "http://localhost:5000" # Pod-local communication only

Nunca exponha via LoadBalancer ou Ingress (isso permitiria a aquisição de token não autorizado fora do limite confiável):

# WRONG - exposes Microsoft Entra SDK for Agent ID publicly
apiVersion: v1
kind: Service
metadata:
  name: sidecar-service
spec:
  type: LoadBalancer # Exposes SDK publicly - INSECURE
  selector:
    app: myapp
  ports:
  - port: 5000

Gerenciamento de credenciais

O gerenciamento seguro de credenciais é fundamental para a segurança do SDK. Use identidades gerenciadas sempre que possível para eliminar segredos e siga o princípio de privilégio mínimo ao configurar credenciais de autenticação.

Preferir Identidade de Carga de Trabalho para contêineres

Use ID de carga de trabalho do Microsoft Entra para implantações em contêineres (AKS) para eliminar totalmente os segredos e garantir o gerenciamento seguro de credenciais com projeção de token baseada em arquivo:

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

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  template:
    metadata:
      labels:
        azure.workload.identity/use: "true"
    spec:
      serviceAccountName: myapp-sa
      containers:
      - name: sidecar
        image: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0
        env:
        - name: AzureAd__ClientId
          value: "<web-api-client-id>"
        
        # Workload Identity credentials - uses file-based token projection
        - name: AzureAd__ClientCredentials__0__SourceType
          value: "SignedAssertionFilePath"

Benefícios: A identidade da carga de trabalho elimina a necessidade de armazenar ou girar credenciais ao proporcionar gerenciamento automático de credenciais, integração com Azure RBAC e um registro completo de auditoria. O token é projetado automaticamente para o pod pelo webhook de identidade de carga de trabalho e o SDK o lê usando o SignedAssertionFilePath tipo de credencial. Essa abordagem reduz significativamente os riscos de segurança e a sobrecarga operacional em comparação com a autenticação tradicional baseada em segredo.

Note: Para Azure VMs e Serviços de Aplicativo (ambientes não conteinerizados), use identidades gerenciadas atribuídas pelo sistema ou pelo usuário com o tipo de credencial SignedAssertionFromManagedIdentity. Para obter mais informações, consulte Usar Identidade Gerenciada.

Use certificados em vez de segredos

Prefira certificados para autenticação quando não é possível evitar segredos do cliente. Os certificados fornecem segurança mais forte do que os segredos do cliente porque usam criptografia de chave pública e são mais difíceis de extrair ou usar indevidamente. Armazene certificados em Azure Key Vault para gerenciamento centralizado e renovação automática:

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

Benefits: Azure Key Vault fornece gerenciamento de certificado centralizado com rotação automatizada, políticas de acesso e auditoria abrangente, garantindo que os certificados nunca sejam inseridos em imagens de contêiner. Para obter mais informações, consulte Usar certificados para autenticação.

Armazenar segredos com segurança

Os Segredos do Kubernetes são a opção adequada para armazenar segredos do cliente se identidades gerenciadas ou certificados não forem uma opção, embora verifique se os segredos são criptografados em repouso e o acesso é fortemente controlado:

apiVersion: v1
kind: Secret
metadata:
  name: app-cert
type: Opaque
data:
  certificate.pfx: <base64-encoded-pfx>
  certificate.password: <base64-encoded-password>

---
containers:
- name: sidecar
  volumeMounts:
  - name: cert-volume
    mountPath: /certs
    readOnly: true
  env:
  - name: AzureAd__ClientCredentials__0__SourceType
    value: "Path"
  - name: AzureAd__ClientCredentials__0__CertificateDiskPath
    value: "/certs/certificate.pfx"
  - name: AzureAd__ClientCredentials__0__CertificatePassword
    valueFrom:
      secretKeyRef:
        name: app-cert
        key: certificate.password

volumes:
- name: cert-volume
  secret:
    secretName: app-cert
    items:
    - key: certificate.pfx
      path: certificate.pfx
    defaultMode: 0400  # Read-only for owner

Segredos do cliente (evite, se possível)

Se os segredos do cliente precisarem ser usados, implemente medidas de segurança adicionais para minimizar o risco. Os segredos do cliente são menos seguros do que identidades gerenciadas ou certificados, portanto, eles exigem proteção extra, incluindo períodos de expiração curtos, armazenamento seguro com criptografia em repouso, acesso restrito por meio do RBAC e agendamentos de rotação frequentes. Nunca armazene segredos em imagens de contêiner ou variáveis de ambiente visíveis em manifestos de implantação:

apiVersion: v1
kind: Secret
metadata:
  name: app-secrets
type: Opaque
stringData:
  client-secret: "<your-client-secret>"

---
containers:
- name: sidecar
  env:
  - name: AzureAd__ClientCredentials__0__SourceType
    value: "ClientSecret"
  - name: AzureAd__ClientCredentials__0__ClientSecret
    valueFrom:
      secretKeyRef:
        name: app-secrets
        key: client-secret

Segurança de token

A segurança do token garante que apenas tokens válidos com escopo apropriado sejam aceitos e processados pelo SDK. Implemente a validação de token, os requisitos de escopo e as verificações de audiência para impedir o acesso não autorizado e limitar o uso indevido de token.

Habilitar validação de escopo

Exigir escopos específicos para tokens de entrada (espaço separado):

- name: AzureAd__Scopes
  value: "access_as_user"

Definir o público-alvo apropriado

Configure o público-alvo esperado para validação de token:

- name: AzureAd__Audience
  value: "api://your-api-id"

Validar tokens antes do uso

Sempre chame /Validate antes de aceitar tokens de usuário.

GET /Validate
Authorization: Bearer <user-token>

Segurança de runtime

Os controles de segurança de runtime protegem o contêiner do SDK contra modificação, escalonamento de privilégios e acesso de capacidade não autorizado. Configure o contêiner para ser executado com mínimos privilégios e sistemas de arquivos em modo somente leitura para reduzir a superfície de ataque.

sistema de arquivos raiz somente leitura

Impedir a modificação do sistema de arquivos de contêiner:

securityContext:
  readOnlyRootFilesystem: true

Política de segurança do pod

Impor padrões de segurança:

apiVersion: policy/v1beta1
kind: PodSecurityPolicy
metadata:
  name: sidecar-psp
spec:
  privileged: false
  allowPrivilegeEscalation: false
  requiredDropCapabilities:
  - ALL
  runAsUser:
    rule: 'MustRunAsNonRoot'
  seLinux:
    rule: 'MustRunAs'
  fsGroup:
    rule: 'MustRunAs'
  readOnlyRootFilesystem: true

Registro e monitoramento

O registro em log e o monitoramento eficazes permitem detectar anomalias, solucionar problemas e manter trilhas de auditoria para conformidade. Configure os níveis de log apropriados para seu ambiente e implemente investigações de integridade para garantir que o SDK opere conforme o esperado.

Configurar o log apropriado

Ambiente de produção:

- name: Logging__LogLevel__Default
  value: "Warning"
- name: Logging__LogLevel__Microsoft.Identity.Web
  value: "Information"

Ambiente de desenvolvimento (detalhado):

- name: Logging__LogLevel__Default
  value: "Debug"
- name: ASPNETCORE_ENVIRONMENT
  value: "Development"

Habilitar o monitoramento de saúde

Configurar probes de atividade e prontidão:

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

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

Lista de verificação de práticas recomendadas

Use essa lista de verificação abrangente para garantir que sua implantação do SDK siga todas as práticas de segurança recomendadas em dimensões de rede, credenciais, tokens, runtime e monitoramento.

Rede:

• [ ] O SDK escuta somente em localhost/127.0.0.1
• [ ] Nunca exposto por meio de LoadBalancer ou Ingress
• [ ] As políticas de rede restringem o acesso externo
• [ ] HTTPS/TLS para comunicação externa

Credenciais:

• [ ] Usar a Identidade da Carga de Trabalho para contêineres (AKS, Kubernetes, Docker) com SignedAssertionFilePath
• [ ] Usar Identidade Gerenciada para VMs/Serviços de Aplicações com SignedAssertionFromManagedIdentity
• [ ] Preferir certificados em vez de segredos
• [ ] Segredos armazenados no sistema de gerenciamento seguro
• [ ] Rotação regular de credenciais

Tokens:

• [ ] Validação de escopo habilitada
• [ ] Validação de público configurada
• [ ] Tokens validados antes do uso

Tempo de Execução

• [ ] O contêiner é executado como usuário não-root
• [ ] Sistema de arquivos raiz somente leitura
• [ ] Contexto de segurança aplicado
• Limites de recursos definidos

Monitorização:

• [ ] Configuração de log adequada
• [ ] Verificações de integridade habilitadas
• [ ] Registro de auditoria habilitado
• [ ] Alertas configurados

Padrões de segurança comuns

Implementações de referência demonstram como combinar vários controles de segurança em padrões de implantação coesos. Esses padrões servem como modelos para implantações de produção em vários modelos de ameaça.

implantação de alta segurança

apiVersion: v1
kind: ServiceAccount
metadata:
  name: secure-app-sa
  annotations:
    azure.workload.identity/client-id: "<managed-identity-id>"

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: secure-app
spec:
  template:
    metadata:
      labels:
        azure.workload.identity/use: "true"
    spec:
      serviceAccountName: secure-app-sa
      securityContext:
        fsGroup: 2000
      containers:
      - name: sidecar
        image: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0
        ports:
        - containerPort: 5000
        env:
        - name: Kestrel__Endpoints__Http__Url
          value: "http://127.0.0.1:5000"
        - name: AzureAd__TenantId
          valueFrom:
            configMapKeyRef:
              name: app-config
              key: tenant-id
        - name: AzureAd__ClientId
          value: "<managed-identity-client-id>"
        securityContext:
          runAsNonRoot: true
          runAsUser: 1000
          readOnlyRootFilesystem: true
          allowPrivilegeEscalation: false
          capabilities:
            drop:
            - ALL
        resources:
          requests:
            memory: "128Mi"
            cpu: "100m"
          limits:
            memory: "256Mi"
            cpu: "250m"
        livenessProbe:
          httpGet:
            path: /health
            port: 5000
          initialDelaySeconds: 10
          periodSeconds: 10

Girar credenciais regularmente

Rotacionar credenciais reduz a oportunidade para invasores se as credenciais forem vazadas ou comprometidas. A frequência de rotação depende do tipo de credencial e da política de segurança da sua organização:

• Segredos do cliente: a cada 90 dias (recomendado)
• Certificados: antes da expiração, normalmente a cada 1 a 2 anos
• Chaves para Solicitações HTTP Assinadas (SHR): siga a política de segurança da sua organização

Implementation guidance: Use Azure Key Vault com funcionalidades de rotação automatizada ou integre gerenciadores de segredos externos (como Sealed Secrets) ao pipeline de implementação. Isso minimiza a intervenção manual e garante agendamentos de rotação consistentes.

Responder a credenciais comprometidas

Se você suspeitar que as credenciais foram comprometidas, siga estas etapas imediatamente para conter o incidente e impedir o acesso não autorizado:

1. Revogue credenciais comprometidas no Microsoft Entra ID – remova as credenciais as do registro do aplicativo para bloquear seu uso imediatamente.
2. Generate novas credenciais – crie novos segredos ou certificados de cliente em Microsoft Entra ID para substituir os comprometidos.
3. Update seu sistema de gerenciamento de segredos - Armazene as novas credenciais em Segredos do Kubernetes ou Azure Key Vault com controles de acesso apropriados.
4. Reimplantar contêineres do SDK – atualize suas implantações para usar as novas credenciais, garantindo que todas as instâncias em execução peguem as alterações.
5. Revisar logs de acesso - Verifique os logs de auditoria do Azure Monitor e do Kubernetes em busca de sinais de solicitações de token não autorizadas ou atividade suspeita durante o período de comprometimento.
6. Documente o incidente – registre detalhes do incidente (quando descoberto, como aconteceu, o que foi acessado) e siga os procedimentos de resposta a incidentes da sua organização para evitar a recorrência.

Conteúdo relacionado

• Guia de instalação
• Referência de configuração
• Referência de pontos de extremidade
• Solução de problemas