Proteger aplicaciones Java con Spring Boot mediante roles y declaraciones de rol

En este artículo se muestra una aplicación web de Java Spring Boot que usa la biblioteca cliente de Spring Boot Starter de Microsoft Entra ID para Java para la autenticación, autorización y adquisición de tokens. La aplicación usa el protocolo OpenID Connect para iniciar sesión de los usuarios y restringe el acceso a algunas rutas mediante roles de aplicación de Microsoft Entra ID (roles de aplicación) para la autorización.

Los roles de aplicación, junto con los grupos de seguridad, son medios populares para implementar la autorización. Con el control de acceso basado en roles (RBAC), mediante roles de aplicación y declaraciones de rol, puedes implementar de forma segura políticas de autorización con el mínimo esfuerzo. Otro enfoque sería usar los grupos de Microsoft Entra ID y las notificaciones de grupo. Los grupos de Microsoft Entra ID y los roles de aplicación no son mutuamente excluyentes. Puede usar ambos para proporcionar un control de acceso granular.

Para ver un vídeo que trata un escenario similar, consulte Implementación de la autorización en las aplicaciones mediante roles de aplicación, grupos de seguridad, ámbitos y roles de directorio.

Para obtener más información sobre cómo funcionan los protocolos en este y otros escenarios, consulte Autenticación frente a autorización.

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

La aplicación usa la biblioteca cliente de Spring Boot Starter de Microsoft Entra ID para Java para iniciar sesión de un usuario y obtener un token de identificador de Microsoft Entra ID. El token de identificador contiene la notificación de roles. La aplicación examina el valor de esta declaración para determinar a qué páginas tiene autorización para acceder el usuario.

Este tipo de autorización se implementa mediante RBAC. Con RBAC, un administrador concede permisos a roles y no a usuarios individuales o grupos. El administrador, a continuación, puede asignar roles a diferentes usuarios y grupos para controlar quién tiene acceso a qué contenido y funcionalidad.

Esta aplicación de ejemplo define los dos roles de aplicación siguientes:

• PrivilegedAdmin: se autoriza a acceder a las páginas Solo administradores y Usuarios normales.
• RegularUser: Autorizado para acceder a la página Usuarios estándar.

Estos roles de aplicación se definen en Azure Portal en el manifiesto de registro de la aplicación. Cuando un usuario inicia sesión en la aplicación, Microsoft Entra ID emite una declaración de roles para cada rol asignado individualmente al usuario en forma de pertenencia al rol.

Puede asignar usuarios y grupos a roles con Azure Portal.

Requisitos previos

• JDK versión 15. Este ejemplo se desarrolló en un sistema con Java 15, pero podría ser compatible con otras versiones.
• Maven 3
• Se recomienda Java Extension Pack para Visual Studio Code para ejecutar este ejemplo en Visual Studio Code.
• 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 tenant de Microsoft Entra ID. Este ejemplo no funcionará con una cuenta Microsoft personal. Por lo tanto, si ha iniciado sesión en Azure Portal con una cuenta personal y nunca ha creado una cuenta de usuario en el directorio, deberá hacerlo ahora.
• Visual Studio Code
• Herramientas de Azure para Visual Studio Code

Recomendaciones

• Cierta familiaridad con Spring Framework.
• Cierta familiaridad con el terminal Linux/OSX.
• 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 para mantenerse up-to-date con los últimos desarrollos.

Configuración del ejemplo

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

Clonación o descarga del 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 4-spring-web-app/3-Authorization-II/roles

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.

Registre la aplicación de ejemplo en su tenant de Microsoft Entra ID

En este ejemplo hay un proyecto. En las secciones siguientes se muestra cómo registrar la aplicación mediante Azure Portal.

Elija el inquilinato de Microsoft Entra ID donde quiere crear las aplicaciones

Para elegir el inquilino, siga estos pasos:

1. Inicie sesión en Azure Portal.

2. Si su cuenta está presente en más de un directorio de Microsoft Entra ID, seleccione su perfil en una esquina del portal de Azure y, a continuación, seleccione Cambiar directorio para cambiar su sesión al directorio de Microsoft Entra ID deseado.

Registrar la aplicación (java-spring-webapp-roles)

Para registrar la aplicación, siga estos pasos:

1. Vaya a Azure Portal y seleccione Microsoft Entra ID.

