Compartir vía

Habilitación del inicio de sesión para aplicaciones de Java Tomcat con el identificador de Microsoft Entra

  • Artículo

En este artículo se muestra una aplicación de Java Tomcat que inicia sesión de los usuarios en el inquilino de Microsoft Entra ID mediante la Biblioteca de autenticación de Microsoft (MSAL) para Java.

En el diagrama siguiente se muestra la topología de la aplicación:

Diagrama que muestra la topología de la aplicación.

La aplicación cliente usa MSAL para Java (MSAL4J) para iniciar sesión de los usuarios en su propio inquilino de Microsoft Entra ID y obtener un token de identificador de Microsoft Entra ID. El token de identificador demuestra que un usuario se autentica con este inquilino. La aplicación protege sus rutas según el estado de autenticación del usuario.

Requisitos previos

  • JDK versión 8 o posterior
  • Maven 3
  • Un inquilino de Microsoft Entra ID. Para obtener más información, consulte Cómo obtener un inquilino de Microsoft Entra ID.
  • Una cuenta de usuario en su propio inquilino de Id. de Microsoft Entra si desea trabajar solo con cuentas en el directorio organizativo, es decir, en modo de inquilino único. Si no ha creado una cuenta de usuario en el inquilino de Id. de Microsoft Entra, debe hacerlo antes de continuar. Para obtener más información, consulte Creación, invitación y eliminación de usuarios.
  • Una cuenta de usuario en el inquilino de Microsoft Entra ID de cualquier organización si desea trabajar con cuentas en cualquier directorio organizativo, es decir, en modo multiinquilino. Debe modificar este ejemplo para trabajar con una cuenta microsoft personal. Si aún no ha creado una cuenta de usuario en el inquilino de Microsoft Entra ID, debe hacerlo antes de continuar. Para obtener más información, consulte Creación, invitación y eliminación de usuarios.
  • Una cuenta microsoft personal ( por ejemplo, Xbox, Hotmail, Live, etc.) si desea trabajar con cuentas personales de Microsoft.

Recomendaciones

  • Cierta familiaridad con los Servlets de Java /Jakarta.
  • Cierta familiaridad con el terminal Linux/OSX o Windows PowerShell.
  • jwt.ms para inspeccionar los tokens.
  • Fiddler para supervisar la actividad de red y la solución de problemas.
  • Siga el blog de Microsoft Entra ID para mantenerse al día con los últimos desarrollos.

Configuración del ejemplo

En las secciones siguientes se muestra cómo configurar la aplicación de ejemplo.

Clonar o descargar el repositorio de ejemplo

Para clonar el ejemplo, abra una ventana de Bash y use el siguiente comando:

git clone https://github.com/Azure-Samples/ms-identity-msal-java-samples.git
cd 3-java-servlet-web-app/1-Authentication/sign-in

Como alternativa, vaya al repositorio ms-identity-msal-java-samples y, a continuación, descárguelo como un archivo .zip y extráigalo en el disco duro.

Importante

Para evitar limitaciones de longitud de ruta de acceso de archivo en Windows, clone o extraiga el repositorio en un directorio cerca de la raíz del disco duro.

Registro de la aplicación de ejemplo con el inquilino de Microsoft Entra ID

Hay un proyecto en este ejemplo. En esta sección se muestra cómo registrar la aplicación.

En primer lugar, registre la aplicación en Azure Portal siguiendo las instrucciones de Inicio rápido: Registro de una aplicación con el Plataforma de identidad de Microsoft.

