Referencia de configuración: Configuración del SDK de Microsoft Entra para AgentID

En esta guía se proporcionan opciones de configuración para el SDK de Microsoft Entra para AgentID, un servicio de autenticación en contenedor que controla la adquisición y administración de tokens para las aplicaciones en entornos contenedorizados. El SDK simplifica la integración de identidades mediante la administración de la autenticación de Id. de Entra de Microsoft, los flujos de token en nombre de (OBO) y las llamadas API de nivel inferior sin necesidad de que las aplicaciones inserte bibliotecas de autenticación directamente.

Aunque esta guía se centra en los patrones de implementación de Kubernetes, el SDK se puede implementar en cualquier entorno contenedorizado, como Docker, Azure Container Instances y otras plataformas de orquestación de contenedores.

Si va a implementar en Azure Kubernetes Service (AKS), configurar entornos de desarrollo o configurar cargas de trabajo de producción, esta referencia trata los patrones de configuración, los tipos de credenciales y las variables de entorno necesarias para proteger las aplicaciones con el identificador de Microsoft Entra.

Descripción general de la configuración

El SDK de Microsoft Entra para AgentID se configura mediante orígenes de configuración siguiendo las convenciones de ASP.NET Core. Los valores de configuración se pueden proporcionar a través de varios métodos, entre los que se incluyen:

• Variables de entorno (recomendadas para Kubernetes)
• Configuración de id. de entra: appsettings.json archivo adjunto al contenedor o incrustado en el archivo yaml.
• Argumentos de la línea de comandos
• Azure App Configuration o Key Vault (para escenarios avanzados)

Configuración de Id. de Entra principal

El SDK de Microsoft Entra para implementaciones de AgentID requiere la configuración principal de Entra ID para autenticar los tokens entrantes y adquirir tokens para las API de nivel inferior. Use las credenciales de cliente adecuadas en el siguiente formato YAML, normalmente como variables de entorno, para garantizar la autenticación segura.

Configuración necesaria

En primer lugar, configure los valores principales de Entra ID para que el SDK autentique los tokens entrantes y adquiera tokens para las API de bajada.

env:
- name: AzureAd__Instance
  value: "https://login.microsoftonline.com/"
- name: AzureAd__TenantId
  value: "<your-tenant-id>"
- name: AzureAd__ClientId
  value: "<your-client-id>"

Configuración de credenciales de cliente

El SDK de Microsoft Entra para AgentID admite varios tipos de credenciales de cliente para autenticarse con el identificador de Microsoft Entra al adquirir tokens para las API de nivel inferior. Elija el tipo de credencial que mejor se adapte a los requisitos de seguridad y entorno de implementación y asegúrese de que la configuración que elija sea adecuada para su escenario.

Cada tipo de credencial ofrece diferentes escenarios:

• Secreto de cliente: configuración sencilla para desarrollo y pruebas (no se recomienda para producción)
• Certificado de Key Vault: entornos de producción con administración centralizada de certificados
• Certificado de archivo: cuando los certificados se montan como archivos (por ejemplo, a través de secretos de Kubernetes)
• Almacén de certificados: entornos de Windows con almacenes de certificados
• Identidad de carga de trabajo para contenedores: recomendado para AKS, mediante la identidad de carga de trabajo de Azure AD con proyección de token basada en archivos
• Identidad administrada para máquinas virtuales o App Services: Azure Virtual Machines y App Services con identidades administradas asignadas por el sistema o por el usuario (no para contenedores)

Configure uno o varios orígenes de credenciales en el siguiente formato YAML:

Secreto del cliente

Esta configuración configura la autenticación entra ID mediante un secreto de cliente para la autenticación entre servicios.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "ClientSecret"
- name: AzureAd__ClientCredentials__0__ClientSecret
  value: "<your-client-secret>"

Certificado de Key Vault

Esta configuración configura la autenticación entra ID mediante un certificado almacenado en Azure Key Vault.

- 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: "<certificate-name>"

Certificado del archivo

