Proteger las aplicaciones Quarkus con Microsoft Entra ID mediante OpenID Connect

Artículo
10/07/2024

Este artículo muestra cómo proteger las aplicaciones Red Hat Quarkus con Microsoft Entra ID mediante OpenID Connect (OIDC).

En este artículo aprenderá a:

Configure un proveedor OpenID Connect con Microsoft Entra ID.
Proteja una aplicación Quarkus mediante OpenID Connect.
Ejecute y pruebe la aplicación Quarkus.

Requisitos previos

Suscripción a Azure. Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.
Una identidad Azure con al menos el rol de Microsoft Entra de administrador de aplicaciones en la nube. Para obtener más información, consulte Enumeración de asignaciones de roles de Microsoft Entra y Roles integrados de Microsoft Entra.
Un inquilino de Microsoft Entra. Si no tiene un inquilino, consulte Inicio rápido: Configurar Configuración de un inquilino.
Una máquina local con un sistema operativo tipo Unix instalado, por ejemplo, Ubuntu, macOS o Windows Subsystem para Linux.
Git.
Una implementación de Java SE, versión 21 o posterior, por ejemplo, la compilación de Microsoft de OpenJDK.
Maven, versión 3.9.3 o superior.

Configuración de un proveedor OpenID Connect con Microsoft Entra ID

En esta sección, usted configura un proveedor OpenID Connect con Microsoft Entra ID para usarlo con su aplicación Quarkus. En una sección posterior, configurará la aplicación Quarkus usando OpenID Connect para autenticar y autorizar a los usuarios en su inquilino de Microsoft Entra.

Creación de usuarios en el inquilino de Microsoft Entra

En primer lugar, cree dos usuarios en su inquilino de Microsoft Entra siguiendo los pasos que se indican en Creación, invitación y eliminación de usuarios. Solo tiene que consultar la sección Creación de un nuevo usuario. Siga las instrucciones a medida que avanza por el artículo y vuelva a este artículo después de crear los usuarios en su inquilino de Microsoft Entra.

Para crear un usuario que actúe como "administrador" en la aplicación, siga estos pasos:

Cuando llegue a la pestaña Aspectos básicos en la sección Creación de un nuevo usuario, siga los pasos a continuación:
1. En Nombre principal de usuario, escriba admin. Guarde el valor para poder usarlo más tarde cuando inicie sesión en la aplicación.
2. En Alias de correo, seleccione Derivar del nombre principal de usuario
3. En Nombre para mostrar, escriba admin.
4. En Contraseña, seleccione Generar contraseña automáticamente. Copie y guarde el valor de Contraseña para usarlo más adelante cuando inicie sesión en la aplicación.
5. Seleccione Cuenta habilitada.
6. Seleccione Revisar y crear>Crear. Espere a que se cree el usuario.
7. Espere un minuto más o menos y seleccione Actualizar. Debería ver al nuevo usuario en la lista.

Para crear un usuario que actúe como "usuario" en la aplicación, repita los mismos pasos, pero use los siguientes valores:

En Nombre principal de usuario, escriba Usuario.
En Nombre para mostrar, escriba Usuario.

Registro de una aplicación en Microsoft Entra ID

A continuación, registre una aplicación siguiendo los pasos que se indican en Inicio rápido: Registro de una aplicación con la plataforma de identidad de Microsoft. Siga las instrucciones a medida que avanza por el artículo y vuelva a este artículo después de registrar y configurar la aplicación.

Cuando llegue a la sección Registrar una aplicación, siga los pasos a continuación:
1. En Tipos de cuenta admitidos, seleccione Cuentas de este directorio organizativo solo (Solo directorio predeterminado: inquilino único).
2. Cuando finalice el registro, guarde los valores de ID de aplicación (cliente) y ID de directorio (inquilino) para usarlos más adelante en la configuración de la aplicación.
Cuando llegue a la sección Agregar un URI de redireccionamiento, sáltese los pasos de momento. Agregará el URI de redireccionamiento más adelante en este artículo al ejecutar y probar la aplicación de ejemplo de forma local.
Cuando llegue a la sección Agregar credenciales, seleccione la pestaña Agregar un secreto de cliente.
Cuando agregue un secreto de cliente, anote el valor Secreto de cliente para usarlo más adelante en la configuración de la aplicación.

Incorporación de roles de aplicación a una aplicación

A continuación, agregue roles de aplicación a su aplicación siguiendo los pasos que se indican en Incorporación de roles de aplicación a una aplicación y su recepción en el token. Solo necesita consultar las secciones Declaración de roles para una aplicación y Asignación de usuarios y grupos a roles de Microsoft Entra. Siga las instrucciones a medida que avanza por el artículo y vuelva a este artículo después de declarar los roles para la aplicación.