A continuación, siga estos pasos para completar el registro:

  1. Vaya a la página de Registros de aplicaciones de la plataforma de identidad de Microsoft para desarrolladores.

  2. Seleccione Nuevo registro.

  3. En la página Registrar una aplicación que aparece, escriba la siguiente información de registro de aplicación:

    • En la sección Nombre , escriba un nombre de aplicación significativo para mostrar a los usuarios de la aplicación; por ejemplo, java-servlet-webapp-authentication.

    • En Tipos de cuenta admitidos, seleccione una de las siguientes opciones:

      • Seleccione Cuentas en este directorio organizativo solo si va a compilar una aplicación solo para que la usen los usuarios del inquilino, es decir, una aplicación de un solo inquilino .
      • Seleccione Cuentas en cualquier directorio organizativo si desea que los usuarios de cualquier inquilino de Id. de Microsoft Entra puedan usar la aplicación, es decir, una aplicación multiinquilino .
      • Seleccione Cuentas en cualquier directorio organizativo y cuentas personales de Microsoft para el conjunto más amplio de clientes, es decir, una aplicación multiinquilino que también admita cuentas personales de Microsoft.
      • Seleccione Cuentas personales de Microsoft para que solo las usen los usuarios de cuentas personales de Microsoft( por ejemplo, Hotmail, Live, Skype y Xbox).

    • En la sección URI de redirección, seleccione Web en el cuadro combinado y escriba el siguiente URI de redirección: http://localhost:8080/msal4j-servlet-auth/auth/redirect.

  4. Seleccione Registrar para crear la aplicación.

  5. En la página de registro de la aplicación, busque y copie el valor de id. de aplicación (cliente) para usarlo más adelante. Este valor se usa en el archivo o archivos de configuración de la aplicación.

  6. En la página de registro de la aplicación, seleccione Certificados y secretos en el panel de navegación para abrir la página para generar secretos y cargar certificados.

  7. En la sección Secretos de cliente, seleccione Nuevo secreto de cliente.

  8. Escriba una descripción, por ejemplo, secreto de aplicación.

  9. Seleccione una de las duraciones disponibles: En 1 año, En 2 años o Nunca expira.

  10. Seleccione Agregar. Se muestra el valor generado.

  11. Copie y guarde el valor generado para usarlo en pasos posteriores. Necesita este valor para los archivos de configuración del código. Este valor no se muestra de nuevo y no se puede recuperar por ningún otro medio. Por lo tanto, asegúrese de guardarlo desde Azure Portal antes de navegar a cualquier otra pantalla o panel.

Configuración de la aplicación para usar el registro de la aplicación

Siga estos pasos para configurar la aplicación:

Nota:

En los pasos siguientes, ClientID es igual Application ID que o AppId.

  1. Abra el proyecto en el IDE.

  2. Abra el archivo ./src/main/resources/authentication.properties .

  3. Busque la cadena {enter-your-tenant-id-here}. Reemplace el valor existente por uno de los siguientes valores:

    • El identificador de inquilino de Id. de Microsoft Entra si registró la aplicación con la opción Cuentas de este directorio organizativo.
    • organizations Palabra si registró la aplicación con la opción Cuentas en cualquier directorio organizativo.
    • common Palabra si registró la aplicación con la opción Cuentas en cualquier directorio organizativo y cuentas microsoft personales.
    • Palabra consumers si registró la aplicación con la opción Cuentas personales de Microsoft .

  4. Busque la cadena {enter-your-client-id-here} y reemplace el valor existente por el identificador de aplicación o clientId de la java-servlet-webapp-authentication aplicación copiada de Azure Portal.

  5. Busque la cadena {enter-your-client-secret-here} y reemplace el valor existente por el valor que guardó durante la creación de la java-servlet-webapp-authentication aplicación, en Azure Portal.

Compilación del ejemplo

Para compilar el ejemplo mediante Maven, vaya al directorio que contiene el archivo pom.xml del ejemplo y, a continuación, ejecute el siguiente comando:

mvn clean package

Este comando genera un archivo .war que se puede ejecutar en varios servidores de aplicaciones.

Ejecución del ejemplo

En las secciones siguientes se muestra cómo implementar el ejemplo en App de Azure Service.

Requisitos previos

Configuración del complemento Maven

