Conexión mediante la autenticación de Microsoft Entra

Descargar controlador JDBC

En este artículo se proporciona información sobre cómo desarrollar aplicaciones Java que usan la característica de autenticación de Microsoft Entra con Microsoft JDBC Driver para SQL Server.

La autenticación de Microsoft Entra es un mecanismo para conectarse a labase de datos de Azure SQL, Azure SQL Managed Instance y Azure Synapse Analytics mediante identidades de Microsoft Entra ID. Use la autenticación de Microsoft Entra para administrar identidades de usuarios de base de datos de forma centralizada y como alternativa a la autenticación de SQL Server. El controlador JDBC te permite especificar las credenciales de Microsoft Entra en la cadena de conexión de JDBC para conectarte a Azure SQL. Para más información sobre cómo configurar la autenticación de Microsoft Entra en Azure SQL, consulta Conectarse a Azure SQL mediante la autenticación de Microsoft Entra.

Las propiedades de conexión para admitir la autenticación de Microsoft Entra en Microsoft JDBC Driver para SQL Server son:

• authentication: use esta propiedad para indicar qué método de autenticación de SQL se va a utilizar en la conexión. Los valores posibles son:

  • ActiveDirectoryManagedIdentity

    • A partir de la versión 8.3.1 del controlador, authentication=ActiveDirectoryMSI se puede usar para conectarse a Azure SQL Database o Synapse Analytics desde un recurso de Azure con la compatibilidad con "Identidad" habilitada. Opcionalmente, se puede especificar msiClientId en las propiedades de conexión/origen de datos junto con este modo de autenticación. msiClientId debe contener el identificador de cliente de una identidad administrada que se usará para adquirir accessToken para establecer la conexión. A partir de la versión v12.2 del controlador, también se puede usar para conectarse a Azure SQL Database o Synapse Analytics desde un recurso de Azure con la compatibilidad con "Identidad" habilitada. Opcionalmente, el identificador de cliente de una identidad administrada también se puede establecer ahora en la propiedad user. Para obtener más información, consulte Conectarse mediante el modo de autenticación ActiveDirectoryManagedIdentity.

  • ActiveDirectoryDefault

    • A partir de la versión 12.2 del controlador, authentication=ActiveDirectoryDefault pse puede usar para conectarse a una base de datos Azure SQL Database/Synapse Analytics a través de la DefaultAzureCredential de la biblioteca de clientes Azure Identity. Para obtener más información, consulte Conectarse mediante el modo autenticación de Azure Active Directory.

  • ActiveDirectoryIntegrated

    • A partir de la versión 6.0 del controlador, authentication=ActiveDirectoryIntegrated se puede usar para conectarse con Azure SQL o Synapse Analytics mediante la autenticación integrada. Para usar este modo de autenticación, debes federar los Servicios de federación de Active Directory (AD FS) locales con Microsoft Entra ID en la nube. Una vez que lo haya configurado, puede conectarse si agrega la biblioteca nativa mssql-jdbc_auth-<version>-<arch>.dll a la ruta de acceso de la clase de aplicación de Windows, o bien si configura un vale Kerberos para la compatibilidad con la autenticación multiplataforma. Puedes acceder a Azure SQL o Azure Synapse Analytics sin que se te soliciten credenciales al iniciar sesión en una máquina unida al dominio. Para obtener más información, consulte Conexión con el modo de autenticación ActiveDirectoryIntegrated.

  • ActiveDirectoryPassword

    • A partir de la versión 6.0 del controlador, authentication=ActiveDirectoryPassword se puede usar para conectarse con Azure SQL Database o Synapse Analytics mediante un nombre de usuario de Microsoft Entra y una contraseña. Para obtener más información, consulte Conexión con el modo de autenticación ActiveDirectoryPassword.

  • ActiveDirectoryInteractive

    • A partir de la versión 9.2 del controlador, authentication=ActiveDirectoryInteractive se puede usar para conectarse con Azure SQL o Synapse Analytics mediante un flujo de autenticación interactiva (autenticación multifactor). Para obtener más información, consulte Conexión con el modo de autenticación ActiveDirectoryInteractive.

  • ActiveDirectoryServicePrincipal

    • A partir de la versión 9.2 del controlador, authentication=ActiveDirectoryServicePrincipal se puede usar para conectarse con Azure SQL o Synapse Analytics especificando el ID de cliente o aplicación en la propiedad "userName" y el secreto de una identidad de entidad de servicio en la propiedad "password". Para obtener más información, consulte Conexión con el modo de autenticación ActiveDirectoryServicePrincipal.

  • ActiveDirectoryServicePrincipalCertificate

    • A partir de la versión 12.4 del controlador, authentication=ActiveDirectoryServicePrincipalCertificate se puede usar para conectarse con Azure SQL Database o Synapse Analytics especificando el ID de cliente o aplicación en la propiedad userName y la ubicación del certificado de la entidad de servicio en la propiedad clientCertificate. Para obtener más información, consulte Conexión con el modo de autenticación ActiveDirectoryServicePrincipalCertificate.

  • SqlPassword

    • Use authentication=SqlPassword para conectarse a un servidor SQL Server mediante las propiedades userName/user y password.

  • NotSpecified

    • Use authentication=NotSpecified o déjelo como valor predeterminado cuando no se necesite ninguno de estos métodos de autenticación.

  • accessToken: use esta propiedad de conexión para conectarse a una base de datos SQL con un token de acceso. Solo se puede establecer accessToken mediante el parámetro Properties del método getConnection() en la clase DriverManager. No se puede usar en la URL de conexión.

