Procedimientos recomendados de seguridad: Protección del SDK de Microsoft Entra para AgentID

Esta guía proporciona una configuración de seguridad completa y procedimientos recomendados de protección para implementar y operar de forma segura el SDK de Microsoft Entra para el id. de agente en entornos de producción. Trata los controles de seguridad esenciales, como el aislamiento de red, la administración de credenciales, la validación de tokens, la seguridad en tiempo de ejecución y la supervisión para asegurarse de que la implementación del SDK sigue los procedimientos recomendados de seguridad.

¿Es seguro ejecutar el SDK?

El SDK de Microsoft Entra para el id. de agente está diseñado teniendo en cuenta la seguridad, pero su seguridad depende de las prácticas de configuración e implementación adecuadas. Siga estos procedimientos recomendados para garantizar una implementación segura:

Seguridad de red

El aislamiento de red es fundamental para proteger las operaciones de autenticación. El SDK de Microsoft Entra para el ID de Agente debe ejecutarse dentro de los límites de confianza con controles de acceso estrictos y filtrado exhaustivo de tráfico. Esto incluye la vinculación únicamente al host local, la comunicación interna dentro del pod y las políticas de red que impiden el acceso no autorizado a los endpoints de autenticación.

Restricción del acceso del SDK

Configure Kestrel para que atienda exclusivamente en localhost y así evitar el acceso externo a la red a los puntos de conexión de autenticación.

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 el filtrado de host de Kestrel con AllowedHosts para restringir el acceso:

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

Uso de la comunicación local de pod

Configure su aplicación para comunicarse con el SDK de Microsoft Entra para el ID de Agente a través de localhost para asegurarse de que el tráfico se mantenga dentro del mismo pod y no atraviese la red.

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

Nunca exponga a través de LoadBalancer o Ingress (esto permitiría la adquisición no autorizada de tokens desde fuera del límite de confianza):

# 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

Administración de credenciales

La administración segura de credenciales es fundamental para la seguridad del SDK. Use identidades administradas siempre que sea posible para eliminar secretos y siga el principio de privilegios mínimos al configurar las credenciales de autenticación.

Preferir la identidad de carga de trabajo para contenedores

Use Id. de carga de trabajo de Microsoft Entra para implementaciones en contenedores (AKS) para eliminar los secretos por completo y garantizar la administración segura de credenciales con proyección de token basada en archivos:

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"

Benefits: La identidad de carga de trabajo elimina la necesidad de almacenar o rotar secretos al proporcionar administración automática de credenciales, integración de Azure RBAC y un rastro de auditoría completo. El webhook de identidad de carga de trabajo proyecta automáticamente el token en el pod, y el SDK lo lee usando el tipo de credencial SignedAssertionFilePath. Este enfoque reduce significativamente los riesgos de seguridad y la sobrecarga operativa en comparación con la autenticación basada en secretos tradicional.

Nota: Para las máquinas virtuales de Azure y los App Services (entornos no contenedorizados), use identidades administradas asignadas por usuario o sistema con el tipo de credencial SignedAssertionFromManagedIdentity en lugar de. Para obtener más información, consulte Uso de identidad administrada.

Uso de certificados en lugar de secretos

Se prefieren certificados para la autenticación cuando no se pueden evitar secretos de cliente. Los certificados proporcionan mayor seguridad que los secretos de cliente porque usan criptografía de clave pública y son más difíciles de extraer o usar mal. Almacene certificados en Azure Key Vault para la administración centralizada y la renovación 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 proporciona administración centralizada de certificados con rotación automatizada, directivas de acceso y auditoría completa, a la vez que garantiza que los certificados nunca se inserten en imágenes de contenedor. Para obtener más información, consulte Usar certificados para la autenticación.

Almacenamiento de secretos de forma segura

Los secretos de Kubernetes son una opción adecuada para almacenar secretos de cliente si las identidades administradas o los certificados no son una opción, aunque asegúrese de que los secretos están cifrados en reposo y el acceso está estrechamente 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

Secretos de cliente (evite si es posible)

Si se deben usar secretos de cliente, implemente medidas de seguridad adicionales para minimizar el riesgo. Los secretos de cliente son menos seguros que las identidades administradas o los certificados, por lo que requieren protección adicional, incluidos períodos de expiración cortos, almacenamiento seguro con cifrado en reposo, acceso restringido a través de RBAC y programaciones de rotación frecuentes. Nunca almacene secretos en imágenes de contenedor o variables de entorno visibles en los manifiestos de implementación:

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

Seguridad de tokens

La seguridad del token garantiza que el SDK acepte y procese solo los tokens válidos y con ámbito adecuado. Implemente la validación de tokens, los requisitos de ámbito y las comprobaciones de audiencia para evitar el acceso no autorizado y limitar el uso indebido de tokens.

Habilitar la validación de ámbito

Requiere ámbitos específicos para los tokens entrantes (separados por espacios):

- name: AzureAd__Scopes
  value: "access_as_user"

Establecer la audiencia adecuada

Configure la audiencia esperada para la validación de tokens:

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

