Introducción a las credenciales para Microsoft. Identity.Web

Cuando la aplicación se autentica con el Plataforma de identidad de Microsoft, presenta una credencial para demostrar su identidad. Microsoft. Identity.Web admite varios tipos de credenciales, cada uno adecuado para distintos entornos y requisitos de seguridad.

Este artículo le ayuda a comprender los tipos de credenciales disponibles, elegir el adecuado para su escenario y configurar las credenciales en la aplicación.

¿Por qué importa la elección de credenciales?

La credencial que usa la aplicación afecta directamente a su posición de seguridad, la sobrecarga operativa y la flexibilidad de implementación. Una credencial mal elegida puede exponer secretos, requerir rotación manual o limitar dónde se puede ejecutar la aplicación.

Microsoft. Identity.Web proporciona un modelo de configuración unificado que le permite:

• Especificar varias credenciales con respaldo automático.
• Cambie los tipos de credenciales sin modificar el código de la aplicación.
• Use credenciales diferentes por entorno (desarrollo, ensayo, producción).

Tipos de credenciales admitidos

Microsoft. Identity.Web admite tres categorías de credenciales para aplicaciones cliente confidenciales:

Credenciales sin certificado (credenciales de identidad federada + identidad administrada)

Las credenciales sin certificado usan Azure identidad administrada combinada con credenciales de identidad federada (FIC) para autenticar la aplicación sin administrar secretos ni certificados. Azure controla completamente el ciclo de vida de las credenciales.

Cómo funciona: La aplicación usa su identidad administrada para obtener un token, que el Plataforma de identidad de Microsoft acepta como prueba de la identidad de la aplicación a través de una confianza de federación preconfigurada.

Best for: Cargas de trabajo de producción que se ejecutan en Azure.

Más información sobre la autenticación sin certificados

Certificados

Los certificados proporcionan autenticación segura basada en claves asimétricas. La aplicación demuestra su identidad mediante la firma de una aserción con la clave privada del certificado. Microsoft. Identity.Web puede cargar certificados desde varios orígenes:

• Azure Key Vault: almacenamiento centralizado y administrado de certificados con directivas de acceso.
• Certificate Store: almacén de certificados Windows (CurrentUser o LocalMachine).
• Ruta de acceso del archivo: archivo de certificado en disco (formato .pfx).
• Codificado en Base64: certificado incrustado directamente en la configuración.

Lo mejor para: Cargas de trabajo de producción en las que las credenciales sin certificado no están disponibles o los entornos híbridos.

Más información sobre las credenciales de certificado

Secretos de cliente

Los secretos de cliente son cadenas compartidas que la aplicación presenta al Plataforma de identidad de Microsoft. Son el tipo de credencial más sencillo para configurar, pero ofrecen la seguridad más débil.

Lo mejor para: Solo desarrollo y pruebas locales.

Más información sobre los secretos de cliente

Elegir el tipo de credencial correcto

Use el siguiente árbol de decisión para determinar qué tipo de credencial es adecuado para su escenario.

Is your application running on Azure?
├── Yes
│   ├── Can you use Managed Identity?
│   │   ├── Yes → Use certificateless credentials (recommended)
│   │   └── No → Use certificates from Azure Key Vault
└── No
    ├── Is this a production environment?
    │   ├── Yes → Use certificates (Key Vault, Certificate Store, or file path)
    │   └── No → Use client secrets for development/testing

Guía general

Siga estos principios al seleccionar un tipo de credencial:

• Prefiera siempre credenciales sin certificados cuando la aplicación se ejecute en Azure. Eliminan completamente la administración de credenciales.
• Use certificados cuando las credenciales sin certificado no estén disponibles. Guárdelos en Azure Key Vault siempre que sea posible.
• Restrinja los secretos de cliente a entornos de desarrollo. Nunca use secretos de cliente en implementaciones de producción.

Comparación de tipos de credenciales

En la tabla siguiente se resumen las diferencias clave entre los tipos de credenciales:

Configuración de credenciales en appsettings.json

Microsoft. Identity.Web usa una matriz ClientCredentials en la configuración para especificar una o varias credenciales. Cada entrada de la matriz incluye una SourceType propiedad que indica de dónde procede la credencial.

Estructura de configuración

En el ejemplo siguiente se muestra una configuración mínima con una sola credencial sin certificado:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",

    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "user-assigned-managed-identity-client-id"
      }
    ]
  }
}

Valores de SourceType

La propiedad SourceType corresponde a la enumeración CredentialSource y determina cómo Microsoft.Identity.Web carga la credencial.

Ejemplos de credenciales por tipo

En los ejemplos siguientes se muestra cómo configurar cada tipo de credencial en appsettings.json y, cuando esté disponible, en el código de C#.

Sin certificado (identidad administrada)

Use una identidad administrada asignada por el usuario especificando su identificador de cliente:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "user-assigned-managed-identity-client-id"
      }
    ]
  }
}

En el caso de la identidad administrada asignada por el sistema, omita la ManagedIdentityClientId propiedad :

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity"
      }
    ]
  }
}

Certificado de Azure Key Vault

Cargue un certificado almacenado en Azure Key Vault especificando la dirección URL del almacén y el nombre del certificado:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "your-certificate-name"
      }
    ]
  }
}

También puede usar el CredentialDescription método auxiliar en C#:

var credential = CredentialDescription.FromKeyVault(
    "https://your-keyvault.vault.azure.net",
    "your-certificate-name");

Certificado del almacén de certificados

Cargue un certificado desde el almacén de certificados de Windows mediante huella digital:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "StoreWithThumbprint",
        "CertificateThumbprint": "ABC123DEF456...",
        "CertificateStorePath": "CurrentUser/My"
      }
    ]
  }
}

También puede usar un nombre distintivo, que simplifica la rotación de certificados porque el nuevo certificado se selecciona automáticamente:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "StoreWithDistinguishedName",
        "CertificateDistinguishedName": "CN=YourAppCertificate",
        "CertificateStorePath": "CurrentUser/My"
      }
    ]
  }
}

En C#, use el método auxiliar:

// By thumbprint
var credential = CredentialDescription.FromCertificateStore(
    "CurrentUser/My",
    thumbprint: "ABC123DEF456...");

// By distinguished name (recommended for rotation)
var credential = CredentialDescription.FromCertificateStore(
    "CurrentUser/My",
    distinguishedName: "CN=YourAppCertificate");

Certificado de la ruta de acceso del archivo

Cargue un certificado de un .pfx archivo en el disco:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "Path",
        "CertificateDiskPath": "/var/certs/app-cert.pfx",
        "CertificatePassword": "certificate-password"
      }
    ]
  }
}

Certificado codificado en Base64

Inserte un certificado directamente en la configuración como una cadena codificada en Base64:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "Base64Encoded",
        "Base64EncodedValue": "MIIKcQIBAzCCCi0..."
      }
    ]
  }
}

Secreto de cliente

Especifique una cadena secreta de cliente para desarrollo y pruebas:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "your-client-secret"
      }
    ]
  }
}

Utilice múltiples credenciales con alternativa

Puede especificar varias credenciales en la ClientCredentials matriz. Microsoft.Identity.Web prueba cada credencial en orden y pasa a la siguiente si la actual falla. Este patrón es útil para las aplicaciones que se ejecutan en varios entornos.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "your-managed-identity-client-id"
      },
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "your-certificate-name"
      },
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "development-only-secret"
      }
    ]
  }
}

En este ejemplo:

1. La aplicación intenta primero la autenticación sin certificados con identidad administrada (funciona en Azure).
2. Si la identidad administrada no está disponible, vuelve a un certificado de Key Vault.
3. Como último recurso, usa un secreto de cliente (para el desarrollo local).

Este enfoque le permite usar el mismo archivo de configuración entre entornos sin cambios en el código.

Configuración de credenciales en el código

También puede configurar las credenciales mediante programación en Program.cs o Startup.cs:

using Microsoft.Identity.Web;

builder.Services.AddMicrosoftIdentityWebAppAuthentication(builder.Configuration, "AzureAd")
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("MyApi", builder.Configuration.GetSection("MyApi"))
    .AddDistributedTokenCaches();

// Or configure credentials programmatically
builder.Services.Configure<MicrosoftIdentityOptions>(options =>
{
    options.ClientCredentials = new[]
    {
        new CredentialDescription
        {
            SourceType = CredentialSource.SignedAssertionFromManagedIdentity,
            ManagedIdentityClientId = "your-managed-identity-client-id"
        }
    };
});

Credenciales de descifrado de tokens

Más allá de las credenciales de cliente para la autenticación, Microsoft. Identity.Web también admite credenciales para el descifrado de tokens. Use las credenciales de descifrado de tokens cuando la aplicación reciba tokens cifrados y necesite descifrarlas.

Las credenciales de descifrado de tokens usan los mismos SourceType valores y patrones de configuración que las credenciales de cliente, pero se especifican en la TokenDecryptionCredentials matriz:

{
  "AzureAd": {
    "TokenDecryptionCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "token-decryption-cert"
      }
    ]
  }
}

Más información sobre el descifrado de tokens

procedimientos recomendados

Tenga en cuenta estas recomendaciones al configurar las credenciales para la aplicación:

Se prefieren las credenciales sin certificado en producción. Eliminan el riesgo de exposición secreta y eliminan la sobrecarga de rotación. Úselos siempre que su aplicación se ejecute en los recursos de cálculo de Azure que admitan la identidad administrada.

Utiliza la credencial alternativa para la portabilidad. Configure varias credenciales en orden de prioridad para que la aplicación funcione en desarrollo, almacenamiento provisional y producción sin cambios en el código.

Nunca use secretos de cliente en producción. Los secretos de cliente pueden filtrarse a través de registros, archivos de configuración o control de código fuente. En su lugar, use certificados o credenciales sin certificado.

Almacene valores confidenciales fuera de los archivos de configuración. Utilice Azure Key Vault, variables de entorno o el Administrador de Secretos de ASP.NET Core para almacenar contraseñas de certificado y secretos de cliente. No confirme valores confidenciales en el control de código fuente.

Renovar certificados antes de que expiren. Supervise las fechas de expiración del certificado y establezca un proceso de rotación. Azure Key Vault puede automatizar la renovación de certificados.

Use Azure Key Vault para el almacenamiento de certificados. Key Vault proporciona administración centralizada, directivas de acceso, registro de auditoría y rotación automática para certificados.

Contenido relacionado

• Autenticación sin certificado
• Credenciales de certificado
• Descifrado de tokens
• Secretos de cliente