Get401 Auth Spring

The get401-auth-spring library is a seamless Spring Boot / Spring Web MVC integration for the Get401 identity platform. It builds on get401-auth-core and provides a native HandlerInterceptor that enforces declarative authentication and authorization on your Spring controllers.

GitHub: get401/java-auth-spring

Requirements

  • Java 21 or higher
  • Spring Boot 3.2.x+ with spring-boot-starter-web

Installation

Gradle

dependencies {
    implementation 'com.get401:get401-auth-spring:0.0.1-SNAPSHOT'
}

Maven

<dependency>
    <groupId>com.get401</groupId>
    <artifactId>get401-auth-spring</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>

Setup & Configuration

Register a JwtPublicKeyProvider bean and add the interceptor via WebMvcConfigurer.

import com.get401.auth.core.JwtPublicKeyProvider;
import com.get401.auth.spring.JwtAuthenticationInterceptor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
 
@Configuration
public class Get401SecurityConfig implements WebMvcConfigurer {
 
    @Bean
    public JwtPublicKeyProvider jwtPublicKeyProvider() {
        String appId = "your-get401-app-id";
        String origin = "https://yourdomain.com";
        // Third parameter: Get401 base URL. Null defaults to "https://app.get401.com"
        return new JwtPublicKeyProvider(appId, origin, null);
    }
 
    private final JwtAuthenticationInterceptor jwtAuthenticationInterceptor;
 
    public Get401SecurityConfig(JwtAuthenticationInterceptor jwtAuthenticationInterceptor) {
        this.jwtAuthenticationInterceptor = jwtAuthenticationInterceptor;
    }
 
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(jwtAuthenticationInterceptor)
                .addPathPatterns("/**");
    }
}

Usage

Securing Controllers with Annotations

Apply annotations to your @RestController classes or individual handler methods.

Annotation Description
@AuthGet401 Requires a valid JWT cookie on every request
@VerifyRoles({"role"}) Requires at least one of the specified roles in the JWT
@VerifyScope({"scope"}) Requires the specified scope string in the JWT 
import com.get401.auth.core.annotation.AuthGet401;
import com.get401.auth.core.annotation.VerifyRoles;
import com.get401.auth.core.annotation.VerifyScope;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
 
@RestController
@AuthGet401
public class SecureApiController {
 
    @GetMapping("/api/public-but-logged-in")
    public String openEndpoint() {
        return "You have a valid JWT token!";
    }
 
    @VerifyRoles({"admin", "editor"})
    @GetMapping("/api/admin/dashboard")
    public String adminDashboard() {
        return "Welcome to the admin dashboard.";
    }
 
    @VerifyScope({"write:billing"})
    @GetMapping("/api/billing/update")
    public String updateBilling() {
        return "Billing updated successfully.";
    }
}

Accessing Token Claims in Controllers

The interceptor injects jwtClaims and jwtSubject into request attributes on successful authentication.

import io.jsonwebtoken.Claims;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestAttribute;
import org.springframework.web.bind.annotation.RestController;
 
@RestController
@AuthGet401
public class UserProfileController {
 
    @GetMapping("/api/me")
    public String getMyProfile(
            @RequestAttribute("jwtSubject") String userId,
            @RequestAttribute("jwtClaims") Claims claims) {
 
        String email = claims.get("email", String.class);
        return String.format("Hello %s, your User ID is %s", email, userId);
    }
}

How It Works

  1. Intercept - JwtAuthenticationInterceptor runs on all registered routes.
  2. Annotation check - If the target class/method has none of @AuthGet401, @VerifyRoles, @VerifyScope, the request passes through with no enforcement.
  3. Cookie extraction - Looks for the aact secure cookie. Missing cookie → 401 Unauthorized.
  4. Signature verification - Validates the JWT's Ed25519 signature using the cached public key from Get401.
  5. Role & scope checks - Asserts constraints from @VerifyRoles and @VerifyScope.
  6. Request enrichment - On success, injects jwtClaims and jwtSubject into request attributes.
← PreviousJavaScript SDKNext →Java Core