Java Spring Boot

Agrega el inicio de sesión de Auth0 a una aplicación web de Spring Boot con Okta Spring Boot Starter.

Requisitos previos:

• JDK 17+ (descargar)
• Maven 3.6+ o Gradle 7+ (Maven | Gradle)
• Un IDE (se recomienda IntelliJ IDEA, Eclipse o VS Code)

Compatibilidad con versiones de Java: Spring Boot 3.x+ y Okta Spring Boot Starter 3.x requieren Java 17 o superior.

​

Primeros pasos

Esta guía de inicio rápido muestra cómo añadir el inicio de sesión de Auth0 a una aplicación web de Spring Boot. Crearás una aplicación web segura con inicio de sesión, cierre de sesión y una página de perfil protegida mediante Okta Spring Boot Starter, que configura automáticamente la compatibilidad con el inicio de sesión mediante OAuth2 de Spring Security.

1. Crear un proyecto nuevo

   Genera un proyecto de Spring Boot con las dependencias requeridas.

   Con Spring Initializr

   curl -L https://start.spring.io/starter.zip \
       -d dependencies=web,security,thymeleaf \
       -d javaVersion=17 \
       -d name=auth0-webapp \
       -d artifactId=auth0-webapp \
       -d packageName=com.auth0.example \
       -o auth0-webapp.zip
   
   mkdir auth0-webapp && unzip auth0-webapp.zip -d auth0-webapp && cd auth0-webapp
   

   O créalo manualmente con Maven

   mvn archetype:generate \
       -DgroupId=com.auth0 \
       -DartifactId=auth0-webapp \
       -DarchetypeArtifactId=maven-archetype-quickstart \
       -DinteractiveMode=false
   
   cd auth0-webapp
   
2. Añade el starter de Spring Boot de Okta

   Agrega la dependencia de Okta Spring Boot Starter a tu proyecto. Esto incluye la compatibilidad con el inicio de sesión OAuth2 de Spring Security, con configuración automática específica para Auth0/Okta.

   Maven (pom.xml)

   <dependency>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-security</artifactId>
   </dependency>
   <dependency>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-thymeleaf</artifactId>
   </dependency>
   <dependency>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-web</artifactId>
   </dependency>
   <dependency>
       <groupId>org.thymeleaf.extras</groupId>
       <artifactId>thymeleaf-extras-springsecurity6</artifactId>
   </dependency>
   <dependency>
       <groupId>com.okta.spring</groupId>
       <artifactId>okta-spring-boot-starter</artifactId>
       <version>3.1.0</version>
   </dependency>
   

   Gradle (build.gradle)

   dependencies {
       implementation 'org.springframework.boot:spring-boot-starter-security'
       implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
       implementation 'org.springframework.boot:spring-boot-starter-web'
       implementation 'org.thymeleaf.extras:thymeleaf-extras-springsecurity6'
       implementation 'com.okta.spring:okta-spring-boot-starter:3.1.0'
       testImplementation 'org.springframework.boot:spring-boot-starter-test'
       testImplementation 'org.springframework.security:spring-security-test'
       testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
   }
   
