Biblioteca cliente de Azure Identity para Java: versión 1.10.4

La biblioteca de identidades de Azure proporciona compatibilidad con la autenticación de tokens de Azure Active Directory (Azure AD) en el SDK de Azure. Proporciona un conjunto de implementaciones de TokenCredential que se pueden usar para construir clientes del SDK de Azure que admiten la autenticación de tokens de Azure AD.

Código | fuenteDocumentación | de referencia de APIDocumentación de Azure AD

Introducción

Inclusión del paquete

Inclusión del archivo BOM

Incluya en el azure-sdk-bom proyecto para que tome una dependencia de la versión estable de la biblioteca. En el fragmento de código siguiente, reemplace el marcador de posición {bom_version_to_target} por el número de versión. Para más información sobre el BOM, consulte el archivo LÉAME de BOM del SDK de Azure.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

A continuación, incluya la dependencia directa en la dependencies sección sin la etiqueta de versión:

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
  </dependency>
</dependencies>

Inclusión de dependencias directas

Para depender de una versión determinada de la biblioteca que no está presente en la lista de materiales, agregue la dependencia directa al proyecto de la siguiente manera:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.10.1</version>
</dependency>

Requisitos previos

• Un kit de desarrollo de Java (JDK), versión 8 o posterior.
• Una suscripción de Azure.
• La CLI de Azure también puede ser útil para autenticarse en un entorno de desarrollo, crear cuentas y administrar roles de cuenta.

Autenticar el cliente

Al depurar y ejecutar código localmente, es habitual que un desarrollador use su propia cuenta para autenticar llamadas a servicios de Azure. Hay varias herramientas de desarrollo que se pueden usar para realizar esta autenticación en el entorno de desarrollo:

• Azure Toolkit for IntelliJ
• Visual Studio Code extensión de cuenta de Azure
  • Se trata de un problema conocido que VisualStudioCodeCredential no funciona con las versiones de la extensión de la cuenta de Azure más recientes que 0.9.11. Está en curso una corrección a largo plazo de este problema. Mientras tanto, considere la posibilidad de autenticarse a través de la CLI de Azure (a continuación).
• CLI de Azure

Seleccione cada elemento anterior para obtener información sobre cómo configurarlos para la autenticación de identidad de Azure.

Conceptos clave

Credenciales

Una credencial es una clase que contiene o puede obtener los datos necesarios para que un cliente del servicio autentique las solicitudes. Los clientes de servicio en el SDK de Azure aceptan credenciales cuando se construyen. Los clientes de servicio usan esas credenciales para autenticar las solicitudes en el servicio.

La biblioteca de identidades de Azure se centra en la autenticación de OAuth con Azure AD y ofrece varias clases de credenciales capaces de adquirir un token de Azure AD para autenticar las solicitudes de servicio. Todas las clases de credenciales de esta biblioteca son implementaciones de la TokenCredential clase abstracta en azure-core y cualquiera de ellas se puede usar para construir clientes de servicio capaces de autenticarse con .TokenCredential

Consulte Clases de credenciales para obtener una lista completa de las clases de credenciales disponibles.

DefaultAzureCredential

DefaultAzureCredential es adecuado para la mayoría de los escenarios en los que la aplicación está pensada para ejecutarse en última instancia en Azure. Esto se debe a que DefaultAzureCredential combina las credenciales que se suelen usar para autenticarse cuando se implementa, con las credenciales usadas para autenticarse en un entorno de desarrollo.

Nota: DefaultAzureCredential está pensado para simplificar la introducción al SDK mediante el control de escenarios comunes con comportamientos predeterminados razonables. Los desarrolladores que quieran tener más control o cuyo escenario no esté servido por la configuración predeterminada deben usar otros tipos de credenciales.

DefaultAzureCredential intentará autenticarse mediante los siguientes mecanismos en orden.