Al implementar en App de Azure Service, la implementación usa automáticamente las credenciales de Azure desde la CLI de Azure. El complemento Maven se autentica con OAuth o el inicio de sesión del dispositivo si la CLI de Azure no está instalada localmente. Para más información, consulte Autenticación con los complementos de Maven.

Siga estos pasos para configurar el complemento:

  1. Ejecute el comando siguiente para configurar la implementación. Este comando le ayuda a configurar el sistema operativo App de Azure Service, la versión de Java y la versión de Tomcat.

    mvn com.microsoft.azure:azure-webapp-maven-plugin:2.12.0:config

  2. En Crear nueva configuración de ejecución, presione Y y, a continuación, presione Entrar.

  3. En Definir valor para sistema operativo, presione 1 para Windows o 2 para Linux y, a continuación, presione Entrar.

  4. En Definir valor para javaVersion, presione 2 para Java 11 y, a continuación, presione Entrar.

  5. En Definir valor para webContainer, presione 4 para Tomcat 9.0 y, a continuación, presione Entrar.

  6. En Definir valor para pricingTier, presione Entrar para seleccionar el nivel P1v2 predeterminado.

  7. En Confirmar, presione Y y, a continuación, presione Entrar.

En el ejemplo siguiente se muestra la salida del proceso de implementación:

Please confirm webapp properties
AppName : msal4j-servlet-auth-1707209552268
ResourceGroup : msal4j-servlet-auth-1707209552268-rg
Region : centralus
PricingTier : P1v2
OS : Linux
Java Version: Java 11
Web server stack: Tomcat 9.0
Deploy to slot : false
Confirm (Y/N) [Y]: [INFO] Saving configuration to pom.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  37.112 s
[INFO] Finished at: 2024-02-06T08:53:02Z
[INFO] ------------------------------------------------------------------------

Después de confirmar las opciones, el complemento agrega el elemento de complemento y la configuración necesarios al archivo pom.xml del proyecto para configurar la aplicación para que se ejecute en App de Azure Service.

La parte pertinente del archivo pom.xml debe ser similar al ejemplo siguiente:

<build>
    <plugins>
        <plugin>
            <groupId>com.microsoft.azure</groupId>
            <artifactId>>azure-webapp-maven-plugin</artifactId>
            <version>x.xx.x</version>
            <configuration>
                <schemaVersion>v2</schemaVersion>
                <resourceGroup>your-resourcegroup-name</resourceGroup>
                <appName>your-app-name</appName>
            ...
            </configuration>
        </plugin>
    </plugins>
</build>

Puede modificar las configuraciones de App Service directamente en la pom.xml. Algunas configuraciones comunes se enumeran en la tabla siguiente:

Propiedad Obligatorio Descripción
subscriptionId false Identificador de la suscripción.
resourceGroup true El grupo de recursos de Azure para la aplicación.
appName true Nombre de la aplicación.
region false Región en la que se va a hospedar la aplicación. El valor predeterminado es centralus. Para ver las regiones válidas, consulte Regiones admitidas.
pricingTier false Plan de tarifa de la aplicación. El valor predeterminado es P1v2 para una carga de trabajo de producción. El valor mínimo recomendado para desarrollo y pruebas de Java es B2. Para más información, consulte Precios de App Service.
runtime false Configuración del entorno en runtime. Para obtener más información, consulte Detalles de configuración.
deployment false Configuración de implementación. Para obtener más información, consulte Detalles de configuración.

Para obtener la lista completa de configuraciones, consulte la documentación de referencia del complemento. Todos los complementos de Azure Maven comparten un conjunto común de configuraciones. Para estas configuraciones, consulte Configuraciones comunes. Para conocer las configuraciones específicas de App de Azure Service, consulte Aplicación de Azure: Detalles de configuración.

Asegúrese de guardar los appName valores y resourceGroup para su uso posterior.

Preparación de la aplicación para la implementación

