Biblioteca cliente de autenticación de aplicaciones para .NET: versión 1.6.0

  • Artículo

Nota:

Microsoft.Azure.Services.AppAuthentication se ha retirado y ya no se admite ni se mantiene. Se reemplaza por la biblioteca cliente de Azure Identity disponible para .NET, Java, TypeScript y Python. Aquí puede encontrar información sobre cómo migrar a Azure Identity: Guía de migración de AppAuthentication a Azure.Identity.

Para autenticarse en los servicios de Azure con la entidad de servicio, necesita una credencial de Azure Active Directory (Azure AD), ya sea un secreto compartido o un certificado.

La administración de estas credenciales puede ser complicada. Resulta tentador agrupar las credenciales en una aplicación incluyéndolas en archivos de configuración o de origen. La biblioteca Microsoft.Azure.Services.AppAuthentication para .NET simplifica este problema. Utiliza las credenciales del desarrollador para la autenticación durante el desarrollo local. Cuando la solución se implementa más adelante en Azure, la biblioteca cambia automáticamente a las credenciales de la aplicación. El uso de credenciales de desarrollador durante el desarrollo local es más seguro porque no es necesario crear credenciales de Azure AD o compartir credenciales entre los programadores.

La biblioteca Microsoft.Azure.Services.AppAuthentication administra la autenticación automáticamente, que a su vez le permite centrarse en la solución, en lugar de en las credenciales. Admite el desarrollo local con Microsoft Visual Studio, la CLI de Azure o la autenticación integrada de Azure AD. Cuando se implementa en un recurso de Azure que admite una identidad administrada, la biblioteca usa automáticamente identidades administradas para los recursos de Azure. No se requieren cambios de configuración o código. La biblioteca también admite el uso directo de las credenciales de cliente de Azure AD cuando una identidad administrada no está disponible o cuando no se puede determinar el contexto de seguridad del desarrollador durante el desarrollo local.

Código | fuente Paquete (nuget) | Documentación de Azure Active Directory

Prerrequisitos

  • Visual Studio 2019 o Visual Studio 2017 v15.5.

  • La extensión de autenticación de la aplicación para Visual Studio, disponible como una extensión independiente para Visual Studio 2017 Update 5 e incluida con el producto en Update 6 y versiones posteriores. Con la Update 6 o posterior, puede comprobar la instalación de la extensión de autenticación de la aplicación si selecciona las herramientas de desarrollo de Azure en el instalador de Visual Studio.

Uso de la biblioteca

Para aplicaciones. NET, la manera más sencilla de trabajar con una identidad administrada es con el paquete Microsoft.Azure.Services.AppAuthentication. Aquí tiene información sobre cómo empezar:

  1. Seleccione Herramientas>Administrador de paquetes NuGet>Administrar paquetes NuGet para la solución para agregar referencias a los paquetes NuGet Microsoft.Azure.Services.AppAuthentication y Microsoft.Azure.KeyVault para el proyecto.

  2. Use AzureServiceTokenProvider para simplificar la solicitud de tokens de acceso para los clientes de Azure, como en los ejemplos siguientes:

    using Microsoft.Azure.Services.AppAuthentication;
using Microsoft.Azure.KeyVault;
using System.Data.SqlClient

// Use AzureServiceTokenProvider’s built-in callback for KeyVaultClient
var azureServiceTokenProvider = new AzureServiceTokenProvider();
var kv = new KeyVaultClient(new KeyVaultClient.AuthenticationCallback(azureServiceTokenProvider.KeyVaultTokenCallback));

// Request an access token for SqlConnection
sqlConnection = new SqlConnection(YourConnectionString)) 
{ 
    sqlConnection.AccessToken = await azureServiceTokenProvider.GetAccessTokenAsync("https://database.windows.net"); 
    sqlConnection.Open(); 
}