Para obtener más información, consulte la propiedad de autenticación en la página Establecer las propiedades de conexión.

Requisitos de configuración del cliente

Además de los requisitos básicos del sistema del controlador, los siguientes modos de autenticación tienen más requisitos.

En la tabla siguiente se enumeran las dependencias de biblioteca necesarias para cada modo de autenticación y la versión del controlador. También se requieren dependencias de dependencias.

Nota:

En los casos en los que la reparación de una versión principal tiene una versión de dependencia diferente a la de su versión principal, también se muestra la reparación.

Opción de autenticación	Versiones del controlador	Dependencias de biblioteca
ActiveDirectoryPassword ActiveDirectoryIntegrated	6.0	Adal4j 1.3.0
ActiveDirectoryPassword ActiveDirectoryIntegrated	6.2.2 - 6.4	Adal4j 1.4.0
ActiveDirectoryPassword ActiveDirectoryIntegrated	7.0	Adal4j 1.6.0
ActiveDirectoryPassword ActiveDirectoryIntegrated	7.2	Adal4j 1.6.3 Client-Runtime-for-AutoRest 1.6.5
ActiveDirectoryPassword ActiveDirectoryIntegrated	7.4 - 8.2	Adal4jl4j 1.6.4 Client-Runtime-for-AutoRest 1.7.0
ActiveDirectoryPassword ActiveDirectoryIntegrated	8,4	Adal4j 1.6.5 Client-Runtime-for-AutoRest 1.7.4
ActiveDirectoryPassword ActiveDirectoryIntegrated ActiveDirectoryInteractive ActiveDirectoryServicePrincipal	9.2	msal4j 1.7.1
ActiveDirectoryPassword ActiveDirectoryIntegrated ActiveDirectoryInteractive ActiveDirectoryServicePrincipal	9,4	msal4j 1.10.1
ActiveDirectoryPassword ActiveDirectoryIntegrated ActiveDirectoryInteractive ActiveDirectoryServicePrincipal	10.2	msal4j 1.11.0
ActiveDirectoryPassword ActiveDirectoryIntegrated ActiveDirectoryInteractive ActiveDirectoryServicePrincipal	11.2	msal4j 1.11.3
ActiveDirectoryPassword ActiveDirectoryIntegrated ActiveDirectoryInteractive ActiveDirectoryServicePrincipal	11.2.3	msal4j 1.13.0
ActiveDirectoryPassword ActiveDirectoryIntegrated ActiveDirectoryInteractive ActiveDirectoryServicePrincipal	12,2	msal4j 1.13.3
ActiveDirectoryManagedIdentity ActiveDirectoryMSI ActiveDirectoryDefault	12,2	azure-identity 1.7.0
ActiveDirectoryPassword ActiveDirectoryIntegrated ActiveDirectoryInteractive ActiveDirectoryServicePrincipal ActiveDirectoryServicePrincipalCertificate	12.4	msal4j 1.13.8
ActiveDirectoryManagedIdentity ActiveDirectoryMSI ActiveDirectoryDefault	12.4	azure-identity 1.9.0
ActiveDirectoryPassword ActiveDirectoryIntegrated ActiveDirectoryInteractive ActiveDirectoryServicePrincipal ActiveDirectoryServicePrincipalCertificate	12.6	msal4j 1.14.1
ActiveDirectoryManagedIdentity ActiveDirectoryMSI ActiveDirectoryDefault	12.6	azure-identity 1.11.1
ActiveDirectoryPassword ActiveDirectoryIntegrated ActiveDirectoryInteractive ActiveDirectoryServicePrincipal ActiveDirectoryServicePrincipalCertificate	12.6.3	msal4j 1.15.1
ActiveDirectoryManagedIdentity ActiveDirectoryMSI ActiveDirectoryDefault	12.6.3	azure-identity 1.12.2
ActiveDirectoryPassword ActiveDirectoryIntegrated ActiveDirectoryInteractive ActiveDirectoryServicePrincipal ActiveDirectoryServicePrincipalCertificate	12.6.4	msal4j 1.15.1
ActiveDirectoryManagedIdentity ActiveDirectoryMSI ActiveDirectoryDefault	12.6.4	azure-identity 1.12.2
ActiveDirectoryPassword ActiveDirectoryIntegrated ActiveDirectoryInteractive ActiveDirectoryServicePrincipal ActiveDirectoryServicePrincipalCertificate	12.8	msal4j 1.15.1
ActiveDirectoryManagedIdentity ActiveDirectoryMSI ActiveDirectoryDefault	12.8	azure-identity 1.12.2

Conexión con el modo de autenticación ActiveDirectoryManagedIdentity

Este modo de autenticación se admite a partir de la versión 7.2. Para usarlo, especifique authentication=ActiveDirectoryMSI. A partir de la versión 12.2, authentication=ActiveDirectoryManagedIdentity también se puede especificar.

Además de los requisitos de dependencia de la biblioteca enumerados en Requisitos de configuración de cliente, esta característica tiene los siguientes requisitos:

• La base de datos de destino debe tener un usuario de base de datos independiente, con permiso CONNECT. El usuario contenido debe representar la Identidad Administrada Asignada por el Sistema o la Identidad Administrada Asignada por el Usuario de su Recurso Azure, o uno de los grupos a los que pertenece su Identidad Administrada.