Al implementar la aplicación en App Service, la dirección URL de redireccionamiento cambia a la dirección URL de redireccionamiento de la instancia de aplicación implementada. Siga estos pasos para cambiar esta configuración en el archivo de propiedades:

  1. Vaya al archivo authentication.properties de la aplicación y cambie el valor de por el nombre de dominio de app.homePage la aplicación implementada, como se muestra en el ejemplo siguiente. Por ejemplo, si eligió example-domain para el nombre de la aplicación en el paso anterior, ahora debe usar https://example-domain.azurewebsites.net para el app.homePage valor . Asegúrese de que también ha cambiado el protocolo de http a https.

    # app.homePage is by default set to dev server address and app context path on the server
# for apps deployed to azure, use https://your-sub-domain.azurewebsites.net
app.homePage=https://<your-app-name>.azurewebsites.net

  2. Después de guardar este archivo, use el siguiente comando para volver a generar la aplicación:

    mvn clean package

Importante

En este mismo archivo authentication.properties , tiene una configuración para aad.secret. No es recomendable implementar este valor en App Service. Tampoco es un procedimiento recomendado dejar este valor en el código y potencialmente insertarlo en el repositorio de Git. Para quitar este valor de secreto del código, puede encontrar instrucciones más detalladas en la sección Deploy to App Service - Remove secret (Implementar en App Service: quitar secreto ). En esta guía se agregan pasos adicionales para insertar el valor del secreto en Key Vault y usar referencias de Key Vault.

Actualización del registro de la aplicación microsoft Entra ID

Dado que el URI de redirección cambia a la aplicación implementada en App de Azure Service, también debe cambiar el URI de redirección en el registro de la aplicación de Id. de Microsoft Entra. Para realizar este cambio, siga estos pasos:

  1. Vaya a la página de Registros de aplicaciones de la plataforma de identidad de Microsoft para desarrolladores.

  2. Use el cuadro de búsqueda para buscar el registro de la aplicación; por ejemplo, java-servlet-webapp-authentication.

  3. Para abrir el registro de la aplicación, seleccione su nombre.

  4. Seleccione Autenticar desde el menú.

  5. En la sección URI de redirección web - , seleccione Agregar URI.

  6. Rellene el URI de la aplicación, anexando /auth/redirect , por ejemplo, https://<your-app-name>.azurewebsites.net/auth/redirect.

  7. Seleccione Guardar.

Implementar la aplicación

Ya está listo para implementar la aplicación en App de Azure Service. Use el comando siguiente para asegurarse de que ha iniciado sesión en el entorno de Azure para ejecutar la implementación:

az login

Con toda la configuración lista en el archivo pom.xml, ahora puede usar el siguiente comando para implementar la aplicación Java en Azure:

mvn package azure-webapp:deploy

Una vez completada la implementación, la aplicación está lista en http://<your-app-name>.azurewebsites.net/. Abra la dirección URL con el explorador web local, donde debería ver la página de inicio de la msal4j-servlet-auth aplicación.

Exploración del ejemplo

Siga estos pasos para explorar el ejemplo:

  1. Observe que el estado de inicio de sesión o de cierre de sesión se muestra en el centro de la pantalla.
  2. Seleccione el botón contextual en la esquina. Este botón lee Iniciar sesión cuando se ejecuta por primera vez la aplicación.
  3. En la página siguiente, siga las instrucciones e inicie sesión con una cuenta en el inquilino de Microsoft Entra ID.
  4. En la pantalla de consentimiento, observe los ámbitos que se solicitan.
  5. Observe que el botón contextual ahora indica Cerrar sesión y muestra el nombre de usuario.
  6. Seleccione Id. Token Details (Detalles del token de identificador) para ver algunas de las notificaciones descodificadas del token de identificador.
  7. Use el botón de la esquina para cerrar la sesión.
  8. Después de cerrar sesión, seleccione Id. Token Details (Detalles del token de identificador) para observar que la aplicación muestra un 401: unauthorized error en lugar de las notificaciones del token de identificador cuando el usuario no está autorizado.

Sobre el código