1. Entorno:DefaultAzureCredential leerá la información de la cuenta especificada a través de variables de entorno y la usará para autenticarse.
2. Identidad de carga de trabajo : si la aplicación se implementa en Kubernetes con variables de entorno establecidas por el webhook de identidad de carga de trabajo, DefaultAzureCredential autenticará la identidad configurada.
3. Identidad administrada : si la aplicación se implementa en un host de Azure con identidad administrada habilitada, se DefaultAzureCredential autenticará con esa cuenta.
4. Azure Developer CLI: si el desarrollador ha autenticado una cuenta a través del comando Azure Developer CLIazd auth login, se DefaultAzureCredential autenticará con esa cuenta.
5. IntelliJ : si el desarrollador se ha autenticado a través del kit de herramientas de Azure para IntelliJ, se DefaultAzureCredential autenticará con esa cuenta.
6. CLI de Azure : si el desarrollador ha autenticado una cuenta mediante el comando de la CLI az login de Azure, se DefaultAzureCredential autenticará con esa cuenta.
7. Azure PowerShell: si el desarrollador ha autenticado una cuenta a través del comando Azure PowerShellConnect-AzAccount, se DefaultAzureCredential autenticará con esa cuenta.

Directiva de continuación

A partir de la versión 1.10.0, DefaultAzureCredential intentará autenticarse con todas las credenciales de desarrollador hasta que se realice correctamente, independientemente de los errores que experimenten las credenciales de desarrollador anteriores. Por ejemplo, una credencial de desarrollador puede intentar obtener un token y producir un error, por lo que DefaultAzureCredential continuará con la siguiente credencial del flujo. Las credenciales de servicio implementadas detendrán el flujo con una excepción iniciada si pueden intentar la recuperación de tokens, pero no reciben una.

Esto permite probar todas las credenciales de desarrollador de la máquina mientras tiene un comportamiento implementado predecible.

Nota sobre VisualStudioCodeCredential

Debido a un problema conocido, VisualStudioCodeCredential se ha quitado de la DefaultAzureCredential cadena de tokens. Cuando se resuelva el problema en una versión futura, este cambio se revertirá.

Ejemplos

Puede encontrar más ejemplos de uso de varias credenciales en la página Wiki de ejemplos de identidad de Azure.

Autenticación con DefaultAzureCredential

En el siguiente ejemplo se muestra la autenticación del elemento SecretClient de la biblioteca cliente azure-security-keyvault-secrets con la clase DefaultAzureCredential.

/**
 * The default credential first checks environment variables for configuration.
 * If environment configuration is incomplete, it will try managed identity.
 */
public void createDefaultAzureCredential() {
    DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder().build();

    // Azure SDK client builders accept the credential as a parameter
    SecretClient client = new SecretClientBuilder()
        .vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net")
        .credential(defaultCredential)
        .buildClient();
}

Consulte más información sobre cómo configurar en la DefaultAzureCredential estación de trabajo o Azure en Configuración de DefaultAzureCredential.

Autenticación de una identidad administrada asignada por el usuario con DefaultAzureCredential

Para autenticarse mediante la identidad administrada asignada por el usuario, asegúrese de que las instrucciones de configuración del recurso de Azure admitido se han completado correctamente.

En el DefaultAzureCredentialejemplo siguiente se muestra cómo SecretClient autenticar desde la biblioteca cliente azure-security-keyvault-secrets mediante , implementado en un recurso de Azure con una identidad administrada asignada por el usuario configurada.

Consulte más información sobre cómo configurar una identidad administrada asignada por el usuario para un recurso de Azure en Habilitación de la identidad administrada para recursos de Azure.

/**
 * The default credential will use the user assigned managed identity with the specified client ID.
 */
public void createDefaultAzureCredentialForUserAssignedManagedIdentity() {
    DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder()
        .managedIdentityClientId("<MANAGED_IDENTITY_CLIENT_ID>")
        .build();

    // Azure SDK client builders accept the credential as a parameter
    SecretClient client = new SecretClientBuilder()
        .vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net")
        .credential(defaultCredential)
        .buildClient();
}

Además de configurar mediante managedIdentityClientId código, también se puede establecer mediante la AZURE_CLIENT_ID variable de entorno . Estos dos enfoques son equivalentes al usar .DefaultAzureCredential

Autenticación de un usuario en el kit de herramientas de Azure para IntelliJ con DefaultAzureCredential

Para autenticarse con IntelliJ, asegúrese de que las instrucciones de configuración aquí se han completado correctamente.

En el DefaultAzureCredentialejemplo siguiente se muestra cómo autenticar SecretClient desde la biblioteca cliente azure-security-keyvault-secrets mediante , en una estación de trabajo con IntelliJ IDEA instalada y el usuario ha iniciado sesión con una cuenta de Azure en el Kit de herramientas de Azure para IntelliJ.