Cuando llegue a la sección Declaración de roles para una aplicación, use la interfaz de usuario oles de aplicación para crear roles para el administrador y el usuario normal.
1. Cree un rol de usuario administrador con los siguientes valores:
  - En Nombre para mostrar, escriba admin.
  - En Tipos de miembro permitidos, seleccione Usuarios/Grupos.
  - En Valor, escriba admin.
  - En Descripción, escriba admin.
  - Seleccione ¿quiere habilitar este rol de aplicación?.
2. Seleccione Aplicar. Espere a que se cree el role.
3. Cree un rol de usuario normal siguiendo los mismos pasos, pero con los siguientes valores:
  - En Nombre para mostrar, escriba Usuario.
  - En Valor, escriba usuario.
  - En Descripción, escriba usuario.
Cuando llegue a la sección Asignación de usuarios y grupos a roles de Microsoft Entra, siga los pasos a continuación:
1. Selecciona Agregar usuario o grupo.
2. En el panel Agregar asignación, en Usuarios, seleccione el usuario Admin y en Seleccionar un rol, seleccione el rol Admin. A continuación, seleccione Asignar. Espere hasta que la asignación de la aplicación se complete. Es posible que tenga que desplazarse lateralmente por la tabla para ver la columna Rol asignado.
3. Repita los pasos anteriores para asignar el rol Usuario al usuario Usuario.
4. Seleccione Actualizar para ver los usuarios y roles asignados en el panel Usuarios y grupos.
  
  Puede que tenga que ajustar la anchura de los encabezados de columna para que pueda visualizar lo mismo que en la imagen.

No siga ningún otro paso de Incorporación de roles de aplicación a una aplicación y su recepción en el token.

Protección de una aplicación Quarkus mediante OpenID Connect

En esta sección, protegerá una aplicación Quarkus que autentica y autoriza a los usuarios en su inquilino de Microsoft Entra mediante el uso de OpenID Connect. También descubrirá cómo dar acceso a los usuarios a determinadas partes de la aplicación mediante el control de acceso basado en roles (RBAC).

La aplicación Quarkus de ejemplo para este inicio rápido está en GitHub en el repositorio quarkus-azure y se encuentra en el directorio entra-id-quarkus.

Habilitación de la autenticación y la autorización para proteger la aplicación

La aplicación tiene un recurso de página de bienvenida definido en WelcomePage.java, que se muestra en el siguiente código de ejemplo. Los usuarios no autenticados pueden acceder a esta página. La ruta raíz de la página de bienvenida se encuentra en /.

@Path("/")
public class WelcomePage {

    private final Template welcome;

    public WelcomePage(Template welcome) {
        this.welcome = requireNonNull(welcome, "welcome page is required");
    }

    @GET
    @Produces(MediaType.TEXT_HTML)
    public TemplateInstance get() {
        return welcome.instance();
    }

}

Desde la página de bienvenida, los usuarios pueden iniciar sesión en la aplicación para acceder a la página de perfil. La página de bienvenida tiene enlaces para iniciar sesión como usuario o como administrador. Los enlaces se encuentran en /profile/user y /profile/admin, respectivamente. La interfaz de usuario de la página de bienvenida se define en welcome.qute.html y se muestra en el siguiente ejemplo:

<html>
    <head>
        <meta charset="UTF-8">
        <title>Greeting</title>
    </head>
    <body>
        <h1>Hello, welcome to Quarkus and Microsoft Entra ID integration!</h1>
        <h1>
            <a href="/profile/user">Sign in as user</a>
        </h1>
        <h1>
            <a href="/profile/admin">Sign in as admin</a>
        </h1>
    </body>
</html>

Los enlaces /profile/user y /profile/admin dirigen al recurso de página de perfil, que se define en ProfilePage.java, como se muestra en el siguiente código de ejemplo. Solo pueden acceder a esta página los usuarios autenticados mediante la anotación @RolesAllowed("**") del paquete jakarta.annotation.security.RolesAllowed. La anotación @RolesAllowed("**") especifica que solo los usuarios autenticados pueden acceder a la ruta /profile.

@Path("/profile")
@RolesAllowed("**")
public class ProfilePage {

    private final Template profile;

    @Inject
    SecurityIdentity identity;

    @Inject
    JsonWebToken accessToken;

    public ProfilePage(Template profile) {
        this.profile = requireNonNull(profile, "profile page is required");
    }

    @Path("/admin")
    @GET
    @Produces(MediaType.TEXT_HTML)
    @RolesAllowed("admin")
    public TemplateInstance getAdmin() {
        return getProfile();
    }

    @Path("/user")
    @GET
    @Produces(MediaType.TEXT_HTML)
    @RolesAllowed({"user","admin"})
    public TemplateInstance getUser() {
        return getProfile();
    }