Esta configuración configura la autenticación entra ID mediante un certificado almacenado como un archivo.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "Path"
- name: AzureAd__ClientCredentials__0__CertificateDiskPath
  value: "/path/to/certificate.pfx"
- name: AzureAd__ClientCredentials__0__CertificatePassword
  value: "<certificate-password>"

Certificado del almacén

Esta configuración configura la autenticación entra ID mediante un certificado del almacén de certificados local.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "StoreWithThumbprint"
- name: AzureAd__ClientCredentials__0__CertificateStorePath
  value: "CurrentUser/My"
- name: AzureAd__ClientCredentials__0__CertificateThumbprint
  value: "<thumbprint>"

Identidad de carga de trabajo para contenedores (recomendado para AKS)

Esta configuración configura la autenticación entra ID mediante Azure AD Workload Identity para implementaciones en contenedores (AKS). Este es el enfoque recomendado para escenarios basados en contenedores, ya que usa la proyección de tokens basada en archivos.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "SignedAssertionFilePath"

Nota: El webhook de Identidad de carga de trabajo de Azure proyecta automáticamente la ruta /var/run/secrets/azure/tokens/azure-identity-token de acceso del archivo de token o una variable de entorno cuando el pod está configurado correctamente con la anotación de la cuenta de servicio y la etiqueta de pod. Consulte Uso de identidad administrada para obtener instrucciones de configuración completas.

Identidad administrada para máquinas virtuales y App Services

Para escenarios clásicos de Identidad administrada de Azure en Máquinas virtuales o App Services (no contenedores), use SignedAssertionFromManagedIdentity:

- name: AzureAd__ClientCredentials__0__SourceType
  value: "SignedAssertionFromManagedIdentity"
- name: AzureAd__ClientCredentials__0__ManagedIdentityClientId
  value: "<managed-identity-client-id>"

Importante: No use SignedAssertionFromManagedIdentity para entornos en contenedores (Kubernetes, AKS, Docker). Para AKS, use SignedAssertionFilePath como se muestra anteriormente. Para Kubernetes y Docker, use certificados de cliente. Para obtener más información, consulte https://aka.ms/idweb/client-credentials

Recursos adicionales

Para obtener detalles completos sobre todas las opciones de configuración de credenciales y su uso, consulte la especificación CredentialDescription en el repositorio microsoft-identity-abstracciones-for-dotnet.

Prioridad de credenciales

Configure varias credenciales con selección basada en prioridad:

# First priority - Key Vault certificate
- name: AzureAd__ClientCredentials__0__SourceType
  value: "KeyVault"
- name: AzureAd__ClientCredentials__0__KeyVaultUrl
  value: "https://prod-keyvault.vault.azure.net"
- name: AzureAd__ClientCredentials__0__KeyVaultCertificateName
  value: "prod-cert"

# Second priority - Client secret (fallback)
- name: AzureAd__ClientCredentials__1__SourceType
  value: "ClientSecret"
- name: AzureAd__ClientCredentials__1__ClientSecret
  valueFrom:
    secretKeyRef:
      name: app-secrets
      key: client-secret

El SDK de Microsoft Entra para AgentID evalúa las credenciales en orden numérico (0, 1, 2, etc.) y usa la primera credencial que se autentica correctamente.

Configuración de LAS API de bajada

Configure las API de bajada a las que la aplicación debe llamar mediante flujos de token en nombre de (OBO). El SDK de Microsoft Entra para AgentID administra la adquisición de tokens y proporciona encabezados de autenticación para estas llamadas API. Cada API de bajada requiere un nombre de configuración único y parámetros específicos para la adquisición de tokens y el control de solicitudes HTTP.

Defina cada API de bajada con su dirección URL base, los ámbitos necesarios y los parámetros opcionales. El SDK controlará automáticamente la adquisición de tokens mediante el token de usuario entrante y proporcionará los encabezados de autorización adecuados para las llamadas API de la aplicación.

- name: DownstreamApis__Graph__BaseUrl
  value: "https://graph.microsoft.com/v1.0"