La clase AzureServiceTokenProvider segura para subprocesos almacena el token en la memoria y lo recupera de Azure AD justo antes de que expire. Esto significa que nunca necesita comprobar la expiración del token antes de llamar al método GetAccessTokenAsync.

El método GetAccessTokenAsync requiere un identificador de recursos. Para obtener más información sobre los servicios de Microsoft Azure, consulte ¿Qué es Managed Identities for Azure Resources?.

Autenticación de desarrollo local

Para el desarrollo local, hay dos escenarios de autenticación principales: la autenticación en los servicios de Azure y la autenticación en los servicios personalizados.

Autenticación en los servicios de Azure

Los equipos locales no admiten identidades administradas para recursos de Azure. Como resultado, la biblioteca Microsoft.Azure.Services.AppAuthentication utiliza las credenciales de desarrollador para la ejecución en el entorno de desarrollo local. Cuando la solución se implementa en Azure, la biblioteca usa una identidad administrada para cambiar a un flujo de concesión de credenciales de cliente de OAuth 2.0. Este enfoque significa que puede probar el mismo código local y remotamente sin preocuparse.

Para el desarrollo local, AzureServiceTokenProvider captura tokens mediante Visual Studio, la interfaz de línea de comandos de Azure (CLI) o la autenticación integrada de Azure AD. Cada opción se prueba secuencialmente y la biblioteca usa la primera opción correcta. Si no funciona ninguna opción, se produce una excepción AzureServiceTokenProviderException con información detallada.

Autenticación con Visual Studio

Para autenticar mediante Visual Studio:

  1. Inicie sesión en Visual Studio y use Herramientas>Opciones para abrir Opciones.

  2. Seleccione Autenticación de servicio de Azure, elija una cuenta para desarrollo local y seleccione Aceptar.

Si experimenta problemas con Visual Studio, como errores relacionados con el archivo del proveedor de tokens, revise atentamente los pasos anteriores.

Puede que sea necesario volver a autenticar el token del desarrollador. Para ello, seleccione Opciones de herramientas> y, a continuación, seleccione Autenticación de servicio de Azure. Busque un vínculo para volver a autenticar en la cuenta seleccionada. Selecciónelo para autenticar.

Autenticación con la CLI de Azure

Para usar la CLI de Azure para el desarrollo local, asegúrese de que tiene la versión CLI de Azure v2.0.12 o posterior.

Para usar la CLI de Azure:

  1. Busque la CLI de Azure en la barra de tareas de Windows para abrir el símbolo del sistema de Microsoft Azure.

  2. Inicie sesión en Azure Portal: az login para iniciar sesión en Azure.

  3. Escriba az account get-access-token --resource https://vault.azure.net para comprobar el acceso. Si recibe un error, compruebe que se ha instalado correctamente la versión adecuada de la CLI de Azure.

    Si la CLI de Azure no está instalada en el directorio predeterminado, recibirá un error que le notificará que AzureServiceTokenProvider no encuentra la ruta de acceso para la CLI de Azure. Use la variable de entorno AzureCLIPath para definir la carpeta de instalación de la CLI de Azure. AzureServiceTokenProvider agrega el directorio especificado en la variable de entorno AzureCLIPath a la variable de entorno Path cuando sea necesario.

  4. Si ha iniciado la sesión en la CLI de Azure con varias cuentas o la cuenta tiene acceso a varias suscripciones, debe especificar la suscripción que se va a usar. Escriba el comando az account set --subscription .

Este comando genera un resultado solo en caso de error. Para comprobar la configuración de la cuenta actual, escriba el comando az account list.

Autenticación con la autenticación de Azure AD

Para usar la autenticación de Azure AD, compruebe lo siguiente:

Autenticación en los servicios personalizados

Cuando un servicio llama a los servicios de Azure, los pasos anteriores funcionan porque los servicios de Azure permiten el acceso a los usuarios y a las aplicaciones.