    private TemplateInstance getProfile() {
        return profile
                .data("name", identity.getPrincipal().getName())
                .data("roles", identity.getRoles())
                .data("scopes", accessToken.getClaim("scp"));
    }

}

El recurso de página de perfil permite RBAC mediante la anotación @RolesAllowed. Los argumentos de la anotación @RolesAllowed especifican que solo los usuarios con el rol admin pueden acceder a la ruta /profile/admin y los usuarios con el rol user o admin pueden acceder a la ruta /profile/user.

Los puntos de conexión /profile/admin y /profile/user devuelven la página de perfil. La interfaz de usuario de la página de perfil se define en profile.qute.html, como se muestra en el siguiente ejemplo. Esta página muestra el nombre, los roles y los ámbitos de usuario. La página del perfil también tiene un enlace de cierre de sesión en /logout, que redirige al usuario al proveedor OIDC para cerrar la sesión. La página de perfil está escrita con el motor de plantillas Qute. Tenga en cuenta el uso de las expresiones {} en la página. Estas expresiones hacen uso de los valores pasados a TemplateInstance mediante el método data(). Para obtener más información sobre Qute, consulte Motor de plantillas de Qute.

<html>
    <head>
        <meta charset="UTF-8">
        <title>Profile</title>
    </head>
    <body>
        <h1>Hello, {name}</h1>
        <h2>Roles</h2>
        <ul>
            {#if roles}
                {#for role in roles}
                    <li>{role}</li>
                {/for}
            {#else}
                <li>No roles found!</li>
            {/if}
        </ul>
        <h2>Scopes</h2>
        <p>
            {scopes}
        </p>
        <h1>
            <b><a href="/logout">Sign out</a></b>
        </h1>
    </body>
</html>

Tras cerrar la sesión, el usuario es redirigido a la página de bienvenida y puede volver a registrarse.

Ejecución y prueba de la aplicación Quarkus

En esta sección, se ejecuta y prueba la aplicación Quarkus para ver cómo funciona con Microsoft Entra ID como proveedor de OpenID Connect.

Agregar un URI de redireccionamiento al registro de la aplicación

Para ejecutar y probar correctamente la aplicación de forma local, debe agregar un URI de redireccionamiento al registro de la aplicación. Siga las instrucciones que se indican en la sección Agregar un URI de redireccionamiento de Inicio rápido: Registrar una aplicación con el Plataforma de identidad de Microsoft y use los siguientes valores:

En Configurar plataformas, seleccione Web.
Para los URI de redireccionamiento, introduzca http://localhost:8080.

Preparar el ejemplo

Siga los pasos a continuación para preparar la aplicación Quarkus de ejemplo:

Use los siguientes comandos para clonar la aplicación Quarkus de ejemplo desde GitHub y navegue hasta el directorio entra-id-quarkus:
```
git clone https://github.com/Azure-Samples/quarkus-azure
cd quarkus-azure/entra-id-quarkus
git checkout 2024-09-26
```
Si ve un mensaje acerca de estar en estado HEAD desasociado, este mensaje es seguro de omitir. Dado que este artículo no requiere ninguna confirmación, el estado HEAD desasociado es adecuado.
Use los siguientes comandos para definir las siguientes variables de entorno con los valores que anotó anteriormente:
```
export QUARKUS_OIDC_CLIENT_ID=<application/client-ID>
export QUARKUS_OIDC_CREDENTIALS_SECRET=<client-secret>
export QUARKUS_OIDC_AUTH_SERVER_URL=https://login.microsoftonline.com/<directory/tenant-ID>/v2.0
```
Estas variables de entorno proporcionan los valores para la compatibilidad integrada de OpenID Connect en Quarkus. En el siguiente ejemplo, se muestran las propiedades en application.properties correspondientes.
```
quarkus.oidc.client-id=
quarkus.oidc.credentials.secret=
quarkus.oidc.auth-server-url=
```
Si el valor de una propiedad está en blanco en application.properties, Quarkus convierte el nombre de la propiedad en una variable de entorno y lee el valor del entorno. Para obtener más detalles sobre la conversión de nombres, consulte la especificación de configuración de MicroProfile.

Ejecución de la aplicación Quarkus

Puede ejecutar la aplicación Quarkus en diferentes modos. Seleccione uno de los siguientes métodos para ejecutar la aplicación Quarkus. Para permitir que Quarkus se conecte a Microsoft Entra ID, asegúrese de ejecutar el comando en el shell en el que definió las variables de entorno que se mostraron en la sección anterior.

Ejecutar la aplicación Quarkus en modo de desarrollo:
```
mvn quarkus:dev
```

Ejecutar la aplicación Quarkus en modo JVM:

mvn install
java -jar target/quarkus-app/quarkus-run.jar

Ejecutar la aplicación Quarkus en modo nativo:

mvn install -Dnative -Dquarkus.native.container-build
./target/quarkus-ad-1.0.0-SNAPSHOT-runner

Si desea probar diferentes modos, use Ctrl+C para detener la aplicación Quarkus y, a continuación, ejecútela en otro modo.

Probar la aplicación Quarkus

Una vez ejecutada la aplicación Quarkus, abra un navegador web con una pestaña privada y vaya a http://localhost:8080. Esto le llevará a la página de bienvenida con los enlaces para iniciar sesión como usuario o como administrador. El uso de una pestaña privada evita contaminar cualquier actividad existente de Microsoft Entra ID que pueda tener en su navegador habitual.

Recopilación de las credenciales de los dos usuarios

En este artículo, Microsoft Entra ID usa la dirección de correo electrónico de cada usuario como ID de usuario para iniciar sesión. Siga los pasos a continuación para obtener la dirección de correo electrónico del usuario administrador y del usuario normal:

Inicie sesión en el Centro de administración de Microsoft Entra como Administrador de aplicaciones en la nube.
Si tiene acceso a varios inquilinos, use el icono Configuración () del menú superior para cambiar al inquilino en el que desea registrar la aplicación desde el menú Directorios + suscripciones.
Vaya a Identidad > Usuarios > Todos los usuarios.
Localice el usuario admin en la lista y selecciónelo.
Localice el campo Nombre principal de usuario.
Use el icono de copia situado junto al valor del campo para guardar la dirección de correo electrónico del usuario en el portapapeles. Guarde el valor para usarlo más adelante.
Para obtener la dirección de correo electrónico del usuario normal, siga los mismos pasos.

Use las contraseñas para el usuario administrador y el usuario normal que estableció al crear los usuarios.

Uso de la funcionalidad de la aplicación

Siga los pasos a continuación para usar esta instancia:

Seleccione el enlace Iniciar sesión como usuario. Inicie sesión con el usuario normal que creó anteriormente. Después de iniciar sesión, Microsoft Entra ID le redirige a la página de perfil, donde verá su nombre, roles y ámbitos.
Si es la primera vez que se registra, se le pedirá que actualice su contraseña. Siga las instrucciones para actualizar la contraseña.
Si se le indica Su organización requiere información de seguridad adicional. Siga las instrucciones para descargar y configurar la aplicación Microsoft Authenticator, puede seleccionar Preguntar más tarde para continuar con la prueba.
Si se le indica Permisos solicitados, revise los permisos solicitados por la aplicación. Seleccione Aceptar para continuar con la prueba.
Seleccione Cerrar sesión para cerrar sesión en la aplicación Quarkus. Microsoft Entra ID realiza el cierre de sesión. Después de cerrar la sesión, Microsoft Entra ID le redirige a la página de bienvenida.
Seleccione el enlace Iniciar sesión como administrador. Microsoft Entra ID le redirige a la página de inicio de sesión. Inicie sesión con el usuario administrador que creó anteriormente. Después de iniciar sesión, Microsoft Entra ID le redirige a la página de perfil similar, con un rol diferente admin.
Vuelva a cerrar la sesión e inténtelo en Iniciar sesión como admin con el usuario normal que creó anteriormente. Debería ver un mensaje de error porque el usuario normal no tiene el rol admin.

Limpieza de recursos

En este artículo no se le indica cómo implementar su aplicación en Azure. No hay recursos de Azure para limpiar la aplicación, aunque hay disponibles recursos de Microsoft Entra ID. Para implementar una aplicación en Azure, puede consultar la guía a la que se hace referencia en la siguiente sección.

Cuando termine con los recursos para esta aplicación de ejemplo, siga los pasos a continuación para limpiar los recursos de Microsoft Entra ID. La eliminación de los recursos de Microsoft Entra ID no usados es una importante práctica recomendada de seguridad.

Elimine el registro de la aplicación que ha creado siguiendo los pasos que se indican en Eliminación de una aplicación registrada con la plataforma de identidad de Microsoft. Solo tiene que seguir los pasos de la sección Eliminación de una aplicación creada por su organización.
El acto de eliminar el registro de la aplicación también debería eliminar la aplicación empresarial. Para obtener más información sobre la eliminación de aplicaciones empresariales, consulte Eliminación de una aplicación empresarial.
Elimine los usuarios que ha creado siguiendo los pasos que se indican en Creación, invitación y eliminación de usuarios.

Pasos siguientes

En este inicio rápido, protegerá las aplicaciones Quarkus con Microsoft Entra ID mediante OpenID Connect. Para obtener más información, consulte los siguientes recursos:

Compartir a través de