Use secretos de cliente con Microsoft. Identity.Web

Un secreto de cliente es un valor de cadena que la aplicación usa para demostrar su identidad al solicitar tokens de la Plataforma de identidad de Microsoft. Microsoft. Identity.Web admite secretos de cliente como uno de varios tipos de credenciales para aplicaciones cliente confidenciales.

Elección de un tipo de credencial

Las aplicaciones cliente confidenciales necesitan una credencial para autenticarse con el Plataforma de identidad de Microsoft. Microsoft. Identity.Web admite los siguientes tipos de credenciales a través de la sección de configuración de ClientCredentials:

Los secretos de cliente son cadenas simples registradas con la aplicación en Microsoft Entra ID. Aunque son el tipo de credencial más fácil de configurar, también tienen limitaciones de seguridad significativas:

• Se pueden exponer accidentalmente en archivos de código fuente, registros o configuración.
• Tienen una fecha de expiración y deben rotarse manualmente.
• No proporcionan ninguna prueba criptográfica de la identidad del autor de la llamada más allá de la posesión del secreto.

Configuración de un secreto de cliente en appsettings.json

Para configurar un secreto de cliente, agregue una ClientCredentials matriz a la AzureAd sección del appsettings.json archivo:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "YOUR_TENANT_ID",
    "ClientId": "YOUR_CLIENT_ID",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "YOUR_SECRET_VALUE"
      }
    ]
  }
}

La ClientCredentials matriz admite varias entradas. Microsoft.Identity.Web intenta cada credencial en orden hasta que una tenga éxito, lo que resulta útil para escenarios de rotación de secretos.

Almacenamiento de secretos para el desarrollo

En esta sección se describe cómo mantener los valores secretos fuera del código fuente durante el desarrollo local.

secretos de usuario de .NET

El enfoque recomendado para almacenar secretos durante el desarrollo local es la herramienta Secret Manager. Secretos de Usuario almacena datos confidenciales fuera del árbol de proyectos, lo que evita confirmaciones accidentales en el control de código fuente.

1. Inicialice secretos de usuario para el proyecto:

   dotnet user-secrets init
   

2. Establezca el valor del secreto de cliente:

   dotnet user-secrets set "AzureAd:ClientCredentials:0:ClientSecret" "your-secret-value"
   

3. Compruebe que el secreto se almacenó:

   dotnet user-secrets list
   

Los secretos de usuario se cargan automáticamente en el Development entorno cuando se usa WebApplication.CreateBuilder() o Host.CreateDefaultBuilder().

Su appsettings.json debe contener la estructura sin el valor secreto real:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "YOUR_TENANT_ID",
    "ClientId": "YOUR_CLIENT_ID",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret"
      }
    ]
  }
}

Variables de entorno

También puede usar variables de entorno para proporcionar el secreto de cliente. .NET configuración asigna automáticamente las variables de entorno que usan el separador de __ (doble subrayado) a la jerarquía de configuración. Establezca la variable para el shell:

$env:AzureAd__ClientCredentials__0__ClientSecret = "your-secret-value"

export AzureAd__ClientCredentials__0__ClientSecret="your-secret-value"

Las variables de entorno tienen prioridad sobre los valores de appsettings.json, por lo que el valor secreto del archivo de configuración puede estar vacío o omitirse.

Almacenar secretos para entornos más avanzados

Para la implementación provisional, el entorno de prueba (QA) o cualquier entorno compartido, utilice Azure Key Vault como origen de configuración. Este enfoque mantiene los secretos fuera de los archivos de configuración y las variables de entorno a la vez que proporciona funcionalidades de auditoría, directivas de acceso y rotación automática.

Agregar Azure Key Vault como origen de configuración

1. Instale el paquete NuGet necesario:

   dotnet add package Azure.Extensions.AspNetCore.Configuration.Secrets
   

2. Almacene el secreto de cliente en Azure Key Vault con un nombre que se asigne a la ruta de configuración. Utilice -- (guión doble) como separador.

   az keyvault secret set \
     --vault-name "your-keyvault-name" \
     --name "AzureAd--ClientCredentials--0--ClientSecret" \
     --value "your-secret-value"
   

3. Agregue Key Vault como origen de configuración en Program.cs. El código siguiente registra Key Vault para que sus secretos estén disponibles a través de la API de configuración estándar:

   var builder = WebApplication.CreateBuilder(args);
   
   builder.Configuration.AddAzureKeyVault(
       new Uri("https://your-keyvault-name.vault.azure.net/"),
       new DefaultAzureCredential());
   

El nombre del secreto de Key Vault AzureAd--ClientCredentials--0--ClientSecret se asigna automáticamente a la ruta de configuración AzureAd:ClientCredentials:0:ClientSecret.

Creación de un secreto de cliente en el portal de Azure

Siga estos pasos para registrar un secreto de cliente para la aplicación en Microsoft Entra ID:

1. Inicie sesión en el Centro de administración Microsoft Entra.
2. Vaya a Identity>Applications>Registros de aplicaciones.
3. Seleccione la aplicación de la lista.
4. En el menú izquierdo, seleccione Certificados y secretos.
5. Seleccione la pestaña Secretos de cliente .
6. Seleccione Nuevo secreto de cliente.
7. En el panel Agregar un secreto de cliente :
   • Escriba una descripción para el secreto (por ejemplo, "Secreto de desarrollo").
   • Seleccione una duración expirada . Las opciones disponibles incluyen 180 días, 365 días, 730 días o una fecha personalizada.
   • Selecciona Agregar.
8. Copie el valor del secreto inmediatamente. El valor solo se muestra una vez y no se puede recuperar después de salir de la página.