2. Seleccione Registros de aplicaciones en el panel de navegación y, a continuación, seleccione Nuevo registro.

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

   • En la sección Nombre, escriba un nombre significativo de la aplicación, que se mostrará a los usuarios de la aplicación, por ejemplo, java-spring-webapp-roles.
   • En Tipos de cuenta admitidos, selecciona Solo las cuentas de este directorio organizativo.
   • En la sección URI de redirección (opcional), seleccione Web en el cuadro combinado y escriba los siguientes URI de redirección: http://localhost:8080/login/oauth2/code/.

4. Seleccione Registrar para crear la aplicación.

5. En la página de registro de la aplicación, busque y copie el valor del identificador de la aplicación (cliente) para usarlo más adelante. Este valor se usa en el archivo o los 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 donde puede 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 expiración para el secreto o especifique una duración personalizada. Los secretos de cliente se limitan a una duración máxima de 24 meses y Microsoft recomienda una expiración de menos de 12 meses. Para las aplicaciones de producción, se recomienda usar un certificado o una credencial de identidad federada en lugar de un secreto de cliente.

10. Seleccione Agregar. Se muestra el valor generado.

11. Copie y guarde el valor generado para usarlo en pasos posteriores. Necesitas este valor para los archivos de configuración de tu código. Este valor no volverá a aparecer y no podrá recuperarlo por ningún otro medio. Por lo tanto, asegúrese de guardarlo desde Azure Portal antes de navegar a cualquier otra pantalla o panel.

Definición de roles para una aplicación

Use los pasos siguientes para definir los roles de la aplicación:

1. Todavía en el mismo registro de aplicaciones, seleccione Roles de aplicación en el panel de navegación.

2. Seleccione Crear rol de aplicación y, a continuación, escriba los valores siguientes:

   • En Nombre para mostrar, escriba un nombre adecuado; por ejemplo, PrivilegedAdmin.
   • En Tipos de miembros permitidos, elija Usuario.
   • Para Valor, escriba PrivilegedAdmin.
   • En Descripción, escriba PrivilegedAdmins quién puede ver la página de administración.

3. Seleccione Crear rol de aplicación y, a continuación, escriba los valores siguientes:

   • En Nombre para mostrar, escriba un nombre adecuado; por ejemplo, RegularUser.
   • En Tipos de miembros permitidos, elija Usuario.
   • En el campo Valor, escriba RegularUser.
   • En Descripción, escriba RegularUsers que pueden ver la página de usuario.

4. Seleccione Aplicar para guardar los cambios.

Asignación de usuarios a roles de aplicación

Para agregar usuarios al rol de aplicación definido anteriormente, siga las instrucciones que se indican aquí: Asignación de usuarios y grupos a roles.

Configure la aplicación (java-spring-webapp-roles) para usar tu registro de aplicaciones

Siga estos pasos para configurar la aplicación:

1. Abra el proyecto en su IDE.

2. Abra el archivo src\main\resources\application.yml.

3. Busque el marcador de posición Enter_Your_Tenant_ID_Here y reemplace el valor existente por el Id. de inquilino de Microsoft Entra.

4. Busque el marcador de posición Enter_Your_Client_ID_Here y reemplace el valor existente por el identificador de aplicación o clientId de la aplicación java-spring-webapp-roles que ha copiado de Azure Portal.

5. Busque el marcador de posición Enter_Your_Client_Secret_Here y reemplace el valor existente por el valor que guardó durante la creación de java-spring-webapp-roles, que copió del portal de Azure.

6. Abra el archivo src/main/java/com/microsoft/azuresamples/msal4j/msidentityspringbootapplication/Sample.Controller.java.

7. Busque las referencias a los roles de aplicación PrivilegedAdmin y RegularUser en este archivo. Si es necesario, cámbielos para reflejar los nombres de rol de la aplicación que eligió en los pasos anteriores.

Ejecución del ejemplo

az login

az upgrade

az extension add --name containerapp --upgrade

az extension add --name containerapp --upgrade --allow-preview true

az provider register --namespace Microsoft.App
az provider register --namespace Microsoft.OperationalInsights

export RESOURCE_GROUP="ms-identity-containerapps"
export LOCATION="canadacentral"
export ENVIRONMENT="env-ms-identity-containerapps"
export API_NAME="ms-identity-api"
export JAR_FILE_PATH_AND_NAME="./target/ms-identity-spring-boot-webapp-0.0.1-SNAPSHOT.jar"