3. Configurar Auth0

   Crea una aplicación web regular en tu tenant de Auth0 y agrega la configuración a tu proyecto.

   Puede hacerlo automáticamente ejecutando un comando de CLI o de forma manual desde el Dashboard:

   CLI

   Ejecute el siguiente comando de shell en el directorio raíz del proyecto para crear una aplicación de Auth0 y actualizar el archivo application.yml:

   Mac/Linux

   AUTH0_APP_NAME="My Spring Boot Webapp" && \
   brew tap auth0/auth0-cli && \
   brew install auth0 && \
   auth0 login --no-input && \
   auth0 apps create -n "${AUTH0_APP_NAME}" -t regular \
       --callbacks "http://localhost:3000/login/oauth2/code/okta" \
       --logout-urls "http://localhost:3000/" \
       --json > auth0-app-details.json && \
   DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name') && \
   CLIENT_ID=$(jq -r '.client_id' auth0-app-details.json) && \
   CLIENT_SECRET=$(jq -r '.client_secret' auth0-app-details.json) && \
   mkdir -p src/main/resources && \
   printf 'server:\n  port: 3000\n\nokta:\n  oauth2:\n    issuer: https://%s/\n    client-id: %s\n    client-secret: %s\n' "$DOMAIN" "$CLIENT_ID" "$CLIENT_SECRET" > src/main/resources/application.yml && \
   rm auth0-app-details.json && \
   echo "✅ application.yml created with your Auth0 app details:" && \
   cat src/main/resources/application.yml
   

   Windows (PowerShell)

   $AppName = "My Spring Boot Webapp"
   $latestRelease = Invoke-RestMethod -Uri "https://api.github.com/repos/auth0/auth0-cli/releases/latest"
   $latestVersion = $latestRelease.tag_name
   $version = $latestVersion -replace "^v"
   Invoke-WebRequest -Uri "https://github.com/auth0/auth0-cli/releases/download/${latestVersion}/auth0-cli_${version}_Windows_x86_64.zip" -OutFile ".\auth0.zip"
   Expand-Archive ".\auth0.zip" .\
   [System.Environment]::SetEnvironmentVariable('PATH', $Env:PATH + ";${pwd}")
   auth0 login --no-input
   auth0 apps create -n "$AppName" -t regular `
       --callbacks "http://localhost:3000/login/oauth2/code/okta" `
       --logout-urls "http://localhost:3000/" `
       --json | Set-Content -Path auth0-app-details.json
   $AppDetails = Get-Content -Raw auth0-app-details.json | ConvertFrom-Json
   $Domain = (auth0 tenants list --json | ConvertFrom-Json | Where-Object { $_.active -eq $true }).name
   $ClientId = $AppDetails.client_id
   $ClientSecret = $AppDetails.client_secret
   New-Item -ItemType Directory -Force -Path "src\main\resources"
   @"
   server:
     port: 3000
   
   okta:
     oauth2:
       issuer: "https://$Domain/"
       client-id: "$ClientId"
       client-secret: "$ClientSecret"
   "@ | Set-Content "src\main\resources\application.yml"
   Remove-Item auth0-app-details.json
   Write-Output "✅ application.yml created with your Auth0 app details:"
   Get-Content "src\main\resources\application.yml"
   

   Panel

   Antes de comenzar, agregue la configuración de Auth0 en su archivo src/main/resources/application.yml:

   src/main/resources/application.yml

   server:
     port: 3000
   
   okta:
     oauth2:
       issuer: "https://YOUR_AUTH0_DOMAIN/"
       client-id: "YOUR_CLIENT_ID"
       client-secret: "YOUR_CLIENT_SECRET"
   

   1. Ve a Auth0 Dashboard → Applications → Applications.
   2. Selecciona Create Application.
   3. Introduce un nombre (p. ej., “My Spring Boot Webapp”) y selecciona Regular Web Applications.
   4. Selecciona Create.
   5. Ve a la pestaña Application Settings y configura:
      • Allowed Callback URLs: http://localhost:3000/login/oauth2/code/okta
      • Allowed Logout URLs: http://localhost:3000/
   6. Copia el dominio, el ID de cliente y el Secreto del cliente de la pestaña Application Settings.
   7. Sustituye los valores de marcador de posición en application.yml.

   La URL de callback debe coincidir exactamente. El inicio de sesión OAuth2 de Spring Security usa la ruta /login/oauth2/code/okta de forma predeterminada.

   El emisor debe incluir https:// y una / al final. Usa solo el dominio y la región. Por ejemplo: https://dev-abc123.us.auth0.com/.

4. Configurar la autenticación

   Cree una configuración de seguridad que habilite el inicio de sesión con OAuth2 y administre el cierre de sesión en Auth0. Los usuarios no autenticados se redirigen automáticamente a la página de inicio de sesión de Auth0.

   // src/main/java/com/auth0/example/SecurityConfig.java
   
   package com.auth0.example;
   
   import org.springframework.beans.factory.annotation.Value;
   import org.springframework.context.annotation.Bean;
   import org.springframework.context.annotation.Configuration;
   import org.springframework.security.config.annotation.web.builders.HttpSecurity;
   import org.springframework.security.web.SecurityFilterChain;
   import org.springframework.security.web.authentication.logout.LogoutHandler;
   import org.springframework.web.servlet.support.ServletUriComponentsBuilder;
   
   import java.io.IOException;
   
   import static org.springframework.security.config.Customizer.withDefaults;
   
   @Configuration
   public class SecurityConfig {
   
       @Value("${okta.oauth2.issuer}")
       private String issuer;
       @Value("${okta.oauth2.client-id}")
       private String clientId;
   
       @Bean
       public SecurityFilterChain configure(HttpSecurity http) throws Exception {
           http
               .authorizeHttpRequests(authorize -> authorize
                   .requestMatchers("/", "/images/**").permitAll()
                   .anyRequest().authenticated()
               )
               .oauth2Login(withDefaults())
               .logout(logout -> logout
                   .addLogoutHandler(logoutHandler()));
           return http.build();
       }
   
       private LogoutHandler logoutHandler() {
           return (request, response, authentication) -> {
               try {
                   String baseUrl = ServletUriComponentsBuilder.fromCurrentContextPath().build().toUriString();
                   response.sendRedirect(issuer + "v2/logout?client_id=" + clientId + "&returnTo=" + baseUrl);
               } catch (IOException e) {
                   throw new RuntimeException(e);
               }
           };
       }
   }
   
5. Crear controladores y vistas

   Crea los controladores y las plantillas de Thymeleaf para las páginas de inicio y perfil.

6. Ejecuta la aplicación

   Inicie la aplicación con el wrapper de Maven o Gradle.

   Maven

   ./mvnw spring-boot:run
   

   Gradle

   ./gradlew bootRun
   

   La aplicación ya se está ejecutando en http://localhost:3000. Vaya a http://localhost:3000/profile para iniciar el flujo de inicio de sesión de Auth0.

Ahora debería tener una aplicación web de Spring Boot completamente funcional con el inicio de sesión de Auth0 ejecutándose en localhost. La página de inicio es pública y, al navegar a /profile, los usuarios no autenticados son redirigidos a la página de inicio de sesión de Auth0.

---

​

Uso avanzado

Acceso a los claims del perfil de usuario

El parámetro @AuthenticationPrincipal OidcUser le da acceso a todos los claims del ID Token. Use getClaims() para recuperar el conjunto completo o métodos getter individuales para claims específicos.

@GetMapping("/profile")
public String profile(Model model, @AuthenticationPrincipal OidcUser oidcUser) {
    model.addAttribute("name", oidcUser.getFullName());
    model.addAttribute("email", oidcUser.getEmail());
    model.addAttribute("picture", oidcUser.getPicture());
    model.addAttribute("sub", oidcUser.getSubject());
    model.addAttribute("allClaims", oidcUser.getClaims());
    return "profile";
}

Control de acceso basado en roles

Puede restringir el acceso a las páginas en función de los roles de Auth0. Primero, agregue roles al ID Token mediante una Action de Auth0 y, después, use hasAuthority() en su configuración de seguridad.

​

Agregar roles a los tokens

1. Vaya a Auth0 Dashboard → Actions → Flows → Login.
2. Cree una Action personalizada que agregue roles como un claim personalizado al ID Token:

exports.onExecutePostLogin = async (event, api) => {
  const namespace = "https://my-app.example.com";
  if (event.authorization) {
    api.idToken.setCustomClaim(`${namespace}/roles`, event.authorization.roles);
  }
};

​

Configurar la autorización

Actualice su SecurityConfig para requerir roles específicos en los endpoints:

@Bean
public SecurityFilterChain configure(HttpSecurity http) throws Exception {
    http
        .authorizeHttpRequests(authorize -> authorize
            .requestMatchers("/", "/images/**").permitAll()
            .requestMatchers("/admin/**").hasAuthority("ROLE_admin")
            .anyRequest().authenticated()
        )
        .oauth2Login(withDefaults())
        .logout(logout -> logout
            .addLogoutHandler(logoutHandler()));
    return http.build();
}

Asignación personalizada de autoridades

El starter de Okta admite la asignación personalizada de autoridades mediante la interfaz AuthoritiesProvider. Registre un bean para agregar objetos GrantedAuthority personalizados en función de los atributos del usuario o de fuentes de datos externas.

package com.auth0.example;

import com.okta.spring.boot.oauth.AuthoritiesProvider;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.core.authority.SimpleGrantedAuthority;

import java.util.HashSet;
import java.util.List;
import java.util.Set;

@Configuration
public class AuthoritiesConfig {

    @Bean
    AuthoritiesProvider customAuthoritiesProvider() {
        return (user, userRequest) -> {
            Set<GrantedAuthority> authorities = new HashSet<>();

            // Asigna el claim de roles personalizado a autoridades de Spring Security
            Object roles = user.getAttribute("https://my-app.example.com/roles");
            if (roles instanceof List<?> roleList) {
                roleList.forEach(role ->
                    authorities.add(new SimpleGrantedAuthority("ROLE_" + role))
                );
            }

            return authorities;
        };
    }
}

---

​

Problemas comunes

Error al redirigir al inicio de sesión: URL de callback no válida

Después de seleccionar Iniciar sesión, Auth0 muestra un error porque la URL de callback no coincide.

Las Allowed Callback URLs de tu aplicación de Auth0 deben coincidir exactamente con la URL de callback que usa Spring Security. La URL predeterminada es http://localhost:3000/login/oauth2/code/okta.

1. Ve a Auth0 Dashboard → Applications → Tu aplicación → Settings.
2. En Allowed Callback URLs, agrega: http://localhost:3000/login/oauth2/code/okta.
3. Selecciona Save Changes.

Issuer no válido al iniciar

La aplicación no se inicia o el inicio de sesión falla porque el issuer no coincide.

okta.oauth2.issuer debe ser la URL completa del inquilino de Auth0, incluidos https:// y la / final.

# ❌ INCORRECTO: falta https:// o la barra final
okta:
  oauth2:
    issuer: "dev-abc123.us.auth0.com"

# ✅ CORRECTO: URL completa con barra final
okta:
  oauth2:
    issuer: "https://dev-abc123.us.auth0.com/"

Error de detección de OIDC al iniciar

La aplicación no se inicia y muestra un error de conexión al obtener /.well-known/openid-configuration.

Okta Spring Boot Starter obtiene el documento de detección de OpenID Connect desde la URL del issuer al iniciar la aplicación. Verifica que la URL del issuer sea correcta y que se pueda acceder a ella desde tu red. Si estás detrás de un firewall corporativo, configura el proxy:

okta:
  oauth2:
    issuer: "https://dev-abc123.us.auth0.com/"
    proxy:
      host: "proxy.example.com"
      port: 8080

No se encuentran los valores de configuración

La aplicación se inicia, pero el inicio de sesión falla porque no se están leyendo las propiedades de configuración.

Asegúrate de que application.yml use la sangría YAML correcta dentro del espacio de nombres okta.oauth2:

# ❌ INCORRECTO: estructura plana, no anidada
okta.oauth2.issuer: "https://dev-abc123.us.auth0.com/"

# ✅ CORRECTO: YAML correctamente anidado
okta:
  oauth2:
    issuer: "https://dev-abc123.us.auth0.com/"
    client-id: "YOUR_CLIENT_ID"
    client-secret: "YOUR_CLIENT_SECRET"

Cerrar sesión no borra la sesión de Auth0

Después de seleccionar Cerrar sesión, el usuario vuelve a iniciar sesión de inmediato sin ver la página de inicio de sesión de Auth0.

Asegúrate de que SecurityConfig incluya el LogoutHandler personalizado que redirige al endpoint /v2/logout de Auth0. Verifica también que Allowed Logout URLs en la configuración de tu aplicación de Auth0 incluya http://localhost:3000/.

---

​

Recursos adicionales

Documentación del SDK

Documentación completa del SDK, código fuente y notas de la versión

Documentación de Auth0

Documentación oficial de Auth0 para aplicaciones de Spring Boot

Referencia de Spring Security

Documentación de inicio de sesión con OAuth2 en Spring Security

Referencia de configuración

Todas las propiedades de configuración disponibles de okta.oauth2.*

Auth0 Dashboard

Administra tus API y aplicaciones en Auth0

Foro de la comunidad

Obtén ayuda de la comunidad de Auth0

---

​

Aplicación de ejemplo

En el repositorio de ejemplos de Auth0 hay disponible una aplicación de ejemplo completa que muestra cómo iniciar sesión, ver el perfil y cerrar sesión con Auth0.

Ejemplo de inicio de sesión MVC

Incluye inicio de sesión, cierre de sesión y una página de perfil con integración de Auth0 OAuth2

Clona y ejecuta:

git clone https://github.com/auth0-samples/auth0-spring-boot-login-samples.git
cd auth0-spring-boot-login-samples/mvc-login

# Actualiza src/main/resources/application.yml con tu configuración de Auth0
# Luego ejecuta:
./gradlew bootRun

Abre http://localhost:3000 en tu navegador y selecciona el enlace Login para probar el flujo de inicio de sesión con Auth0.