• El entorno de cliente debe ser un recurso de Azure y debe tener habilitada la compatibilidad con la característica de "identidad". En la tabla siguiente se enumeran los servicios de Azure admitidos por cada versión del controlador JDBC:

  Versión del controlador	Dependencias requeridas	Servicios de Azure admitidos
  7.2 - 11.2	None	Para Azure App Service y Azure Functions Azure Virtual Machines
  12,2 12.4 12.6 12.8	azure-identity 1.7.0 azure-identity 1.9.0 azure-identity 1.11.1 azure-identity 1.12.2	Para Azure App Service y Azure Functions Azure Arc Azure Cloud Shell Azure Kubernetes Service Azure Service Fabric Azure Virtual Machines Azure Virtual Machines Scale Sets

En el siguiente ejemplo se muestra cómo usar el modo authentication=ActiveDirectoryManagedIdentity. Ejecute este ejemplo desde un recurso de Azure configurado para la identidad administrada.

Para ejecutar el ejemplo, reemplace el nombre del servidor o la base de datos por su nombre del servidor o la base de datos en las líneas siguientes:

ds.setServerName("msentra-managed-demo.database.windows.net"); // replace 'msentra-managed-demo' with your server name
ds.setDatabaseName("demo"); // replace with your database name
//Optional
ds.setMSIClientId("<managed_identity_client>"); // Replace with Client ID of user-assigned managed identity to be used

El ejemplo para usar el modo de autenticación ActiveDirectoryMSI:

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;

import com.microsoft.sqlserver.jdbc.SQLServerDataSource;