Consulte más información sobre cómo configurar intelliJ IDEA en El kit de herramientas de Azure para IntelliJ para IntelliJCredential.

/**
 * The default credential will use the KeePass database path to find the user account in IntelliJ on Windows.
 */
public void createDefaultAzureCredentialForIntelliJ() {
    DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder()
        // KeePass configuration required only for Windows. No configuration needed for Linux / Mac
        .intelliJKeePassDatabasePath("C:\\Users\\user\\AppData\\Roaming\\JetBrains\\IdeaIC2020.1\\c.kdbx")
        .build();

    // Azure SDK client builders accept the credential as a parameter
    SecretClient client = new SecretClientBuilder()
        .vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net")
        .credential(defaultCredential)
        .buildClient();
}

Compatibilidad con identidades administradas

La autenticación de identidad administrada se admite a través de DefaultAzureCredential o ManagedIdentityCredential directamente para los siguientes servicios de Azure:

• Para Azure App Service y Azure Functions
• Azure Arc
• Azure Cloud Shell
• Azure Kubernetes Service
• Azure Service Fabric
• Azure Virtual Machines
• Conjuntos de escalado de Azure Virtual Machines

Nota: Use azure-identity la versión 1.7.0 o posterior para usar la compatibilidad con el almacenamiento en caché de tokens para la autenticación de identidad administrada.

Ejemplos

Autenticación en Azure con identidad administrada

En este ejemplo se muestra cómo SecretClient autenticar desde la biblioteca cliente azure-security-keyvault-secrets mediante en ManagedIdentityCredential una máquina virtual, app service, aplicación de funciones, cloud shell o entorno de AKS en Azure, con la identidad administrada asignada por el sistema o asignada por el usuario habilitada.

Consulte más información sobre cómo configurar el recurso de Azure para la identidad administrada en Habilitación de la identidad administrada para recursos de Azure.

/**
 * Authenticate with a User Assigned Managed identity.
 */
public void createManagedIdentityCredential() {
    ManagedIdentityCredential managedIdentityCredential = new ManagedIdentityCredentialBuilder()
        .clientId("<USER ASSIGNED MANAGED IDENTITY CLIENT ID>") // only required for user assigned
        .build();

    // Azure SDK client builders accept the credential as a parameter
    SecretClient client = new SecretClientBuilder()
        .vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net")
        .credential(managedIdentityCredential)
        .buildClient();
}

/**
 * Authenticate with a System Assigned Managed identity.
 */
public void createManagedIdentityCredential() {
    ManagedIdentityCredential managedIdentityCredential = new ManagedIdentityCredentialBuilder()
        .build();

    // Azure SDK client builders accept the credential as a parameter
    SecretClient client = new SecretClientBuilder()
        .vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net")
        .credential(managedIdentityCredential)
        .buildClient();
}

Definición de un flujo de autenticación personalizado con ChainedTokenCredential

Aunque DefaultAzureCredential generalmente es la forma más rápida de empezar a desarrollar aplicaciones para Azure, es posible que los usuarios más avanzados quieran personalizar las credenciales que se tienen en cuenta al autenticarse. ChainedTokenCredential permite a los usuarios combinar varias instancias de credenciales para definir una cadena personalizada de credenciales. En este ejemplo se muestra cómo crear un ChainedTokenCredential, que hará lo siguiente:

• Intente autenticarse mediante la identidad administrada.
• Vuelva a la autenticación a través de la CLI de Azure si la identidad administrada no está disponible en el entorno actual.

// Authenticate using managed identity if it is available; otherwise use the Azure CLI to authenticate.

    ManagedIdentityCredential managedIdentityCredential = new ManagedIdentityCredentialBuilder().build();
    AzureCliCredential cliCredential = new AzureCliCredentialBuilder().build();

    ChainedTokenCredential credential = new ChainedTokenCredentialBuilder().addLast(managedIdentityCredential).addLast(cliCredential).build();

    // Azure SDK client builders accept the credential as a parameter
    SecretClient client = new SecretClientBuilder()
        .vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net")
        .credential(credential)
        .buildClient();

Cloud configuration