En este ejemplo se muestra cómo usar MSAL para Java (MSAL4J) para iniciar sesión de los usuarios en el inquilino de Id. de Microsoft Entra. Si quiere usar MSAL4J en sus propias aplicaciones, debe agregarlo a los proyectos mediante Maven.

Si desea replicar el comportamiento de este ejemplo, puede copiar el archivo pom.xml y el contenido de las carpetas auxiliares y authservlets en la carpeta src/main/java/com/microsoft/azuresamples/msal4j. También necesita el archivo authentication.properties . Estas clases y archivos contienen código genérico que puede usar en una amplia gama de aplicaciones. También puede copiar el resto del ejemplo, pero las demás clases y archivos se compilan específicamente para abordar el objetivo de este ejemplo.

Contenido

En la tabla siguiente se muestra el contenido de la carpeta del proyecto de ejemplo:

Archivo/carpeta Descripción
src/main/java/com/microsoft/azuresamples/msal4j/authwebapp/ Este directorio contiene las clases que definen la lógica empresarial de back-end de la aplicación.
src/main/java/com/microsoft/azuresamples/msal4j/authservlets/ Este directorio contiene las clases que se usan para los puntos de conexión de inicio de sesión y cierre de sesión.
____Servlet.java Todos los puntos de conexión disponibles se definen en .java clases que terminan en ____Servlet.java.
src/main/java/com/microsoft/azuresamples/msal4j/helpers/ Clases auxiliares para la autenticación.
AuthenticationFilter.java Redirige las solicitudes no autenticadas a los puntos de conexión protegidos a una página 401.
src/main/resources/authentication.properties Microsoft Entra ID y configuración del programa.
src/main/webapp/ Este directorio contiene la interfaz de usuario: plantillas de JSP
CHANGELOG.md Lista de cambios en el ejemplo.
CONTRIBUTING.md Directrices para contribuir al ejemplo.
LICENCIA Licencia del ejemplo.

ConfidentialClientApplication

Se crea una ConfidentialClientApplication instancia en el archivo AuthHelper.java , como se muestra en el ejemplo siguiente. Este objeto ayuda a crear la dirección URL de autorización del identificador de Entra de Microsoft y también ayuda a intercambiar el token de autenticación de un token de acceso.

// getConfidentialClientInstance method
IClientSecret secret = ClientCredentialFactory.createFromSecret(SECRET);
confClientInstance = ConfidentialClientApplication
                     .builder(CLIENT_ID, secret)
                     .authority(AUTHORITY)
                     .build();

Los parámetros siguientes se usan para crear instancias:

  • Identificador de cliente de la aplicación.
  • Secreto de cliente, que es un requisito para aplicaciones cliente confidenciales.
  • Microsoft Entra ID Authority, que incluye el identificador de inquilino de Microsoft Entra ID.

En este ejemplo, estos valores se leen del archivo authentication.properties mediante un lector de propiedades en el archivo Config.java .

Tutorial paso a paso

Los pasos siguientes proporcionan un tutorial de la funcionalidad de la aplicación:

  1. El primer paso del proceso de inicio de sesión es enviar una solicitud al /authorize punto de conexión del inquilino de Microsoft Entra ID. La instancia de MSAL4J ConfidentialClientApplication se usa para construir una dirección URL de solicitud de autorización. La aplicación redirige el explorador a esta dirección URL, que es donde el usuario inicia sesión.

    final ConfidentialClientApplication client = getConfidentialClientInstance();
AuthorizationRequestUrlParameters parameters = AuthorizationRequestUrlParameters.builder(Config.REDIRECT_URI, Collections.singleton(Config.SCOPES))
        .responseMode(ResponseMode.QUERY).prompt(Prompt.SELECT_ACCOUNT).state(state).nonce(nonce).build();