Al crear un servicio que llama a un servicio personalizado, use las credenciales de cliente de Azure AD para la autenticación de desarrollo local. Hay dos opciones:

  • Usar a una entidad de servicio para iniciar sesión en Azure:

    1. Crear una entidad de servicio. Para más información, vea Creación de una entidad de servicio de Azure con la CLI de Azure.

    2. Use la CLI de Azure para iniciar sesión con el siguiente comando:

      az login --service-principal -u <principal-id> --password <password> --tenant <tenant-id> --allow-no-subscriptions

      Puesto que la entidad de servicio puede no tener acceso a la suscripción, use el argumento --allow-no-subscriptions.

  • Usar variables de entorno para especificar los detalles de la entidad de servicio. Para más información, consulte Ejecución de la aplicación con una entidad de servicio.

Una vez que haya iniciado sesión en Azure, AzureServiceTokenProvider usa la entidad de servicio para recuperar un token para el desarrollo local.

Este enfoque se aplica solo a desarrollo local. Cuando la solución se implementa en Azure, la biblioteca cambia a una identidad administrada para la autenticación.

Ejecución de la aplicación con una identidad administrada o una identidad asignada por el usuario

Cuando se ejecuta el código en una instancia de Azure App Service o en una máquina virtual de Azure con una identidad administrada habilitada, la biblioteca usa automáticamente dicha identidad. No se requieren cambios en el código, pero la identidad administrada debe tener permisos para los recursos a los que intentará acceder. Por ejemplo, las directivas de acceso son necesarias para que una identidad administrada acceda a los secretos de un almacén de claves.

También puede autenticarse con una identidad asignada por el usuario. Para obtener más información sobre las identidades asignadas por el usuario, consulte el artículo sobre las identidades administradas para recursos de Azure. Para autenticarse con una identidad asignada por el usuario, debe especificar el identificador de cliente de la identidad asignada por el usuario en la cadena de conexión. La cadena de conexión se especifica en Compatibilidad con la cadena de conexión.

Ejecución de la aplicación con una entidad de servicio

Puede ser necesario crear una credencial de cliente de Azure AD para autenticar. Esta situación puede producirse en los ejemplos siguientes:

  • El código se ejecuta en un entorno de desarrollo local, pero no en la identidad del desarrollador. Service Fabric, por ejemplo, usa la cuenta de NetworkService para el desarrollo local.

  • El código se ejecuta en un entorno de desarrollo local y se autentica en un servicio personalizado, por lo que no puede usar la identidad de desarrollador.

  • Se ejecuta el código en un recurso de Azure Compute que aún no admite identidades administradas para recursos de Azure, como Azure Batch.

Hay tres métodos principales para usar una entidad de servicio para ejecutar la aplicación. Para usar cualquiera de ellos, primero debe crear una entidad de servicio. Para más información, vea Creación de una entidad de servicio de Azure con la CLI de Azure.