public class MsEntraMSI {
    public static void main(String[] args) throws Exception {

        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replace with your server name
        ds.setDatabaseName("demo"); // Replace with your database name
        ds.setAuthentication("ActiveDirectoryMSI");
        // Optional
        ds.setMSIClientId("<managed_identity_client_guid>"); // Replace with Client ID of user-assigned managed identity to be used

        try (Connection connection = ds.getConnection();
                Statement stmt = connection.createStatement();
                ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

En el siguiente ejemplo se muestra el procedimiento para usar el modo authentication=ActiveDirectoryManagedIdentity.

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;

import com.microsoft.sqlserver.jdbc.SQLServerDataSource;

public class MSEntraManagedIdentity {
    public static void main(String[] args) throws Exception {

        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replace with your server name
        ds.setDatabaseName("demo"); // Replace with your database name
        ds.setAuthentication("ActiveDirectoryManagedIdentity"); // ActiveDirectoryManagedIdentity for JDBC driver version v12.2.0+
        // Optional
        ds.setUser("<managed_identity_client>"); // Replace with Client ID of User-Assigned Managed Identity to be used

        try (Connection connection = ds.getConnection();
                Statement stmt = connection.createStatement();
                ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

En estos ejemplos en una máquina virtual de Azure, se captura un token de acceso de la identidad administrada asignada por el sistema o la identidad administrada asignada por el usuario (si se especifica msiClientId o user con un identificador de cliente de una identidad administrada) y se establece una conexión mediante el token de acceso capturado. Si se establece una conexión, debería ver el mensaje siguiente:

You have successfully logged on as: <your Managed Identity username>

Conexión con el modo de autenticación ActiveDirectoryDefault

La opción de autenticación ActiveDirectoryDefault usa la implementación encadenada TokenCredential de la biblioteca cliente DefaultAzureCredential de Azure Identity. La credencial combina métodos de autenticación usados habitualmente encadenados conjuntamente.

La autenticación ActiveDirectoryDefault requiere una dependencia en tiempo de ejecución en la biblioteca cliente de identidades de Azure para la identidad administrada. Para obtener más información sobre la versión de la biblioteca, consulte Requisitos de configuración del cliente.

En la tabla siguiente se muestra la cadena de credenciales DefaultAzureCredential para cada versión del controlador JDBC.

Versión del controlador	documentación de la versión de azure-identity	cadena DefaultAzureCredential
12,2	azure-identity 1.7.0	Entorno Identidad administrada IntelliJ CLI de Azure Azure PowerShell
12.4	azure-identity 1.9.0	Entorno Identidad de carga de trabajo Identidad administrada CLI de desarrollo de Azure IntelliJ CLI de Azure Azure PowerShell
12.6	azure-identity 1.11.1	Entorno Identidad de carga de trabajo Identidad administrada CLI de desarrollo de Azure IntelliJ CLI de Azure Azure PowerShell
12.8	azure-identity 1.12.2	Entorno Identidad de carga de trabajo Identidad administrada CLI de desarrollo de Azure IntelliJ CLI de Azure Azure PowerShell

Hay muchas variables que se pueden establecer para configurar la credencial Environment. Para más información sobre cómo configurar la cadena DefaulAzureCredential, incluida la credencial Environment, consulte la versión pertinente de los documentos de azure-identity vinculados en la tabla anterior.

Para usar IntellijCredential en Windows, establezca la variable de entorno INTELLIJ_KEEPASS_PATH en la ubicación del archivo keepass. Por ejemplo, INTELLIJ_KEEPASS_PATH=C:\user\your\path\to\the\keepass\file.

Para proporcionar más inquilinos a DefaultAzureCredential, use la variable de entorno ADDITIONALLY_ALLOWED_TENANTS. Esta variable toma una lista delimitada por comas. Por ejemplo: ADDITIONALLY_ALLOWED_TENANTS=<your-tenant-id-0>,<your-tenant-id-1>,<your-tenant-id-2>,...

En el ejemplo siguiente se muestra el procedimiento para usar el modo authentication=ActiveDirectoryDefault con AzureCliCredential en DefaultAzureCredential.

1. Primero inicie sesión en la CLI de Azure con el siguiente comando.

   az login
   

2. Después de iniciar sesión correctamente en la CLI de Azure, ejecute el código siguiente.

   import java.sql.Connection;
   import java.sql.ResultSet;
   import java.sql.Statement;
   
   import com.microsoft.sqlserver.jdbc.SQLServerDataSource;
   
   public class MSEntraDefault {
       public static void main(String[] args) throws Exception {
   
           SQLServerDataSource ds = new SQLServerDataSource();
           ds.setServerName("msentra-managed-demo.database.windows.net"); // Replace with your server name
           ds.setDatabaseName("demo"); // Replace with your database name
           ds.setAuthentication("ActiveDirectoryDefault");
   
           try (Connection connection = ds.getConnection();
                   Statement stmt = connection.createStatement();
                   ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
               if (rs.next()) {
                   System.out.println("You have successfully logged on as: " + rs.getString(1));
               }
           }
       }
   }
   

Conexión con el modo de autenticación ActiveDirectoryIntegrated

Hay dos maneras de usar la autenticación de ActiveDirectoryIntegrated en Controlador JBDC para SQL Server de Microsoft:

• En Windows, se puede copiar el archivo mssql-jdbc_auth-<version>-<arch>.dll del paquete descargado y pegarlo en una ubicación de la ruta de acceso del sistema.
• Si no puede usar el archivo DLL, a partir de la versión 6.4, puede configurar un vale kerberos. Este método es compatible con todas las plataformas (Windows, Linux y macOS). Para obtener más información, vea Establecimiento del vale Kerberos en Windows, Linux y macOS.

Asegúrese de que ha requerido bibliotecas dependientes de los requisitos de configuración del cliente.

En el siguiente ejemplo se muestra cómo usar el modo authentication=ActiveDirectoryIntegrated. Este ejemplo se ejecuta en una máquina unida al dominio que se federa con Microsoft Entra ID. En la base de datos debe haber un usuario de base de datos independiente que represente a su usuario de Windows y debe tener el permiso CONNECT.

Reemplace el nombre del servidor o la base de datos por su nombre del servidor o la base de datos en las siguientes líneas antes de ejecutar el ejemplo:

ds.setServerName("msentra-managed-demo.database.windows.net"); // replace 'msentra-managed-demo' with your server name
ds.setDatabaseName("demo"); // replace with your database name

El ejemplo para usar el modo de autenticación ActiveDirectoryIntegrated:

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;

import com.microsoft.sqlserver.jdbc.SQLServerDataSource;

public class MSEntraIntegrated {
    public static void main(String[] args) throws Exception {

        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replace with your server name
        ds.setDatabaseName("demo"); // Replace with your database name
        ds.setAuthentication("ActiveDirectoryIntegrated");

        try (Connection connection = ds.getConnection();
                Statement stmt = connection.createStatement();
                ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

La ejecución de este ejemplo utiliza automáticamente su vale Kerberos de la plataforma cliente y no se requiere ninguna contraseña. Si se establece una conexión, debería ver el mensaje siguiente:

You have successfully logged on as: <your domain user name>

Establecimiento del vale Kerberos en Windows, Linux y macOS

Debe configurar un vale Kerberos para vincular el usuario actual a una cuenta de dominio de Windows. A continuación se resumen los pasos necesarios.

Windows

Nota:

En Windows, se puede usar el archivo mssql-jdbc_auth-<version>-<arch>.dll del paquete descargado en lugar de estos pasos de configuración de Kerberos. Estos pasos solo son necesarios si no se puede usar el archivo DLL.

JDK incluye kinit, que puede usar para obtener un TGT del Centro de distribución de claves (KDC) en una máquina unida al dominio que se federa con Microsoft Entra ID.

Paso 1: Recuperación de un vale de concesión de vales

• Ejecutar en: Windows

• Acción:

  • Use el comando kinit username@DOMAIN.COMPANY.COM para obtener un TGT de KDC y, a continuación, le solicitará la contraseña del dominio.
  • Use klist para ver los vales disponibles. Si el comando kinit se ha ejecutado correctamente, debería ver un vale de krbtgt/DOMAIN.COMPANY.COM@ DOMAIN.COMPANY.COM.

  Nota:

  Puede que tenga que especificar un archivo .ini con -Djava.security.krb5.conf para que la aplicación busque KDC.

Linux y macOS

Requisitos

Acceso a un equipo Windows unido a dominio para consultar el controlador de dominio de Kerberos.

Paso 1: Búsqueda de KDC de Kerberos

• Ejecutar en: Línea de comandos de Windows

• Acción: nltest /dsgetdc:DOMAIN.COMPANY.COM (donde DOMAIN.COMPANY.COM se asigna al nombre del dominio)

• Salida de ejemplo

  DC: \\co1-red-dc-33.domain.company.com
  Address: \\2111:4444:2111:33:1111:ecff:ffff:3333
  ...
  The command completed successfully
  

• Información para extraer El nombre del controlador de dominio, en este caso co1-red-dc-33.domain.company.com

Paso 2: Configuración de KDC en krb5.conf

• Ejecutar en: Linux/macOS

• Acción: Edite /etc/krb5.conf en el editor que prefiera. Configure las claves siguientes

  [libdefaults]
    default_realm = DOMAIN.COMPANY.COM
  
  [realms]
  DOMAIN.COMPANY.COM = {
     kdc = co1-red-dc-28.domain.company.com
  }
  

  Guarde el archivo krb5.conf y salga.

  Nota:

  El dominio debe estar en MAYÚSCULAS.

Paso 3: Prueba de la recuperación de un vale de concesión de vales

• Ejecutar en: Linux/macOS
• Acción: 
  • Use el comando kinit username@DOMAIN.COMPANY.COM para obtener un TGT de KDC y, a continuación, le solicitará la contraseña del dominio.
  • Use klist para ver los vales disponibles. Si el comando kinit se ha ejecutado correctamente, debería ver un vale de krbtgt/DOMAIN.COMPANY.COM@ DOMAIN.COMPANY.COM.

Conexión con el modo de autenticación ActiveDirectoryPassword

En el siguiente ejemplo se muestra cómo usar el modo authentication=ActiveDirectoryPassword.

Para compilar y ejecutar el ejemplo:

1. Asegúrese de que ha requerido bibliotecas dependientes de los requisitos de configuración del cliente.

2. Busque las siguientes líneas de código y reemplace el nombre del servidor o la base de datos por su nombre del servidor o la base de datos.

   ds.setServerName("msentra-managed-demo.database.windows.net"); // replace 'msentra-managed-demo' with your server name
   ds.setDatabaseName("demo"); // replace with your database name
   

3. Busque las siguientes líneas de código. Reemplaza el nombre del usuario por el nombre del usuario de Microsoft Entra que quieras que aparezca cuando te conectes.

   ds.setUser("bob@example.com"); // replace with your username
   ds.setPassword("password");     // replace with your password
   

El ejemplo para usar el modo de autenticación ActiveDirectoryPassword:

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;

import com.microsoft.sqlserver.jdbc.SQLServerDataSource;

public class MSEntraUserPassword {

    public static void main(String[] args) throws Exception{

        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replace with your server name
        ds.setDatabaseName("demo"); // Replace with your database
        ds.setUser("bob@example.com"); // Replace with your username
        ds.setPassword("password"); // Replace with your password
        ds.setAuthentication("ActiveDirectoryPassword");

        try (Connection connection = ds.getConnection();
                Statement stmt = connection.createStatement();
                ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

Si se establece una conexión, debería ver el mensaje siguiente como resultado:

You have successfully logged on as: <your user name>

Conexión con el modo de autenticación ActiveDirectoryInteractive

En el siguiente ejemplo se muestra cómo usar el modo authentication=ActiveDirectoryInteractive.

Para compilar y ejecutar el ejemplo:

1. Asegúrese de que ha requerido bibliotecas dependientes de los requisitos de configuración del cliente.

2. Busque las siguientes líneas de código y reemplace el nombre del servidor o la base de datos por su nombre del servidor o la base de datos.

   ds.setServerName("msentra-managed-demo.database.windows.net"); // replace 'msentra-managed-demo' with your server name
   ds.setDatabaseName("demo"); // replace with your database name
   

3. Busque las siguientes líneas de código. Reemplace el nombre del usuario por el nombre del usuario de Microsoft Entra que quieras que aparezca cuando te conectes.

   ds.setUser("bob@example.com"); // replace with your username
   

El ejemplo para usar el modo de autenticación ActiveDirectoryInteractive:

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;

import com.microsoft.sqlserver.jdbc.SQLServerDataSource;

public class MSEntraInteractive {
    public static void main(String[] args) throws Exception{

        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replace with your server name
        ds.setDatabaseName("demo"); // Replace with your database
        ds.setAuthentication("ActiveDirectoryInteractive");

        // Optional login hint
        ds.setUser("bob@example.com"); // Replace with your user name

        try (Connection connection = ds.getConnection();
                Statement stmt = connection.createStatement();
                ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

Al ejecutar el programa, se mostrará un explorador para autenticar el usuario. Lo que vea exactamente depende de cómo haya configurado su instancia de Microsoft Entra ID. Es posible que incluya o no mensajes de autenticación multifactor para el nombre de usuario, la contraseña, el PIN o la segunda autenticación de dispositivo a través de un teléfono. Si se realizan varias solicitudes de autenticación interactiva en el mismo programa, es posible que las solicitudes posteriores no se le envíen a usted si la biblioteca de autenticación puede volver a usar un token de autenticación previamente almacenado en caché.

Para información sobre cómo configurar Microsoft Entra ID para solicitar la autenticación multifactor, consulte Introducción a la autenticación multifactor de Microsoft Entra en la nube.

Para ver capturas de pantalla de estos cuadros de diálogo, consulte Uso de la autenticación multifactor de Microsoft Entra.

Si la autenticación del usuario se completa correctamente, debería ver el siguiente mensaje en el explorador:

Authentication complete. You can close the browser and return to the application.

Este mensaje solo indica que la autenticación del usuario se ha realizado de forma correcta, y no implica necesariamente una conexión correcta con el servidor. Al volver a la aplicación, si se ha establecido una conexión con el servidor, debería ver el siguiente mensaje como salida:

You have successfully logged on as: <your user name>

Conexión con el modo de autenticación ActiveDirectoryServicePrincipal

En el siguiente ejemplo se muestra cómo usar el modo authentication=ActiveDirectoryServicePrincipal.

Para compilar y ejecutar el ejemplo:

1. Asegúrese de que ha requerido bibliotecas dependientes de los requisitos de configuración del cliente.

2. Busque las siguientes líneas de código y reemplace el nombre del servidor o la base de datos por su nombre del servidor o la base de datos.

   ds.setServerName("msentra-managed-demo.database.windows.net"); // replace 'msentra-managed-demo' with your server name
   ds.setDatabaseName("demo"); // replace with your database name
   

3. Busque las siguientes líneas de código. Reemplaza el valor de principalId por el Id. de aplicación o de cliente de la entidad de servicio de Microsoft Entra que quieras que aparezca cuando te conectes. Reemplace el valor de principalSecret por el secreto.

   String principalId = "<service_principal_guid>"; // Replace with your Microsoft Entra service principal ID.
   String principalSecret = "..."; // Replace with your Microsoft Entra principal secret.
   

4. Establezca el ID y el secreto de la entidad de seguridad usando setUser y setPassword en la versión 10.2 y posteriores, y setAADSecurePrincipalId y setAADSecurePrincipalSecret en la versión 9.4 y anteriores.

El ejemplo para usar el modo de autenticación ActiveDirectoryServicePrincipal:

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;

import com.microsoft.sqlserver.jdbc.SQLServerDataSource;

public class MSEntraServicePrincipal {
    public static void main(String[] args) throws Exception{
        String principalId = "<service_principal_guid>"; // Replace with your Microsoft Entra service principal ID.
        String principalSecret = "..."; // Replace with your Microsoft Entra principal secret.

        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replace with your server name
        ds.setDatabaseName("demo"); // Replace with your database
        ds.setAuthentication("ActiveDirectoryServicePrincipal");
        ds.setUser(principalId); // setAADSecurePrincipalId for JDBC Driver 9.4 and below
        ds.setPassword(principalSecret); // setAADSecurePrincipalSecret for JDBC Driver 9.4 and below 

        try (Connection connection = ds.getConnection();
                Statement stmt = connection.createStatement();
                ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

Si se establece una conexión, debería ver el siguiente mensaje como resultado:

You have successfully logged on as: <your app/client ID>

Conexión con el modo de autenticación ActiveDirectoryServicePrincipalCertificate

En el siguiente ejemplo se muestra cómo usar el modo authentication=ActiveDirectoryServicePrincipalCertificate.

Para compilar y ejecutar el ejemplo:

1. Asegúrese de que ha requerido bibliotecas dependientes de los requisitos de configuración del cliente.

2. Busque las siguientes líneas de código y reemplace el nombre del servidor o la base de datos por su nombre del servidor o la base de datos.

   ds.setServerName("msentra-managed-demo.database.windows.net"); // replace 'msentra-managed-demo' with your server name
   ds.setDatabaseName("demo"); // replace with your database name
   

3. Busque las siguientes líneas de código. Reemplaza el valor de principalId por el Id. de aplicación o de cliente de la entidad de servicio de Microsoft Entra que quieras que aparezca cuando te conectes. Reemplaza el valor de clientCertificate por la ubicación del certificado de entidad de servicio.

   String principalId = "<service_principal_guid>"; // Replace with your Microsoft Entra service principal ID.
   
   String clientCertificate = "..."; // Replace with the location for your Microsoft Entra service principal certificate.
   

4. Si el certificado mencionado previamente necesita una contraseña, establezca el secreto principal con setPassword en la versión 10.2 o superior o setAADSecurePrincipalSecret en la versión 9.4 y posteriores.

5. Si el certificado tiene una clave privada asociada, establezca la clave privada con setClientKey. Si esta clave requiere una contraseña, establezca la contraseña para la clave privada con setClientKeyPassword.

El ejemplo para usar el modo de autenticación ActiveDirectoryServicePrincipalCertificate:

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;

import com.microsoft.sqlserver.jdbc.SQLServerDataSource;

public class MSEntraServicePrincipalCertificate {
    public static void main(String[] args) throws Exception{
        String principalId = "<service_principal_guid>"; // Replace with your Microsoft Entra service principal ID.
        String clientCertificate = "..."; // Replace with the location of your service principal certificate.

        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replace with your server name
        ds.setDatabaseName("demo"); // Replace with your database
        ds.setAuthentication("ActiveDirectoryServicePrincipalCertificate");
        ds.setUser(principalId); // setAADSecurePrincipalId for JDBC Driver 9.4 and below
        ds.setClientCertificate(clientCertificate);

        try (Connection connection = ds.getConnection();
             Statement stmt = connection.createStatement();
             ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

Si se establece una conexión, debería ver el siguiente mensaje como resultado:

You have successfully logged on as: <your app/client ID>

Conectar con un token de acceso

Las aplicaciones o servicios pueden recuperar un token de acceso de Microsoft Entra ID y usarlo para conectarse a labase de datos de Azure SQL, Azure SQL Managed Instance o Azure Synapse Analytics.

Nota:

Solo se puede establecer accessToken mediante el parámetro Properties del método getConnection() en la clase DriverManager. No se puede usar en la cadena de conexión. A partir de la versión 12.2 del controlador, los usuarios pueden implementar y proporcionar una devolución de llamada al controlador para la renovación de tokens en escenarios de agrupación de conexiones. Los escenarios de agrupación de conexiones requieren la implementación del grupo de conexiones para usar las clases de agrupación de conexiones JDBC estándar.

En el siguiente ejemplo se incluye una aplicación Java sencilla que se conecta a Azure mediante la autenticación basada en tokens de acceso.

Para compilar y ejecutar el ejemplo:

1. Crea una cuenta de aplicación en Microsoft Entra ID para tu servicio.

   1. Inicie sesión en Azure Portal.
   2. Selecciona Microsoft Entra ID en la barra de navegación izquierda.
   3. Seleccione App registrations (Registros de aplicaciones).
   4. Seleccione Nuevo registro.
   5. Escribe mytokentest como nombre descriptivo para la aplicación.
   6. Deje la selección predeterminada para los tipos de cuenta admitidos que pueden usar la aplicación.
   7. Selecciona Registrar en la parte inferior.
   8. No es necesaria la URL DE INICIO DE SESIÓN. Proporcione cualquier cosa: https://mytokentest.
   9. Seleccione Create en la parte inferior.
   10. Al seleccionar Registrarse, la aplicación se crea inmediatamente y se lo lleva a su página de recursos.
   11. En el cuadro Essentials, busca el Id. de aplicación (cliente) y cópialo. Necesitarás este valor más adelante para configurar tu aplicación.
   12. Seleccione Certificados y secretos en el panel de navegación. En la pestaña Secretos de cliente (0), selecciona Nuevo secreto de cliente. Escribe una descripción para el secreto de cliente selecciona una expiración (la predeterminada valdría). Selecciona Agregar en la parte inferior. Importante antes de salir de esta página, copia el valor generado para el secreto de cliente. Este valor no se puede visualizar después de salir de la página. Este valor es el secreto de cliente.
   13. Vuelva al panel Registros de aplicaciones de Microsoft Entra ID y busque la pestaña Punto de conexión. Copie la dirección URL en OAuth 2.0 token endpoint. Esta dirección URL es su dirección URL de STS.

   

2. Conéctate a la base de datos como administrador de Microsoft Entra y usa un comando T-SQL para aprovisionar un usuario de base de datos independiente para la entidad de seguridad de la aplicación. Para obtener más información sobre cómo crear un administrador de Microsoft Entra y un usuario de base de datos independiente, consulta Conexión mediante la autenticación de Microsoft Entra.

   CREATE USER [mytokentest] FROM EXTERNAL PROVIDER
   

3. En la máquina cliente en la que ejecute el ejemplo, descargue la biblioteca Microsoft Authentication Library (MSAL) para Java y sus dependencias. MSAL solo es necesario para ejecutar este ejemplo específico. En el ejemplo se usan las API de esta biblioteca para recuperar el token de acceso de Microsoft Entra ID. Si ya tiene un token de acceso, puede omitir este paso y quitar la sección del ejemplo que recupera un token de acceso.

En el siguiente ejemplo, reemplace la dirección URL de STS, el identificador de cliente, el secreto de cliente, el servidor y el nombre de base de datos por sus valores.

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;
import java.util.concurrent.Executors;
import java.util.concurrent.Future;
import com.microsoft.sqlserver.jdbc.SQLServerDataSource;

// The microsoft-authentication-library-for-java is needed to retrieve the access token in this example.
import com.microsoft.aad.msal4j.ClientCredentialFactory;
import com.microsoft.aad.msal4j.ClientCredentialParameters;
import com.microsoft.aad.msal4j.ConfidentialClientApplication;
import com.microsoft.aad.msal4j.IAuthenticationResult;
import com.microsoft.aad.msal4j.IClientCredential;

public class MSEntraTokenBased {

    public static void main(String[] args) throws Exception {

        // Retrieve the access token from Microsoft Entra ID.
        String spn = "https://database.windows.net/";
        String stsurl = "https://login.microsoftonline.com/..."; // Replace with your STS URL.
        String clientId = "<service_principal_guid>"; // Replace with your client ID.
        String clientSecret = "..."; // Replace with your client secret.

        String scope = spn +  "/.default";
        Set<String> scopes = new HashSet<>();
        scopes.add(scope);

        ExecutorService executorService = Executors.newSingleThreadExecutor();
        IClientCredential credential = ClientCredentialFactory.createFromSecret(clientSecret);
        ConfidentialClientApplication clientApplication = ConfidentialClientApplication
            .builder(clientId, credential).executorService(executorService).authority(stsurl).build();
        CompletableFuture<IAuthenticationResult> future = clientApplication
            .acquireToken(ClientCredentialParameters.builder(scopes).build());

        IAuthenticationResult authenticationResult = future.get();
        String accessToken = authenticationResult.accessToken();

        System.out.println("Access Token: " + accessToken);

        // Connect with the access token.
        SQLServerDataSource ds = new SQLServerDataSource();

        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replace with your server name.
        ds.setDatabaseName("demo"); // Replace with your database name.
        ds.setAccessToken(accessToken);

        try (Connection connection = ds.getConnection();
                Statement stmt = connection.createStatement();
                ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

Si la conexión se realiza correctamente, debería ver el siguiente mensaje como resultado:

Access Token: <your access token>
You have successfully logged on as: <your client ID>

Conectar con una devolución de llamada de token de acceso

Al igual que la propiedad de token de acceso, la devolución de llamada de token de acceso permite registrar un método que proporcionará un token de acceso al controlador. La ventaja de esta devolución de llamada sobre la propiedad es que la devolución de llamada permite al controlador solicitar un nuevo token de acceso cuando el token ha expirado. Por ejemplo, un grupo de conexiones que crea una nueva conexión puede solicitar un nuevo token con una nueva fecha de expiración. Para obtener más información, consulte Usar agrupación de conexiones.

En el ejemplo siguiente se muestra cómo implementar y establecer la devolución de llamada de token de acceso.

import com.microsoft.aad.msal4j.IClientCredential;
import com.microsoft.aad.msal4j.ClientCredentialFactory;
import com.microsoft.aad.msal4j.ConfidentialClientApplication;
import com.microsoft.aad.msal4j.IAuthenticationResult;
import com.microsoft.aad.msal4j.ClientCredentialParameters;
import java.sql.Connection;
import java.util.HashSet;
import java.util.Set;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

public class MSEntraAccessTokenCallback {

    public static void main(String[] args) {

        SQLServerAccessTokenCallback callback = new SQLServerAccessTokenCallback() {
            @Override
            public SqlAuthenticationToken getAccessToken(String spn, String stsurl) {

                String clientSecret = "..."; // Replace with your client secret.
                String clientId = "<service_principal_guid>"; // Replace with your client ID.

                String scope = spn + "/.default";
                Set<String> scopes = new HashSet<>();
                scopes.add(scope);

                try {
                    ExecutorService executorService = Executors.newSingleThreadExecutor();
                    IClientCredential credential = ClientCredentialFactory.createFromSecret(clientSecret);
                    ConfidentialClientApplication clientApplication = ConfidentialClientApplication
                            .builder(clientId, credential).executorService(executorService).authority(stsurl).build();
                    CompletableFuture<IAuthenticationResult> future = clientApplication
                            .acquireToken(ClientCredentialParameters.builder(scopes).build());

                    IAuthenticationResult authenticationResult = future.get();
                    String accessToken = authenticationResult.accessToken();

                    return new SqlAuthenticationToken(accessToken, authenticationResult.expiresOnDate().getTime());
                } catch (Exception e) {
                    e.printStackTrace();
                }
                return null;
            }
        };

        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replaces with your server name.
        ds.setDatabaseName("demo"); // Replace with your database name.
        ds.setAccessTokenCallback(callback);

        try (Connection connection = ds.getConnection();
                Statement stmt = connection.createStatement();
                ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

Si la conexión se realiza correctamente, debería ver el siguiente mensaje como resultado:

You have successfully logged on as: <your client ID>

A partir de la versión 12 4, la devolución de llamada accessToken se puede establecer mediante la propiedad de cadena de conexión accessTokenCallbackClass. En el ejemplo siguiente se muestra cómo establecer la devolución de llamada accessToken con esta propiedad:

import com.microsoft.aad.msal4j.IClientCredential;
import com.microsoft.aad.msal4j.ClientCredentialFactory;
import com.microsoft.aad.msal4j.ConfidentialClientApplication;
import com.microsoft.aad.msal4j.IAuthenticationResult;
import com.microsoft.aad.msal4j.ClientCredentialParameters;
import java.sql.Connection;
import java.util.HashSet;
import java.util.Set;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

 

public class MSEntraAccessTokenCallbackClass {
    public static class AccessTokenCallbackClass implements SQLServerAccessTokenCallback {
        @Override
        public SqlAuthenticationToken getAccessToken(String spn, String stsurl) {
            String clientSecret = "..."; // Replace with your client secret.
            String clientId = "<service_principal_guid>"; // Replace with your client ID.
            
            String scope = spn + "/.default";
            Set<String> scopes = new HashSet<>();
            scopes.add(scope);
            
            try {
                ExecutorService executorService = Executors.newSingleThreadExecutor();
                IClientCredential credential = ClientCredentialFactory.createFromSecret(clientSecret);
                ConfidentialClientApplication clientApplication = ConfidentialClientApplication

                        .builder(clientId, credential).executorService(executorService).authority(stsurl).build();
                
                CompletableFuture<IAuthenticationResult> future = clientApplication
                        .acquireToken(ClientCredentialParameters.builder(scopes).build());
                
                IAuthenticationResult authenticationResult = future.get();
                String accessToken = authenticationResult.accessToken();
                
                return new SqlAuthenticationToken(accessToken, authenticationResult.expiresOnDate().getTime());
            } catch (Exception e) {
                e.printStackTrace();
            }
            return null;
        }
    }
    
    public static void main(String[] args) throws Exception {
        
        SQLServerDataSource ds = new SQLServerDataSource();
        ds.setServerName("msentra-managed-demo.database.windows.net"); // Replaces with your server name.
        ds.setDatabaseName("demo"); // Replace with your database name.
        ds.setAccessTokenCallbackClass(AccessTokenCallbackClass.class.getName());
        
        try (Connection connection = ds.getConnection();
             Statement stmt = connection.createStatement();
             ResultSet rs = stmt.executeQuery("SELECT SUSER_SNAME()")) {
            if (rs.next()) {
                System.out.println("You have successfully logged on as: " + rs.getString(1));
            }
        }
    }
}

Si la conexión se realiza correctamente, debería ver el siguiente mensaje como resultado:

You have successfully logged on as: <your client ID>

Pasos siguientes

Obtenga más información sobre los conceptos relacionados en los artículos siguientes:

• Conexión a Azure SQL mediante la autenticación de Microsoft Entra
• Biblioteca de autenticación de Microsoft (MSAL) para Java
• Biblioteca de autenticación de Microsoft Azure Active Directory (ADAL) para Java
• Solución de problemas de conexión comunes relacionados con Azure SQL Database