Las credenciales se autentican de forma predeterminada en el punto de conexión de Azure AD para la nube pública de Azure. Para acceder a los recursos de otras nubes, como Azure Government o una nube privada, configure las credenciales con el auhtorityHost argumento . AzureAuthorityHosts define autoridades para nubes conocidas:

DefaultAzureCredential defaultAzureCredential = new DefaultAzureCredentialBuilder()
    .authorityHost(AzureAuthorityHosts.AZURE_GOVERNMENT)
    .build();

No todas las credenciales requieren esta configuración. Las credenciales que se autentican a través de una herramienta de desarrollo, como AzureCliCredential, usan la configuración de esa herramienta. Del mismo modo, VisualStudioCodeCredential acepta un authority argumento, pero el valor predeterminado es la configuración "Azure: Cloud" de VS Code que coincide con la autoridad.

Clases de credenciales

Autenticación de aplicaciones hospedadas en Azure

Autenticación de aplicaciones hospedadas en Azure

Clase credential	Uso	Ejemplo
DefaultAzureCredential	proporciona una experiencia de autenticación simplificada para empezar a desarrollar rápidamente aplicaciones que se ejecutan en Azure.	ejemplo
ChainedTokenCredential	permite a los usuarios definir flujos de autenticación personalizados que componen varias credenciales	ejemplo
EnvironmentCredential	autentica una entidad de servicio o un usuario a través de la información de credenciales especificada en variables de entorno.
ManagedIdentityCredential	autentica la identidad administrada de un recurso de Azure.	ejemplo
WorkloadIdentityCredential	admite la identidad de carga de trabajo de Azure AD en Kubernetes	ejemplo

Autenticación de entidades de servicio

Autenticación de entidades de servicio

Clase credential	Uso	Ejemplo	Referencia
ClientAssertionCredential	autentica una entidad de servicio mediante una aserción de cliente firmada
ClientCertificateCredential	autentica una entidad de servicio mediante un certificado	ejemplo	Autenticación de entidad de servicio
ClientSecretCredential	autentica una entidad de servicio mediante un secreto	ejemplo	Autenticación de entidad de servicio

Autenticación de usuarios

Autenticación de usuarios

Clase credential	Uso	Ejemplo	Referencia
AuthorizationCodeCredential	autenticar a un usuario con un código de autorización obtenido previamente como parte de un flujo de Oauth 2		Código de autenticación OAuth2
DeviceCodeCredential	autentica interactivamente a un usuario en dispositivos con una interfaz de usuario limitada	ejemplo	Autenticación con código de dispositivo
InteractiveBrowserCredential	autentica interactivamente a un usuario con el explorador del sistema predeterminado	ejemplo	Código de autenticación OAuth2
OnBehalfOfCredential	propaga la identidad de usuario delegada y los permisos a través de la cadena de solicitudes.		Autenticación en nombre de
UsernamePasswordCredential	autentica a un usuario con un nombre de usuario y una contraseña sin autenticación multifactor	ejemplo	Autenticación con nombre de usuario y contraseña

Autenticación mediante herramientas de desarrollo

Autenticación mediante herramientas de desarrollo

Clase credential	Uso	Ejemplo	Referencia
AzureCliCredential	Autenticación en un entorno de desarrollo con el usuario o la entidad de servicio habilitados en la CLI de Azure	ejemplo	Autenticación de la CLI de Azure
AzureDeveloperCliCredential	Autenticación en un entorno de desarrollo con el usuario o la entidad de servicio habilitados en Azure Developer CLI		Referencia de Azure Developer CLI
AzurePowerShellCredential	Autenticación en un entorno de desarrollo con el usuario o la entidad de servicio habilitados en Azure PowerShell	ejemplo	Documentación de Azure PowerShell
IntelliJCredential	Autenticación en un entorno de desarrollo con la cuenta del kit de herramientas de Azure para IntelliJ	ejemplo	Autenticación de IntelliJ
VisualStudioCodeCredential	Autentíquese en un entorno de desarrollo con la cuenta en Visual Studio Code extensión de cuenta de Azure.	ejemplo	Extensión de la cuenta de Azure de VS Code

Nota: Todas las implementaciones de credenciales de la biblioteca de identidades de Azure son threadsafe y se puede usar una única instancia de credenciales para crear varios clientes de servicio.

