Java Spring Boot - Auth0 Docs

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.

Crear un proyecto nuevo

Genera un proyecto de Spring Boot con las dependencias requeridas.

Con Spring Initializr
O créalo manualmente con Maven

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

mvn archetype:generate \
    -DgroupId=com.auth0 \
    -DartifactId=auth0-webapp \
    -DarchetypeArtifactId=maven-archetype-quickstart \
    -DinteractiveMode=false

cd auth0-webapp

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)
Gradle (build.gradle)

<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>

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'
}

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
Panel

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
Windows (PowerShell)

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

$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"

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"

Ve a Auth0 Dashboard → Applications → Applications.
Selecciona Create Application.
Introduce un nombre (p. ej., “My Spring Boot Webapp”) y selecciona Regular Web Applications.
Selecciona Create.
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/
Copia el dominio, el ID de cliente y el Secreto del cliente de la pestaña Application Settings.
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/.

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);
            }
        };
    }
}

Crear controladores y vistas

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

Ejecuta la aplicación

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

Maven
Gradle

./mvnw spring-boot:run

./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

Vaya a Auth0 Dashboard → Actions → Flows → Login.
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.

Ve a Auth0 Dashboard → Applications → Tu aplicación → Settings.
En Allowed Callback URLs, agrega: http://localhost:3000/login/oauth2/code/okta.
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.

​Primeros pasos

​Uso avanzado

​Agregar roles a los tokens

​Configurar la autorización

​Problemas comunes

​Recursos adicionales

Documentación del SDK

Documentación de Auth0

Referencia de Spring Security

Referencia de configuración

Auth0 Dashboard

Foro de la comunidad

​Aplicación de ejemplo

Ejemplo de inicio de sesión MVC

Primeros pasos

Uso avanzado

Agregar roles a los tokens

Configurar la autorización

Problemas comunes

Recursos adicionales

Aplicación de ejemplo