az group create  \
    --name $RESOURCE_GROUP \
    --location $LOCATION \

az containerapp env create \
    --name $ENVIRONMENT \
    --resource-group $RESOURCE_GROUP \
    --location $LOCATION

az containerapp env show \
    --name $ENVIRONMENT \
    --resource-group $RESOURCE_GROUP \
    --query properties.defaultDomain

az containerapp up \
    --name $API_NAME \
    --resource-group $RESOURCE_GROUP \
    --location $LOCATION \
    --environment $ENVIRONMENT \
    --artifact <JAR_FILE_PATH_AND_NAME> \
    --ingress external \
    --target-port 8080 \
    --query properties.configuration.ingress.fqdn

Explora el 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 indica Iniciar sesión cuando se ejecuta por primera vez la aplicación. Como alternativa, seleccione los detalles del token, solo administradores o usuarios normales. Dado que estas páginas están protegidas y requieren autenticación, se le redirigirá automáticamente a la página de inicio de sesión.
3. En la página siguiente, siga las instrucciones e inicie sesión con una cuenta en el tenant de Microsoft Entra ID.
4. En la pantalla de consentimiento, observe los ámbitos que se solicitan.
5. Tras completar correctamente el flujo de inicio de sesión, debe redirigirse a la página principal (que muestra el estado de inicio de sesión) o a una de las otras páginas, en función del botón que desencadene el flujo de inicio de sesión.
6. Observe que el botón contextual ahora indica Cerrar sesión y muestra el nombre de usuario.
7. Si está en la página principal, seleccione Detalles del token de ID para ver algunas de las declaraciones decodificadas del token de ID, incluidos los roles.
8. Seleccione Solo administradores para ver el /admin_only. Solo los usuarios con el rol de aplicación PrivilegedAdmin pueden ver esta página. De lo contrario, se muestra un mensaje de error de autorización.
9. Seleccione Usuarios normales para ver la página /regular_user. Solo los usuarios con el rol de aplicación RegularUser o PrivilegedAdmin pueden ver esta página. De lo contrario, se muestra un mensaje de error de autorización.
10. Use el botón de la esquina para cerrar la sesión. La página de estado refleja el nuevo estado.

Sobre el código

Este ejemplo muestra cómo usar la biblioteca cliente Microsoft Entra ID Spring Boot Starter para Java para permitir que los usuarios inicien sesión en su tenant de Microsoft Entra ID. El ejemplo también usa los iniciadores de spring Oauth2 Client y Spring Web Boot. En el ejemplo se usan notificaciones del token de identificador obtenido de Microsoft Entra ID para mostrar los detalles del usuario que ha iniciado sesión y para restringir el acceso a algunas páginas mediante la notificación de roles para la autorización.

Contenido

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

Notificaciones de token de ID

Para extraer los detalles del token, la aplicación usa el objeto AuthenticationPrincipal y OidcUser de Spring Security en una asignación de solicitudes, como se muestra en el ejemplo siguiente. Consulta el Controlador de ejemplo para conocer todos los detalles sobre cómo esta aplicación usa las declaraciones del token de ID.

import org.springframework.security.oauth2.core.oidc.user.OidcUser;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
//...
@GetMapping(path = "/some_path")
public String tokenDetails(@AuthenticationPrincipal OidcUser principal) {
    Map<String, Object> claims = principal.getIdToken().getClaims();
}

Procesar una declaración de roles en el token de ID

La declaración de roles del token incluye los nombres de los roles que tiene asignados el usuario que ha iniciado sesión, como se muestra en el ejemplo siguiente:

{
  ...
  "roles": [
    "PrivilegedAdmin",
    "RegularUser",]
  ...
}

Una forma habitual de acceder a los nombres de los roles se describe en la sección Declaraciones del token de identificador.

Microsoft Entra ID Boot Starter v3.3 y versiones posteriores también analiza automáticamente la notificación de roles y agrega cada rol a Authorities del usuario que ha iniciado sesión, añadiendo el prefijo de cadena APPROLE_. Esta configuración permite a los desarrolladores usar roles de aplicación con anotaciones de condición PrePost de Spring mediante el método hasAuthority. Por ejemplo, puede encontrar las siguientes condiciones @PreAuthorize que se muestran en SampleController.java:

@GetMapping(path = "/admin_only")
@PreAuthorize("hasAuthority('APPROLE_PrivilegedAdmin')")
public String adminOnly(Model model) {
    // restrict to users who have PrivilegedAdmin app role only
}
@GetMapping(path = "/regular_user")
@PreAuthorize("hasAnyAuthority('APPROLE_PrivilegedAdmin','APPROLE_RegularUser')")
public String regularUser(Model model) {
    // restrict to users who have any of RegularUser or PrivilegedAdmin app roles
}

El código siguiente obtiene una lista completa de autoridades para un usuario determinado:

@GetMapping(path = "/some_path")
public String tokenDetails(@AuthenticationPrincipal OidcUser principal) {
   Collection<? extends GrantedAuthority> authorities = principal.getAuthorities();
}

Enlaces para iniciar y cerrar sesión

Para el inicio de sesión, la aplicación realiza una solicitud al punto de conexión de inicio de sesión de Microsoft Entra ID configurado automáticamente por la biblioteca cliente de Spring Boot Starter de Microsoft Entra ID para Java, como se muestra en el ejemplo siguiente:

<a class="btn btn-success" href="/oauth2/authorization/azure">Sign In</a>

Para cerrar sesión, la aplicación realiza una solicitud POST al punto de conexión logout, como se muestra en el ejemplo siguiente:

<form action="#" th:action="@{/logout}" method="post">
  <input class="btn btn-warning" type="submit" value="Sign Out" />
</form>

Elementos de la interfaz de usuario dependientes de la autenticación

La aplicación tiene cierta lógica sencilla en las páginas de plantilla de la interfaz de usuario para determinar el contenido que se va a mostrar en función de si el usuario está autenticado, como se muestra en el ejemplo siguiente mediante etiquetas Spring Security Thymeleaf:

<div sec:authorize="isAuthenticated()">
  this content only shows to authenticated users
</div>
<div sec:authorize="isAnonymous()">
  this content only shows to not-authenticated users
</div>

Protege las rutas con AADWebSecurityConfigurerAdapter

De forma predeterminada, la aplicación protege las páginas Detalles del token de identificador, Solo administradores y Usuarios normales para que solo los usuarios que hayan iniciado sesión puedan acceder a ellas. La aplicación configura estas rutas mediante la propiedad app.protect.authenticated del archivo application.yml. Para configurar los requisitos específicos de su aplicación, puede extender AADWebSecurityConfigurationAdapter en una de sus clases. Para obtener un ejemplo, consulte la clase SecurityConfig de esta aplicación, que se muestra en el código siguiente:

@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class SecurityConfig extends AADWebSecurityConfigurerAdapter{
  @Value( "${app.protect.authenticated}" )
  private String[] protectedRoutes;

    @Override
    public void configure(HttpSecurity http) throws Exception {
    // use required configuration form AADWebSecurityAdapter.configure:
    super.configure(http);
    // add custom configuration:
    http.authorizeRequests()
      .antMatchers(protectedRoutes).authenticated()     // limit these pages to authenticated users (default: /token_details, /admin_only, /regular_user)
      .antMatchers("/**").permitAll();                  // allow all other routes.
    }
}

Más información

• Documentación de la plataforma de identidad de Microsoft
• Descripción general de la biblioteca de autenticación de Microsoft (MSAL)
• Inicio rápido: Registro de una aplicación en la plataforma de identidad de Microsoft
• Inicio rápido: Configuración de una aplicación cliente para tener acceso a las API web
• Comprender las experiencias de consentimiento de aplicaciones de Microsoft Entra ID
• Descripción del consentimiento del usuario y del administrador
• Objetos de aplicación y de entidad de servicio de Azure Active Directory
• Nubes nacionales
• Ejemplos de código MSAL
• Biblioteca cliente de Azure Active Directory Spring Boot Starter para Java
• Biblioteca de autenticación de Microsoft para Java (MSAL4J)
• Página wiki de MSAL4J
• Tokens de identificador
• Tokens de acceso en la plataforma de identidad de Microsoft

Para obtener más información sobre cómo funcionan los protocolos de OAuth 2.0 en este escenario y otros escenarios, vea Escenarios de autenticación para Microsoft Entra ID.