- name: DownstreamApis__Graph__Scopes
  value: "User.Read Mail.Read"
- name: DownstreamApis__Graph__RelativePath
  value: "/me"

- name: DownstreamApis__MyApi__BaseUrl
  value: "https://api.contoso.com"
- name: DownstreamApis__MyApi__Scopes
  value: "api://myapi/.default"

Opciones de adquisición de tokens

Ajuste del comportamiento de la adquisición de tokens:

- name: DownstreamApis__Graph__AcquireTokenOptions__Tenant
  value: "<specific-tenant-id>"

- name: DownstreamApis__Graph__AcquireTokenOptions__AuthenticationScheme
  value: "Bearer"

- name: DownstreamApis__Graph__AcquireTokenOptions__CorrelationId
  value: "<correlation-id>"

Configuración de solicitud HTTP firmada (SHR)

Habilite las solicitudes HTTP firmadas para mejorar la seguridad:

- name: DownstreamApis__SecureApi__AcquireTokenOptions__PopPublicKey
  value: "<base64-encoded-public-key>"

- name: DownstreamApis__SecureApi__AcquireTokenOptions__PopClaims
  value: '{"custom_claim": "value"}'

Configuración de registro

Configuración de los niveles de registro:

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

configuración de ASP.NET Core

- name: ASPNETCORE_ENVIRONMENT
  value: "Production"
- name: ASPNETCORE_URLS
  value: "http://+:5000"

invalidaciones de configuración de Per-Request

Todos los puntos de conexión de adquisición de tokens aceptan parámetros de consulta para invalidar la configuración:

# Override scopes
GET /AuthorizationHeader/Graph?optionsOverride.Scopes=User.Read&optionsOverride.Scopes=Mail.Read

# Request app token instead of OBO
GET /AuthorizationHeader/Graph?optionsOverride.RequestAppToken=true

GET /AuthorizationHeaderUnauthenticated/Graph?optionsOverride.RequestAppToken=true

# Override tenant
GET /AuthorizationHeader/Graph?optionsOverride.AcquireTokenOptions.Tenant=<tenant-id>

# Override relative path
GET /DownstreamApi/Graph?optionsOverride.RelativePath=me/messages

# Enable SHR for this request
GET /AuthorizationHeader/Graph?optionsOverride.AcquireTokenOptions.PopPublicKey=<base64-key>

Invalidaciones de identidad del agente

Especifique la identidad del agente en el momento de la solicitud:

# Autonomous agent
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>

# Autonomous agent with specific agent user identity (by username)
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>&AgentUsername=user@contoso.com

# Autonomous agent with specific agent user identity (by object ID)
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>&AgentUserId=<user-object-id>

Reglas importantes:

• AgentUsername y AgentUserId requieren AgentIdentity
• AgentUsername y AgentUserId son mutuamente excluyentes

Consulte Identidades de agente para obtener una semántica detallada.

Ejemplo de configuración completa

A continuación se proporciona un ejemplo listo para producción que muestra cómo implementar el SDK con una separación adecuada de la configuración y los secretos. En este ejemplo se muestra la configuración de varias API de bajada, el uso de ConfigMaps de Kubernetes para la configuración no confidencial, el almacenamiento de credenciales de forma segura en secretos y la aplicación de configuraciones específicas del entorno para la implementación segura.

Este patrón sigue los procedimientos recomendados de Kubernetes separando los datos de configuración de credenciales confidenciales, lo que permite una administración eficaz de diferentes entornos al tiempo que se mantiene la seguridad.

Kubernetes ConfigMap

ConfigMap almacena opciones de configuración no confidenciales para el SDK, incluidos la configuración de Id. entra, las API de bajada y los niveles de registro.

apiVersion: v1
kind: ConfigMap
metadata:
  name: sidecar-config