Validación de tokens antes de su uso

Siempre se debe llamar a /Validate antes de aceptar tokens de usuario.

GET /Validate
Authorization: Bearer <user-token>

Seguridad en tiempo de ejecución

Los controles de seguridad en tiempo de ejecución protegen el contenedor del SDK frente a la modificación, la elevación de privilegios y el acceso a funcionalidades no autorizadas. Configure el contenedor para que se ejecute con privilegios mínimos y sistemas de archivos de solo lectura para reducir la superficie expuesta a ataques.

Sistema de archivos raíz de solo lectura

Impedir la modificación del sistema de archivos de contenedor:

securityContext:
  readOnlyRootFilesystem: true

Directiva de seguridad de pods

Aplicar estándares de seguridad:

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 y supervisión

El registro y la supervisión eficaces le permiten detectar anomalías, solucionar problemas y mantener seguimientos de auditoría para el cumplimiento. Configure los niveles de registro adecuados para su entorno e implemente sondeos de estado para asegurarse de que el SDK funciona según lo previsto.

Configuración del registro adecuado

Entorno de producción:

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

Entorno de desarrollo (detallado):

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

Activar la monitorización de la salud

Configuración de sondeos de actividad y disponibilidad

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 comprobación de procedimientos recomendados

Use esta lista de comprobación completa para asegurarse de que la implementación del SDK sigue todos los procedimientos de seguridad recomendados en las dimensiones de red, credenciales, tokens, tiempo de ejecución y supervisión.

Red:

• [ ] EL SDK solo escucha en localhost/127.0.0.1
• [ ] Nunca se expone a través de LoadBalancer o Ingress
• [ ] Las directivas de red restringen el acceso externo
• [ ] HTTPS/TLS para la comunicación externa

Credenciales:

• [ ] Uso de la identidad de carga de trabajo para contenedores (AKS, Kubernetes, Docker) con SignedAssertionFilePath
• [ ] Utilizar identidad administrada para máquinas virtuales o Servicios de Aplicaciones con SignedAssertionFromManagedIdentity
• [ ] Preferir certificados sobre secretos
• [ ] Secretos almacenados en el sistema de administración segura
• [ ] Rotación regular de credenciales

Fichas:

• [ ] Validación de alcance habilitada
• [ ] Validación de usuarios configurada
• [ ] Tokens validados antes de su uso

Tiempo de ejecución

• [ ] El contenedor se ejecuta como usuario no root
• [ ] Sistema de archivos raíz de solo lectura
• [ ] Contexto de seguridad aplicado
• [ ] Límites de recursos establecidos

Monitorización:

• [ ] Registro adecuado configurado
• [ ] Comprobaciones de estado habilitadas
• [ ] Registro de auditoría habilitado
• [ ] Alertas configuradas

Patrones de seguridad comunes

Las implementaciones de referencia muestran cómo combinar varios controles de seguridad en patrones de implementación cohesivos. Estos patrones sirven como plantillas para implementaciones de producción en varios modelos de amenazas.

implementación de alta seguridad

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

Rotación de credenciales periódicamente

La rotación de credenciales reduce la ventana de oportunidad para los atacantes si se filtran o se ponen en peligro las credenciales. La frecuencia de rotación depende del tipo de credencial y de la directiva de seguridad de la organización:

• Secretos de cliente: cada 90 días (recomendado)
• Certificados: antes de la expiración, normalmente cada 1 a 2 años
• Claves para solicitudes HTTP firmadas (SHR): siga la directiva de seguridad de la organización.

Guía de implementación: use Azure Key Vault con funcionalidades de rotación automatizadas o integre administradores de secretos externos (como Secretos sellados) en la canalización de implementación. Esto minimiza la intervención manual y garantiza programaciones de rotación coherentes.

Responder a credenciales comprometidas

Si sospecha que las credenciales se han puesto en peligro, siga estos pasos inmediatamente para contener el incidente y evitar el acceso no autorizado:

1. Revocar credenciales comprometidas en Microsoft Entra ID: Quite las credenciales del registro de aplicaciones para bloquear su uso de inmediato.
2. Generar nuevas credenciales: cree nuevos secretos de cliente o certificados en Microsoft Entra ID para reemplazar los que están en peligro.
3. Actualizar el sistema de administración de secretos: almacene las nuevas credenciales en secretos de Kubernetes o Azure Key Vault con los controles de acceso adecuados.
4. Reimplementación de contenedores del SDK : actualice las implementaciones para usar las nuevas credenciales, lo que garantiza que todas las instancias en ejecución recojan los cambios.
5. Revisar registros de acceso: Compruebe los registros de Azure Monitor y auditoría de Kubernetes para buscar signos de solicitudes de token no autorizadas o actividad sospechosa durante la ventana de compromiso.
6. Documente el incidente: registre los detalles del incidente (cuando se detectó, cómo ocurrió, qué se accedió) y siga los procedimientos de respuesta a incidentes de su organización para prevenir la recurrencia.

Contenido relacionado

• Guía de instalación
• Referencia de configuración
• Referencia de puntos de conexión
• Solución de problemas