Las credenciales se pueden encadenar juntas para que se intenten a su vez hasta que una se realice correctamente con ChainedTokenCredential; vea Encadenamiento de credenciales para obtener más información.

Variables de entorno

DefaultAzureCredential y EnvironmentCredential se pueden configurar con variables de entorno. Cada tipo de autenticación requiere valores para variables específicas:

Entidad de servicio con secreto

Entidad de servicio con secreto

Nombre de la variable	Valor
AZURE_CLIENT_ID	Identificador de una aplicación de Azure Active Directory
AZURE_TENANT_ID	Identificador del inquilino de Azure Active Directory de la aplicación
AZURE_CLIENT_SECRET	uno de los secretos de cliente de la aplicación

Entidad de servicio con certificado

Entidad de servicio con certificado

Nombre de la variable	Valor
AZURE_CLIENT_ID	Identificador de una aplicación de Azure Active Directory
AZURE_TENANT_ID	Identificador del inquilino de Azure Active Directory de la aplicación
AZURE_CLIENT_CERTIFICATE_PATH	ruta de acceso a un archivo de certificado con codificación PFX o PEM, incluida la clave privada
AZURE_CLIENT_CERTIFICATE_PASSWORD	(opcional) contraseña para el certificado. El certificado no se puede proteger con contraseña a menos que se especifique este valor.

Nombre de usuario y contraseña

Nombre de usuario y contraseña

Nombre de la variable	Valor
AZURE_CLIENT_ID	Identificador de una aplicación de Azure Active Directory
AZURE_TENANT_ID	(opcional) Identificador del inquilino de Azure AD de la aplicación
AZURE_USERNAME	nombre de usuario (normalmente una dirección de correo electrónico).
AZURE_PASSWORD	la contraseña del usuario

La configuración se intenta en el orden anterior. Por ejemplo, si los valores del secreto de cliente y el certificado están presentes, se utilizará el secreto de cliente.

Evaluación continua de acceso

A partir de la versión 1.10.0, el acceso a los recursos protegidos por evaluación continua de acceso (CAE) es posible por solicitud. Esto se puede habilitar mediante la TokenRequestContext.setCaeEnabled(boolean) API. CAE no es compatible con las credenciales de desarrollador.

Almacenamiento en caché de tokens

El almacenamiento en caché de tokens es una característica proporcionada por la biblioteca de identidades de Azure que permite a las aplicaciones:

• Caché de tokens en memoria (valor predeterminado) o en disco (participación).
• Mejorar la resistencia y el rendimiento.
• Reduzca el número de solicitudes realizadas a Azure AD para obtener tokens de acceso.

La biblioteca de identidades de Azure ofrece almacenamiento en caché de disco persistente y en memoria. Para más información, consulte la documentación del almacenamiento en caché de tokens.

Solución de problemas

Las credenciales generan excepciones cuando no se autentican o no pueden ejecutar la autenticación. Cuando las credenciales no se autentican, se genera .ClientAuthenticationException La excepción tiene un atributo , que describe por qué se produjo un message error de autenticación. Cuando se produce esta excepción, ChainedTokenCredentialse detiene la ejecución encadenada de la lista subyacente de credenciales.

Cuando las credenciales no pueden ejecutar la autenticación debido a que una de las credenciales subyacentes requeridas por la credencial no está disponible en el equipo, se genera .CredentialUnavailableException La excepción tiene un message atributo que describe por qué la credencial no está disponible para la ejecución de la autenticación. Cuando se produce ChainedTokenCredentialesta excepción, el mensaje recopila mensajes de error de cada credencial de la cadena.

Consulte la guía de solución de problemas para obtener más información sobre cómo diagnosticar varios escenarios de error.

Pasos siguientes

Las bibliotecas cliente de Java enumeradas aquí admiten la autenticación con TokenCredential y la biblioteca de identidades de Azure. Puede obtener más información sobre su uso y encontrar documentación adicional sobre el uso de estas bibliotecas cliente junto con ejemplos con se puede encontrar en los vínculos mencionados aquí.

Microsoft-graph-sdk también admite la autenticación con TokenCredential y la biblioteca de identidades de Azure.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

El proyecto ha adoptado el Código de conducta de código abierto de Microsoft. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.