Administrar la expiración y la rotación de secretos

Los secretos de cliente tienen una duración máxima y expiran en la fecha especificada durante la creación. Planifique la rotación de claves para evitar fallos en las aplicaciones.

Control de la caducidad

• Compruebe la columna Fecha de expiración en la página Certificados y secretos del registro de la aplicación.
• Configura recomendaciones de Microsoft Entra para recibir alertas antes de que expiren las credenciales.

Estrategia de rotación

Usa el ClientCredentials array para soportar la rotación sin tiempo de inactividad.

1. Cree un nuevo secreto de cliente en el portal de Azure.

2. Agregue el nuevo secreto como entrada adicional en la ClientCredentials matriz. Coloque primero el nuevo secreto para que se intente antes del antiguo:

   {
     "AzureAd": {
       "ClientCredentials": [
         {
           "SourceType": "ClientSecret",
           "ClientSecret": "[NEW_SECRET_REFERENCE]"
         },
         {
           "SourceType": "ClientSecret",
           "ClientSecret": "[OLD_SECRET_REFERENCE]"
         }
       ]
     }
   }
   

3. Implemente la configuración actualizada. Microsoft. Identity.Web intenta la primera credencial y vuelve a la segunda si se produce un error en la primera.

4. Después de confirmar que el nuevo secreto funciona, quite el secreto anterior de la configuración y el portal de Azure.

Migración a credenciales de producción

Antes de implementar en producción, migre de secretos de cliente a un tipo de credencial más seguro:

Autenticación basada en certificados

Los certificados proporcionan una prueba criptográfica de identidad y son el tipo de credencial recomendado para producción. La siguiente configuración recupera un certificado de Key Vault:

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

Para obtener pasos detallados, consulte Usar certificados con Microsoft.Identity.Web.

Identidad administrada (sin certificado)

En el caso de las aplicaciones hospedadas en Azure, las identidades administradas eliminan la necesidad de administrar las credenciales por completo. La siguiente configuración usa una identidad administrada asignada por el usuario:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "YOUR_MANAGED_IDENTITY_CLIENT_ID"
      }
    ]
  }
}

Para obtener pasos detallados, consulte Certificateless authentication con Microsoft.Identity.Web.

Lista de comprobación para la migración

• [ ] Genere o aprovisione la nueva credencial (certificado o identidad administrada).
• [ ] Actualice la configuración de la aplicación para usar el nuevo tipo de credencial.
• [ ] Pruebe la nueva credencial en un entorno de ensayo.
• [ ] Implemente en producción.
• [ ] Quite el secreto de cliente antiguo del portal de Azure.
• [ ] Compruebe que la aplicación funciona correctamente sin el secreto antiguo.

Evitar errores comunes de seguridad

Revise los siguientes antipatrones y sus alternativas recomendadas al trabajar con secretos de los clientes.

Solución de errores comunes

En esta sección se tratan los errores frecuentes que se pueden producir al configurar secretos de cliente.

Secreto de cliente no válido

Error: AADSTS7000215: Invalid client secret provided.

Causas posibles:

• El valor secreto se copió incorrectamente. Los valores secretos pueden contener caracteres especiales que se truncan durante las operaciones de copia y pegado.
• El secreto se creó para un registro de aplicación diferente al configurado en ClientId.
• La ruta de configuración es incorrecta y la aplicación no está leyendo el valor del secreto.

Resolución:

1. Cree un nuevo secreto de cliente en el portal de Azure y copie cuidadosamente el valor completo.

2. Verifique que ClientId y TenantId en su configuración coincidan con el registro de la aplicación donde se creó el secreto.

3. Agregue un punto de interrupción o una instrucción de registro para comprobar que la configuración se ha cargado correctamente:

   // For debugging only — remove before committing
   var config = builder.Configuration.GetSection("AzureAd:ClientCredentials:0:ClientSecret").Value;
   Console.WriteLine($"Secret loaded: {!string.IsNullOrEmpty(config)}");
   

Secreto de cliente expirado

Error: AADSTS7000222: The provided client secret keys for app '{app-id}' are expired.

Resolución:

1. Vaya al registro de la aplicación en el Centro de administración Microsoft Entra.
2. Compruebe la fecha de expiración en Certificados y secretos>Secretos de cliente.
3. Cree un nuevo secreto y actualice la configuración de la aplicación.
4. Elimine el secreto expirado del portal.

Secreto no encontrado en la configuración

Síntoma: La aplicación genera un NullReferenceException o no se puede autenticar porque el valor del secreto es null.

Causas posibles:

• Los secretos de usuario no se inicializan para el proyecto.
• El nombre de la variable de entorno no coincide con la ruta de acceso de configuración esperada.
• Key Vault no está configurado como origen de configuración.
• La aplicación se ejecuta en un entorno que no es de desarrollo donde no se cargan los secretos de usuario.

Resolución:

1. Verifique que los secretos de usuario se inicializan verificando la existencia de un elemento UserSecretsId en el archivo .csproj.
2. Para comprobar que el secreto está establecido, ejecute dotnet user-secrets list.
3. Compruebe que la ruta de configuración coincide exactamente: AzureAd:ClientCredentials:0:ClientSecret.
4. Si se ejecuta fuera del entorno de desarrollo, asegúrese de que el origen de configuración adecuado (variable de entorno o Key Vault) esté disponible.

Contenido relacionado

• Certificados con Microsoft.Identity.Web
• Autenticación sin certificado
• Introducción a la caché de tokens
• Almacenamiento seguro de secretos de aplicaciones en desarrollo en ASP.NET Core
• Proveedor de configuración de Azure Key Vault en ASP.NET Core