final String authorizeUrl = client.getAuthorizationRequestUrl(parameters).toString();
contextAdapter.redirectUser(authorizeUrl);

    En la lista siguiente se describen las características de este código:

    • AuthorizationRequestUrlParameters: parámetros que se deben establecer para compilar una authorizationRequestUrl.

    • REDIRECT_URI: donde Microsoft Entra ID redirige el explorador (junto con el código de autenticación) después de recopilar las credenciales de usuario. Debe coincidir con el URI de redireccionamiento en el registro de la aplicación de Id. de Microsoft Entra en Azure Portal.

    • SCOPES: los ámbitos son permisos solicitados por la aplicación. Normalmente, los tres ámbitos openid profile offline_access son suficientes para recibir una respuesta de token de identificador.

      Puede encontrar una lista completa de los ámbitos solicitados por la aplicación en el archivo authentication.properties . Puede agregar más ámbitos, como User.Read.

  2. Microsoft Entra ID presenta al usuario un mensaje de inicio de sesión. Si el intento de inicio de sesión se realiza correctamente, el explorador del usuario se redirige al punto de conexión de redireccionamiento de la aplicación. Una solicitud válida a este punto de conexión contiene un código de autorización.

  3. A continuación, la ConfidentialClientApplication instancia intercambia este código de autorización para un token de identificador y un token de acceso de Microsoft Entra ID.

    // First, validate the state, then parse any error codes in response, then extract the authCode. Then:
// build the auth code params:
final AuthorizationCodeParameters authParams = AuthorizationCodeParameters
        .builder(authCode, new URI(Config.REDIRECT_URI)).scopes(Collections.singleton(Config.SCOPES)).build();

// Get a client instance and leverage it to acquire the token:
final ConfidentialClientApplication client = AuthHelper.getConfidentialClientInstance();
final IAuthenticationResult result = client.acquireToken(authParams).get();

    En la lista siguiente se describen las características de este código:

    • AuthorizationCodeParameters: parámetros que se deben establecer para intercambiar el código de autorización de un identificador o token de acceso.
    • authCode: el código de autorización que se recibió en el punto de conexión de redireccionamiento.
    • REDIRECT_URI: el URI de redirección usado en el paso anterior debe pasarse de nuevo.
    • SCOPES: los ámbitos usados en el paso anterior deben pasarse de nuevo.

  4. Si acquireToken se realiza correctamente, se extraen las notificaciones de token. Si se supera la comprobación de nonce, los resultados se colocan en ( una instancia de IdentityContextData ) y se guardan en context la sesión. A continuación, la aplicación puede crear una instancia IdentityContextData de desde la sesión mediante una instancia de IdentityContextAdapterServlet siempre que necesite acceso a ella, como se muestra en el código siguiente:

    // parse IdToken claims from the IAuthenticationResult:
// (the next step - validateNonce - requires parsed claims)
context.setIdTokenClaims(result.idToken());

// if nonce is invalid, stop immediately! this could be a token replay!
// if validation fails, throws exception and cancels auth:
validateNonce(context);

// set user to authenticated:
context.setAuthResult(result, client.tokenCache().serialize());

Protección de las rutas

Para obtener información sobre cómo la aplicación de ejemplo filtra el acceso a las rutas, consulte AuthenticationFilter.java. En el archivo authentication.properties , la app.protect.authenticated propiedad contiene las rutas separadas por comas a las que solo pueden acceder los usuarios autenticados, como se muestra en el ejemplo siguiente:

# for example, /token_details requires any user to be signed in and does not require special roles claim(s)
app.protect.authenticated=/token_details

Ámbitos

Los ámbitos indican a Microsoft Entra ID el nivel de acceso que solicita la aplicación.

En función de los ámbitos solicitados, Microsoft Entra ID presenta un diálogo de consentimiento al usuario al iniciar sesión. Si el usuario da su consentimiento a uno o varios ámbitos y obtiene un token, los ámbitos con consentimiento se codifican en el objeto resultante access_token.

Para los ámbitos solicitados por la aplicación, consulte authentication.properties. MsAL solicita estos tres ámbitos y se proporcionan de forma predeterminada por el identificador de Entra de Microsoft.

Información adicional