Uso de un certificado en el almacén de claves local para iniciar sesión en Azure AD

  1. Cree un certificado de entidad de servicio mediante el comando az ad sp create-for-rbac de la CLI de Azure.

    az ad sp create-for-rbac --create-cert

    Este comando un archivo .pem (clave privada) que se almacena en el directorio particular. Convierta el archivo .pem en un certificado PFX mediante el comando :

    openssl pkcs12 -export -in test.pem -out test.pfx

  2. Establezca una variable de entorno denominada AzureServicesAuthConnectionString para el siguiente valor:

    RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};
      CertificateStoreLocation={CertificateStore}

    Reemplace {AppId} , {TenantId} y {Thumbprint} por los valores generados en el paso 1. Reemplace {CertificateStore} por LocalMachine` o CurrentUser, según su plan de implementación.

  3. Ejecute la aplicación.

Uso de una credencial compartida secreta para iniciar sesión en Azure AD

  1. Cree un certificado de entidad de servicio con una contraseña mediante el comando az ad sp create-for-rbac de la CLI de Azure con el parámetro --sdk-auth.

    az ad sp create-for-rbac --sdk-auth

  2. Establezca una variable de entorno denominada AzureServicesAuthConnectionString para el siguiente valor:

    RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret}

    Reemplace {AppId} , {TenantId} y {ClientSecret} por los valores generados en el paso 1.

  3. Ejecute la aplicación.

Una vez que todo está configurado correctamente, no es necesario realizar más cambios de código. AzureServiceTokenProvider usa la variable de entorno y el certificado para autenticar en Azure AD.

Uso de un certificado en Key Vault para iniciar sesión en Azure AD

Esta opción le permite almacenar el certificado de cliente de una entidad de servicio en Key Vault y usarlo para la autenticación de la entidad de servicio. Puede usar esta opción en los escenarios siguientes:

  • Autenticación local, en la que quiere autenticarse mediante una entidad de servicio explícita y quiere guardar la credencial de la entidad de servicio de forma segura en un almacén de claves. La cuenta de desarrollador debe tener acceso al almacén de claves.

  • Autenticación desde Azure, donde quiere usar la credencial explícita y quiere guardar la credencial de la entidad de servicio de forma segura en un almacén de claves. Puede usar esta opción para un escenario entre inquilinos. La identidad administrada debe tener acceso al almacén de claves.

La identidad administrada o la identidad del desarrollador deben tener permiso para recuperar el certificado de cliente de Key Vault. La biblioteca AppAuthentication usa el certificado recuperado como credencial de cliente de la entidad de servicio.

Para usar un certificado de cliente para la autenticación de la entidad de servicio:

  1. Cree un certificado de entidad de servicio y almacénelo automáticamente en su Key Vault. Use el comando az ad sp create-for-rbac --keyvault keyvaultname <> --cert <certificatename> --create-cert --skip-assignment:

    az ad sp create-for-rbac --keyvault <keyvaultname> --cert <certificatename> --create-cert --skip-assignment

    El identificador del certificado será una URL con el formato https://<keyvaultname>.vault.azure.net/secrets/<certificatename>

  2. Reemplace {KeyVaultCertificateSecretIdentifier} en esta cadena de conexión por el identificador del certificado:

    RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier={KeyVaultCertificateSecretIdentifier}

    Por ejemplo, si el almacén de claves se llamaba myKeyVault y ha creado un certificado denominado myCert, el identificador del certificado sería:

    RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier=https://myKeyVault.vault.azure.net/secrets/myCert

Compatibilidad de la cadena de conexión

De forma predeterminada, AzureServiceTokenProvider intenta los siguientes métodos de autenticación, en orden, para recuperar un token:

Para controlar el proceso, utilice una cadena de conexión pasada al constructor AzureServiceTokenProvider o especificada en la variable de entorno AzureServicesAuthConnectionString. Se admiten las siguientes opciones:

Opción de la cadena de conexión Escenario Comentarios
RunAs=Developer;DeveloperTool=AzureCli Desarrollo local AzureServiceTokenProvider usa AzureCli para obtener el token.
RunAs=Developer;DeveloperTool=VisualStudio Desarrollo local AzureServiceTokenProvider usa Visual Studio para obtener el token.
RunAs=CurrentUser Desarrollo local No se admite en .NET Core. AzureServiceTokenProvider usa la autenticación integrada de Azure AD para obtener el token.
RunAs=App Identidades administradas para recursos de Azure AzureServiceTokenProvider usa una identidad administrada para obtener el token.
RunAs=App;AppId={ClientId of user-assigned identity} Identidad asignada por el usuario para recursos de Azure AzureServiceTokenProvider usa una identidad asignada por el usuario para obtener el token.
RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier={KeyVaultCertificateSecretIdentifier} Autenticación en servicios personalizados KeyVaultCertificateSecretIdentifier es el identificador secreto del certificado.
RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};CertificateStoreLocation={LocalMachine or CurrentUser} Entidad de servicio AzureServiceTokenProvider usa el certificado para obtener el token desde Azure AD.
RunAs=App;AppId={AppId};TenantId={TenantId};CertificateSubjectName={Subject};CertificateStoreLocation={LocalMachine or CurrentUser} Entidad de servicio AzureServiceTokenProvider usa el certificado para obtener el token desde Azure AD.
RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret} Entidad de servicio AzureServiceTokenProvider usa el secreto para obtener el token desde Azure AD.

Ejemplos

Para ver la biblioteca Microsoft.Azure.Services.AppAuthentication en acción, consulte los siguientes ejemplos de código.

Solución de problemas de AppAuthentication

Problemas comunes durante el desarrollo local

La CLI de Azure no está instalada, no se ha iniciado sesión o no se cuenta con la versión más reciente

Ejecute az account get-access-token para ver si la CLI de Azure muestra un token automáticamente. Si indica que no se encontró dicho programa, instale la versión más reciente de la CLI de Azure. Es posible que se le pida que inicie sesión.

AzureServiceTokenProvider no puede encontrar la ruta de acceso de la CLI de Azure

AzureServiceTokenProvider busca la CLI de Azure en sus ubicaciones de instalación predeterminadas. Si no se puede encontrar la CLI de Azure, establezca la variable de entorno AzureCLIPath en la carpeta de instalación de la CLI de Azure. AzureServiceTokenProvider agregará la variable de entorno a la variable de entorno Path.

Ha iniciado sesión en la CLI de Azure con varias cuentas, la misma cuenta tiene acceso a las suscripciones de varios inquilinos o se recibe un error de acceso denegado al intentar realizar llamadas durante el desarrollo local

Con la CLI de Azure, establezca la suscripción predeterminada en una que tenga la cuenta que quiere usar. La suscripción debe estar en el mismo inquilino que el recurso al que quiere acceder: az account set --subscription [subscription-id] . Si no se muestra ninguna salida, significa que se ha realizado correctamente. Compruebe que la cuenta correcta es ahora el valor predeterminado mediante az account list.

Problemas comunes en los entornos

Acceso no autorizado, acceso denegado, prohibido o un error similar

La entidad de seguridad utilizada no tiene acceso al recurso al que intenta acceder. Conceda a la cuenta de usuario o al "colaborador" de MSI de App Service acceso a un recurso. La decisión depende de si está ejecutando el ejemplo en el equipo local o implementado en Azure en App Service. Algunos recursos, como los almacenes de claves, también tienen sus propias directivas de acceso, que se usan para conceder acceso a las entidades de seguridad, como usuarios, aplicaciones y grupos.

Problemas comunes al realizar la implementación en Azure App Service

La identidad administrada no se configura en App Service.

Compruebe si las variables de entorno MSI_ENDPOINT y MSI_SECRET existen mediante Kudu debug console. Si estas variables de entorno no existen, la identidad administrada no está habilitada en App Service.

Problemas comunes al realizar la implementación localmente con IIS

No se pueden recuperar los tokens al depurar la aplicación en IIS.

De manera predeterminada, AppAuth se ejecuta en un contexto de usuario diferente en IIS. Este es el motivo por el que no tiene acceso para usar la identidad de desarrollador para recuperar los tokens de acceso. Puede configurar IIS para que se ejecute con su contexto de usuario con los dos pasos siguientes:

  • Configure el grupo de aplicaciones para que la aplicación web se ejecute como su cuenta de usuario actual. Puede obtener más información aquí

  • Configure "setProfileEnvironment" en "True". Puede obtener más información aquí.

    • Vaya a %windir%\System32\inetsrv\config\applicationHost.config.
    • Busque "setProfileEnvironment". Si está establecido en "False", cámbielo a "True". Si no está presente, agréguelo como atributo al elemento processModel (/configuration/system.applicationHost/applicationPools/applicationPoolDefaults/processModel/@setProfileEnvironment) y establézcalo en "True".

  • Obtenga más información sobre las identidades administradas para recursos de Azure.

  • Más información sobre los escenarios de autenticación de Azure AD.