data:
  ASPNETCORE_ENVIRONMENT: "Production"
  ASPNETCORE_URLS: "http://+:5000"
  
  AzureAd__Instance: "https://login.microsoftonline.com/"
  AzureAd__TenantId: "common"
  AzureAd__ClientId: "your-app-client-id"
  AzureAd__Scopes: "access_as_user"
  
  DownstreamApis__Graph__BaseUrl: "https://graph.microsoft.com/v1.0"
  DownstreamApis__Graph__Scopes: "User.Read Mail.Read"
  
  DownstreamApis__MyApi__BaseUrl: "https://api.contoso.com"
  DownstreamApis__MyApi__Scopes: "api://myapi/.default"
  
  Logging__LogLevel__Default: "Information"
  Logging__LogLevel__Microsoft.Identity.Web: "Debug"

Secreto de Kubernetes

El secreto almacena credenciales confidenciales, como secretos de cliente, por separado de ConfigMap.

apiVersion: v1
kind: Secret
metadata:
  name: sidecar-secrets
type: Opaque
stringData:
  AzureAd__ClientCredentials__0__ClientSecret: "your-client-secret"

Implementación con ConfigMap y secreto

La implementación monta ConfigMap y Secret en el contenedor del SDK, lo que garantiza que la configuración y las credenciales estén separadas correctamente.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  template:
    spec:
      containers:
      - name: sidecar
        image: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0
        envFrom:
        - configMapRef:
            name: sidecar-config
        - secretRef:
            name: sidecar-secrets

Configuración específica del entorno

Configure opciones específicas del entorno para adaptar la seguridad, el registro y el aislamiento de inquilinos para los entornos de implementación. Cada entorno requiere diferentes enfoques de configuración para equilibrar la eficacia del desarrollo, la validación de ensayo y los requisitos de seguridad de producción.

Desarrollo

- name: ASPNETCORE_ENVIRONMENT
  value: "Development"
- name: Logging__LogLevel__Default
  value: "Debug"
- name: AzureAd__TenantId
  value: "<dev-tenant-id>"

Staging

- name: ASPNETCORE_ENVIRONMENT
  value: "Staging"
- name: Logging__LogLevel__Default
  value: "Information"
- name: AzureAd__TenantId
  value: "<staging-tenant-id>"

Producción

- name: ASPNETCORE_ENVIRONMENT
  value: "Production"
- name: Logging__LogLevel__Default
  value: "Warning"
- name: Logging__LogLevel__Microsoft.Identity.Web
  value: "Information"
- name: AzureAd__TenantId
  value: "<prod-tenant-id>"
- name: ApplicationInsights__ConnectionString
  value: "<app-insights-connection>"

Validation

El SDK de Microsoft Entra para AgentID valida la configuración en el inicio y registra errores para:

• Falta la configuración necesaria (TenantId, ClientId)
• Configuraciones de credenciales no válidas
• Definiciones de API de bajada con formato incorrecto
• Direcciones URL o formatos de ámbito no válidos

Compruebe los registros de contenedor para ver los mensajes de validación:

kubectl logs <pod-name> -c sidecar

procedimientos recomendados

1. Uso de secretos para credenciales: almacene secretos de cliente y certificados en secretos de Kubernetes o Azure Key Vault. Consulte también https://aka.ms/msidweb/client-credentials
2. Configuración independiente por entorno: Use ConfigMaps para administrar la configuración específica del entorno
3. Habilitar el registro adecuado: usar el registro de depuración en desarrollo, información o advertencia en producción
4. Configurar comprobaciones de estado: asegúrese de que los puntos de conexión de comprobación de estado están configurados correctamente.
5. Uso de la identidad de carga de trabajo para contenedores: para implementaciones en contenedores (AKS), se prefiere la identidad de carga de trabajo de Azure AD con SignedAssertionFilePath a través de secretos de cliente para mejorar la seguridad.
6. Uso de identidad administrada para máquinas virtuales o App Services: para máquinas virtuales de Azure y App Services, use identidades administradas asignadas por el sistema o el usuario.
7. Validar en tiempo de implementación: probar la configuración en el almacenamiento provisional antes de la implementación de producción

Véase también

• Identidades del agente
• Referencia de puntos de conexión
• Procedimientos recomendados de seguridad
• Solución de problemas