The repository's Todo service uses Spring gRPC, Spring Security, Protovalidate, JPA, and Liquibase, with localized error handling and integration tests.

🌟 Why Use Spring Boot gRPC?

Spring Boot lets you expose protobuf-defined RPC methods as Spring-managed services.

• Contract-first API design: protobuf files define RPC methods, message shapes, and validation rules.
• Spring-managed services: Spring Boot registers BindableService beans with the gRPC server.
• gRPC security: authentication and authorization run through the server pipeline.
• Centralized validation: request constraints live in the protobuf contract and are checked before service logic.
• Consistent errors: invalid requests and authentication failures become gRPC status responses.
• Deployment support: the repository includes tests, native-image metadata, Docker, Helm, and Terraform assets.

📋 Prerequisites

• ☕ Java Development Kit (JDK) 25
• 📦 Maven Wrapper with ./mvnw
• 🔤 IDE (IntelliJ IDEA, Eclipse, VS Code)
• 🛢️ Basic familiarity with JPA and Spring Security
• 🧪 Optional: grpcurl and jq for manual verification

🛠️ Step 1: Add Dependencies

Add the dependencies used by the sample for gRPC, JPA, Liquibase, JWT security, caching, MapStruct, and Protovalidate.

Maven:

<properties>
  <java.version>25</java.version>
  <org.mapstruct.version>1.6.3</org.mapstruct.version>
  <protovalidate.version>0.14.0</protovalidate.version>
</properties>

<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-grpc-server</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-cache</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-liquibase</artifactId>
  </dependency>
  <dependency>
    <groupId>org.hibernate.orm</groupId>
    <artifactId>hibernate-jcache</artifactId>
    <version>${hibernate.version}</version>
  </dependency>
  <dependency>
    <groupId>com.github.ben-manes.caffeine</groupId>
    <artifactId>caffeine</artifactId>
  </dependency>
  <dependency>
    <groupId>com.github.ben-manes.caffeine</groupId>
    <artifactId>jcache</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
  </dependency>
  <dependency>
    <groupId>build.buf</groupId>
    <artifactId>protovalidate</artifactId>
    <version>${protovalidate.version}</version>
  </dependency>
  <dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <optional>true</optional>
  </dependency>
  <dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct</artifactId>
    <version>${org.mapstruct.version}</version>
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-grpc-server-test</artifactId>
    <scope>test</scope>
  </dependency>
</dependencies>

Gradle:

dependencies {
  implementation 'org.springframework.boot:spring-boot-starter-grpc-server'
  implementation 'org.springframework.boot:spring-boot-starter-cache'
  implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
  implementation 'org.springframework.boot:spring-boot-starter-liquibase'
  implementation 'org.hibernate.orm:hibernate-jcache'
  implementation 'com.github.ben-manes.caffeine:caffeine'
  implementation 'com.github.ben-manes.caffeine:jcache'
  implementation 'org.springframework.boot:spring-boot-starter-oauth2-resource-server'
  implementation 'build.buf:protovalidate:0.14.0'
  implementation 'org.mapstruct:mapstruct:1.6.3'
  compileOnly 'org.projectlombok:lombok'
  testImplementation 'org.springframework.boot:spring-boot-starter-grpc-server-test'
}

Gradle Kotlin DSL:

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-grpc-server")
    implementation("org.springframework.boot:spring-boot-starter-cache")
    implementation("org.springframework.boot:spring-boot-starter-data-jpa")
    implementation("org.springframework.boot:spring-boot-starter-liquibase")
    implementation("org.hibernate.orm:hibernate-jcache")
    implementation("com.github.ben-manes.caffeine:caffeine")
    implementation("com.github.ben-manes.caffeine:jcache")
    implementation("org.springframework.boot:spring-boot-starter-oauth2-resource-server")
    implementation("build.buf:protovalidate:0.14.0")
    implementation("org.mapstruct:mapstruct:1.6.3")
    compileOnly("org.projectlombok:lombok")
    testImplementation("org.springframework.boot:spring-boot-starter-grpc-server-test")
}

The dev profile uses H2, while prod uses PostgreSQL; each database driver is scoped to its profile.

Together, these dependencies let the service persist Todos, run Liquibase migrations, map entities with MapStruct, validate protobuf messages, cache Hibernate data, and protect business RPCs with JWTs.

🛠️ Step 2: Configuration Files

Application configuration connects the gRPC listener to the active profile, persistence layer, migrations, and localized messages. The files below show those settings along with the schema and seed data.

• src/main/resources/config/application.yml Holds the application name, active profile handling, JPA defaults, Hibernate cache settings, Liquibase changelog path, message bundle path, and gRPC server port.

• src/main/resources/config/application-dev.yml Defines the local H2-based development profile, debug logging, and the faker Liquibase context.

• src/main/resources/config/application-prod.yml Switches the sample to PostgreSQL-oriented production defaults with tighter JWT expiration and larger cache sizes.

• src/main/resources/logback-spring.xml Trims noisy framework logs so gRPC, Liquibase, Hibernate, and security output stay readable during local development.

• src/main/resources/db/changelog/db.changelog-master.xml The Liquibase master file that declares DBMS-specific now properties and includes the Todo and user-related schema files.

• src/main/resources/db/changelog/changes/001-create-todos.xml Creates the Todo sequence, todos table, supporting indexes, and Faker-context seed load.

• src/main/resources/db/changelog/changes/002-create-users.xml Creates users, authorities, and user_authorities, then loads the bootstrap security data.

• src/main/resources/db/data/todos.csv Seed Todo rows used when the faker Liquibase context is enabled.

• src/main/resources/db/data/users.csv Initial application users with bcrypt-hashed passwords.

• src/main/resources/db/data/authorities.csv Seed role definitions.

• src/main/resources/db/data/user-authorities.csv User-to-role mappings for the bootstrap security model.

• src/main/resources/i18n/messages.properties Default English validation, authentication, and Todo error messages returned through the gRPC advice layer.

• src/main/resources/i18n/messages_tr.properties Turkish translations for the same validation and security message codes.

• src/main/java/io/github/susimsek/springgrpcsamples/config/i18n/GrpcLocaleServerInterceptor.java Resolves accept-language from gRPC metadata and pushes the selected locale into LocaleContextHolder before validation and exception translation run.

spring:
  application:
    name: spring-grpc-samples
  profiles:
    active: '@spring.profiles.active@'
  docker:
    compose:
      lifecycle-management: start-only
      file: src/main/docker/services.yml
  main:
    allow-bean-definition-overriding: true
  data:
    jpa:
      repositories:
        bootstrap-mode: deferred
  jpa:
    open-in-view: false
    properties:
      hibernate.jdbc.time_zone: Europe/Istanbul
      hibernate.cache.region.factory_class: jcache
      hibernate.javax.cache.provider: com.github.benmanes.caffeine.jcache.spi.CaffeineCachingProvider
      hibernate.cache.use_second_level_cache: true
      hibernate.cache.use_query_cache: false
      hibernate.generate_statistics: false
      hibernate.jdbc.batch_size: 50
      hibernate.order_inserts: true
      hibernate.order_updates: true
      hibernate.jdbc.fetch_size: 50
    hibernate:
      ddl-auto: none
      naming:
        physical-strategy: org.hibernate.boot.model.naming.CamelCaseToUnderscoresNamingStrategy
        implicit-strategy: org.springframework.boot.hibernate.SpringImplicitNamingStrategy
  messages:
    basename: i18n/messages
  liquibase:
    change-log: classpath:db/changelog/db.changelog-master.xml
  grpc:
    server:
      port: 9090

The gRPC listener uses spring.grpc.server.port. JPA, Liquibase, and message-source settings configure the application around it.

application-dev.yml

spring:
  devtools:
    restart:
      enabled: true
  docker:
    compose:
      enabled: false
  datasource:
    url: jdbc:h2:mem:grpcsamples;MODE=PostgreSQL;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE
    username: sa
    password:
  jpa:
    show-sql: true
    properties:
      hibernate.format_sql: true
  liquibase:
    contexts: dev, faker

app:
  cache:
    caffeine:
      ttl: PT1H
      initial-capacity: 50
      maximum-size: 100
  security:
    jwt:
      secret: CDyi/yxfK/EMHtj20eOFoLc0t08WVHotnfcpgpnjdt4=
      issuer: https://spring-grpc-samples.local
      expires-in: PT1H

logging:
  level:
    root: INFO
    org.hibernate.SQL: DEBUG
    io.github.susimsek.springgrpcsamples: DEBUG

application-prod.yml

spring:
  devtools:
    restart:
      enabled: false
  docker:
    compose:
      profiles:
        active: prod
  datasource:
    url: jdbc:postgresql://localhost:5432/grpcsamples
    username: ${SPRING_DATASOURCE_USERNAME}
    hikari:
      maximum-pool-size: 10
      minimum-idle: 2
  jpa:
    show-sql: false
    properties:
      hibernate.format_sql: false
  liquibase:
    contexts: prod

app:
  cache:
    caffeine:
      ttl: PT1H
      initial-capacity: 500
      maximum-size: 1000
  security:
    jwt:
      secret: ${SECURITY_JWT_SECRET}
      issuer: https://spring-grpc-samples.local
      expires-in: PT30M

logging:
  level:
    root: INFO
    org.hibernate.SQL: INFO
    io.github.susimsek.springgrpcsamples: INFO

logback-spring.xml

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <include resource="org/springframework/boot/logging/logback/defaults.xml"/>
    <include resource="org/springframework/boot/logging/logback/console-appender.xml"/>

    <!-- Noisy frameworks trimmed down to WARN to keep dev console readable -->
    <logger name="com.zaxxer" level="WARN"/>
    <logger name="org.apache" level="WARN"/>
    <logger name="org.hibernate" level="WARN"/>
    <logger name="org.springframework" level="WARN"/>
    <logger name="org.springframework.boot.docker" level="WARN"/>
    <logger name="org.springframework.cache" level="WARN"/>
    <logger name="org.springframework.grpc" level="WARN"/>
    <logger name="org.springframework.security" level="WARN"/>
    <logger name="org.springframework.security.oauth2" level="WARN"/>
    <logger name="liquibase" level="WARN"/>
    <logger name="LiquibaseSchemaResolver" level="INFO"/>
    <logger name="io.grpc" level="WARN"/>

    <springProperty name="log.level" source="logging.level.root" defaultValue="INFO"/>
    <root level="${log.level}">
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>

messages.properties

grpc.validation.failed=One or more validation errors occurred.
grpc.validation.unknown=invalid value
grpc.validation.constraints.notBlank=This field cannot be blank.
grpc.validation.constraints.notEmpty=This field cannot be empty.
grpc.validation.constraints.int32.gte=Value must be greater than or equal to {0}.
grpc.validation.constraints.int32.gte_lte=Value must be between 1 and 100.
grpc.validation.constraints.int32.lte=Value must be less than or equal to {0}.
grpc.validation.constraints.int64.gt=Value must be greater than {0}.
grpc.validation.constraints.string.max_len=Value length must be at most {0} characters.
grpc.validation.constraints.string.min_len=Value length must be at least {0} characters.
grpc.auth.invalidCredentials=invalid username or password
grpc.auth.invalidToken=Invalid or expired token.
grpc.auth.unauthenticated=Authentication failed.
grpc.auth.accessDenied=Access denied.
grpc.todo.notFound=todo not found with id: {0}
grpc.internal=An unexpected error occurred. Please try again later.

messages_tr.properties

grpc.validation.failed=Bir veya daha fazla doğrulama hatası oluştu.
grpc.validation.unknown=geçersiz değer
grpc.validation.constraints.notBlank=Bu alan boş bırakılamaz.
grpc.validation.constraints.notEmpty=Bu alan boş olamaz.
grpc.validation.constraints.int32.gte=Değer {0} veya daha büyük olmalıdır.
grpc.validation.constraints.int32.gte_lte=Değer 1 ile 100 arasında olmalıdır.
grpc.validation.constraints.int32.lte=Değer {0} veya daha küçük olmalıdır.
grpc.validation.constraints.int64.gt=Değer {0}''dan büyük olmalıdır.
grpc.validation.constraints.string.max_len=Uzunluk en fazla {0} karakter olmalıdır.
grpc.validation.constraints.string.min_len=Uzunluk en az {0} karakter olmalıdır.
grpc.auth.invalidCredentials=kullanıcı adı veya parola geçersiz
grpc.auth.invalidToken=Token geçersiz veya süresi dolmuş.
grpc.auth.unauthenticated=Authentication failed.
grpc.auth.accessDenied=Access denied.
grpc.todo.notFound=id''si {0} olan todo bulunamadı
grpc.internal=Beklenmeyen bir hata oluştu. Lütfen daha sonra tekrar deneyin.

GrpcLocaleServerInterceptor.java

Java

package io.github.susimsek.springgrpcsamples.config.i18n;

import io.grpc.ForwardingServerCallListener;
import io.grpc.Metadata;
import io.grpc.ServerCall;
import io.grpc.ServerCallHandler;
import io.grpc.ServerInterceptor;
import java.util.List;
import java.util.Locale;
import java.util.function.Supplier;
import org.springframework.context.i18n.LocaleContext;
import org.springframework.context.i18n.LocaleContextHolder;
import org.springframework.context.i18n.SimpleLocaleContext;
import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.grpc.server.GlobalServerInterceptor;
import org.springframework.stereotype.Component;
import org.springframework.util.StringUtils;

@Component
@GlobalServerInterceptor
@Order(Ordered.HIGHEST_PRECEDENCE)
public class GrpcLocaleServerInterceptor implements ServerInterceptor {

    private static final String ACCEPT_LANGUAGE_HEADER = "accept-language";
    private static final List<Locale> SUPPORTED_LOCALES =
            List.of(Locale.ENGLISH, Locale.forLanguageTag("tr"));
    private static final Metadata.Key<String> ACCEPT_LANGUAGE =
            Metadata.Key.of(ACCEPT_LANGUAGE_HEADER, Metadata.ASCII_STRING_MARSHALLER);

    @Override
    public <ReqT, RespT> ServerCall.Listener<ReqT> interceptCall(
            ServerCall<ReqT, RespT> call, Metadata headers, ServerCallHandler<ReqT, RespT> next) {
        Locale locale = resolveLocale(headers);
        ServerCall.Listener<ReqT> listener =
                callWithLocale(locale, () -> next.startCall(call, headers));
        return new LocaleAwareServerCallListener<>(listener, locale);
    }

    private static Locale resolveLocale(Metadata headers) {
        String language = headers.get(ACCEPT_LANGUAGE);
        if (!StringUtils.hasText(language)) {
            return Locale.ENGLISH;
        }
        try {
            Locale locale = Locale.lookup(Locale.LanguageRange.parse(language), SUPPORTED_LOCALES);
            return locale != null ? locale : Locale.ENGLISH;
        } catch (IllegalArgumentException ex) {
            return Locale.ENGLISH;
        }
    }

    private static <T> T callWithLocale(Locale locale, Supplier<T> action) {
        LocaleContext previous = LocaleContextHolder.getLocaleContext();
        try {
            LocaleContextHolder.setLocaleContext(new SimpleLocaleContext(locale));
            return action.get();
        } finally {
            LocaleContextHolder.setLocaleContext(previous);
        }
    }

    private static final class LocaleAwareServerCallListener<ReqT>
            extends ForwardingServerCallListener.SimpleForwardingServerCallListener<ReqT> {

        private final Locale locale;

        private LocaleAwareServerCallListener(ServerCall.Listener<ReqT> delegate, Locale locale) {
            super(delegate);
            this.locale = locale;
        }

        @Override
        public void onMessage(ReqT message) {
            runWithLocale(() -> super.onMessage(message));
        }

        @Override
        public void onHalfClose() {
            runWithLocale(super::onHalfClose);
        }

        @Override
        public void onCancel() {
            runWithLocale(super::onCancel);
        }

        @Override
        public void onComplete() {
            runWithLocale(super::onComplete);
        }

        @Override
        public void onReady() {
            runWithLocale(super::onReady);
        }

        private void runWithLocale(Runnable action) {
            callWithLocale(locale, () -> {
                action.run();
                return null;
            });
        }
    }
}

Kotlin

package io.github.susimsek.springgrpcsamples.config.i18n

import io.grpc.*
import org.springframework.context.i18n.LocaleContext
import org.springframework.context.i18n.LocaleContextHolder
import org.springframework.context.i18n.SimpleLocaleContext
import org.springframework.core.Ordered
import org.springframework.core.annotation.Order
import org.springframework.grpc.server.GlobalServerInterceptor
import org.springframework.stereotype.Component
import org.springframework.util.StringUtils
import java.util.Locale

@Component
@GlobalServerInterceptor
@Order(Ordered.HIGHEST_PRECEDENCE)
class GrpcLocaleServerInterceptor : ServerInterceptor {

    override fun <ReqT : Any?, RespT : Any?> interceptCall(
        call: ServerCall<ReqT, RespT>,
        headers: Metadata,
        next: ServerCallHandler<ReqT, RespT>
    ): ServerCall.Listener<ReqT> {
        val locale = resolveLocale(headers)
        val listener = callWithLocale(locale) { next.startCall(call, headers) }
        return LocaleAwareServerCallListener(listener, locale)
    }

    private fun resolveLocale(headers: Metadata): Locale {
        val language = headers.get(ACCEPT_LANGUAGE)
        if (!StringUtils.hasText(language)) return Locale.ENGLISH
        return try {
            Locale.lookup(Locale.LanguageRange.parse(language), SUPPORTED_LOCALES) ?: Locale.ENGLISH
        } catch (_: IllegalArgumentException) {
            Locale.ENGLISH
        }
    }

    private fun <T> callWithLocale(locale: Locale, action: () -> T): T {
        val previous: LocaleContext = LocaleContextHolder.getLocaleContext()
        return try {
            LocaleContextHolder.setLocaleContext(SimpleLocaleContext(locale))
            action()
        } finally {
            LocaleContextHolder.setLocaleContext(previous)
        }
    }

    private inner class LocaleAwareServerCallListener<ReqT>(
        delegate: ServerCall.Listener<ReqT>,
        private val locale: Locale
    ) : ForwardingServerCallListener.SimpleForwardingServerCallListener<ReqT>(delegate) {

        override fun onMessage(message: ReqT) = runWithLocale { super.onMessage(message) }
        override fun onHalfClose() = runWithLocale { super.onHalfClose() }
        override fun onCancel() = runWithLocale { super.onCancel() }
        override fun onComplete() = runWithLocale { super.onComplete() }
        override fun onReady() = runWithLocale { super.onReady() }

        private fun runWithLocale(action: () -> Unit) {
            callWithLocale(locale) { action() }
        }
    }

    companion object {
        private const val ACCEPT_LANGUAGE_HEADER = "accept-language"
        private val SUPPORTED_LOCALES = listOf(Locale.ENGLISH, Locale.forLanguageTag("tr"))
        private val ACCEPT_LANGUAGE: Metadata.Key<String> =
            Metadata.Key.of(ACCEPT_LANGUAGE_HEADER, Metadata.ASCII_STRING_MARSHALLER)
    }
}

db.changelog-master.xml

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog https://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd">

    <property name="now" value="now()" dbms="h2"/>
    <property name="now" value="current_timestamp" dbms="postgresql"/>
    <include file="db/changelog/changes/001-create-todos.xml"/>
    <include file="db/changelog/changes/002-create-users.xml"/>
</databaseChangeLog>

001-create-todos.xml

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog https://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd">
    <changeSet id="001-create-todo-sequence" author="susimsek">
        <createSequence
            sequenceName="todo_seq"
            startValue="1"
            incrementBy="1"
            minValue="1"
            maxValue="9999999999999999"
            cacheSize="100"
            cycle="false"/>
    </changeSet>
    <changeSet id="002-create-todos-table" author="susimsek">
        <createTable tableName="todos">
            <column name="id" type="bigint" defaultValueSequenceNext="todo_seq">
                <constraints nullable="false" primaryKey="true" primaryKeyName="pk_todos"/>
            </column>
            <column name="title" type="varchar(255)">
                <constraints nullable="false"/>
            </column>
            <column name="completed" type="boolean" defaultValueBoolean="false">
                <constraints nullable="false"/>
            </column>
            <column name="created_by" type="varchar(100)">
                <constraints nullable="false"/>
            </column>
            <column name="created_at" type="timestamp" defaultValueComputed="${now}">
                <constraints nullable="false"/>
            </column>
            <column name="last_modified_by" type="varchar(100)"/>
            <column name="updated_at" type="timestamp" defaultValueComputed="${now}">
                <constraints nullable="false"/>
            </column>
        </createTable>
    </changeSet>
    <changeSet id="003-create-todo-indexes" author="susimsek">
        <createIndex indexName="idx_todos_completed" tableName="todos">
            <column name="completed"/>
        </createIndex>
        <createIndex indexName="idx_todos_title" tableName="todos">
            <column name="title"/>
        </createIndex>
    </changeSet>
    <changeSet id="004-seed-todos" author="susimsek" context="faker">
        <loadData
            encoding="UTF-8"
            file="db/data/todos.csv"
            separator=";"
            tableName="todos"
            usePreparedStatements="true">
            <column header="title" type="string"/>
            <column header="completed" type="boolean"/>
            <column header="created_by" type="string"/>
            <column header="last_modified_by" type="string"/>
        </loadData>
    </changeSet>
</databaseChangeLog>

002-create-users.xml

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog https://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd">
    <changeSet id="001-create-user-sequence" author="susimsek">
        <createSequence
            sequenceName="user_seq"
            startValue="1"
            incrementBy="1"
            minValue="1"
            maxValue="9999999999999999"
            cacheSize="100"
            cycle="false"/>
    </changeSet>
    <changeSet id="002-create-users-table" author="susimsek">
        <createTable tableName="users">
            <column name="id" type="bigint" defaultValueSequenceNext="user_seq">
                <constraints nullable="false" primaryKey="true" primaryKeyName="pk_users"/>
            </column>
            <column name="username" type="varchar(100)">
                <constraints nullable="false" unique="true" uniqueConstraintName="uk_users_username"/>
            </column>
            <column name="password" type="varchar(255)">
                <constraints nullable="false"/>
            </column>
            <column name="enabled" type="boolean" defaultValueBoolean="true">
                <constraints nullable="false"/>
            </column>
            <column name="created_by" type="varchar(100)">
                <constraints nullable="false"/>
            </column>
            <column name="created_at" type="timestamp" defaultValueComputed="${now}">
                <constraints nullable="false"/>
            </column>
            <column name="last_modified_by" type="varchar(100)"/>
            <column name="updated_at" type="timestamp" defaultValueComputed="${now}">
                <constraints nullable="false"/>
            </column>
        </createTable>
    </changeSet>
    <changeSet id="003-create-user-indexes" author="susimsek">
        <createIndex indexName="idx_users_username" tableName="users" unique="true">
            <column name="username"/>
        </createIndex>
    </changeSet>
    <changeSet id="004-create-authorities-table" author="susimsek">
        <createSequence
            sequenceName="authority_seq"
            startValue="1"
            incrementBy="1"
            minValue="1"
            maxValue="9999999999999999"
            cacheSize="100"
            cycle="false"/>
        <createTable tableName="authorities">
            <column name="id" type="bigint" defaultValueSequenceNext="authority_seq">
                <constraints nullable="false" primaryKey="true" primaryKeyName="pk_authorities"/>
            </column>
            <column name="name" type="varchar(50)">
                <constraints nullable="false" unique="true" uniqueConstraintName="uk_authorities_name"/>
            </column>
        </createTable>
    </changeSet>
    <changeSet id="005-create-user-authorities-table" author="susimsek">
        <createTable tableName="user_authorities">
            <column name="user_id" type="bigint">
                <constraints nullable="false"/>
            </column>
            <column name="authority_id" type="bigint">
                <constraints nullable="false"/>
            </column>
        </createTable>
        <addPrimaryKey
            tableName="user_authorities"
            columnNames="user_id, authority_id"
            constraintName="pk_user_authorities"/>
        <addForeignKeyConstraint
            baseTableName="user_authorities"
            baseColumnNames="user_id"
            constraintName="fk_user_authorities_user"
            referencedTableName="users"
            referencedColumnNames="id"/>
        <addForeignKeyConstraint
            baseTableName="user_authorities"
            baseColumnNames="authority_id"
            constraintName="fk_user_authorities_authority"
            referencedTableName="authorities"
            referencedColumnNames="id"/>
        <createIndex indexName="idx_user_authorities_authority" tableName="user_authorities">
            <column name="authority_id"/>
        </createIndex>
    </changeSet>
    <changeSet id="006-seed-authorities" author="susimsek">
        <loadData
            encoding="UTF-8"
            file="db/data/authorities.csv"
            separator=";"
            tableName="authorities"
            usePreparedStatements="true">
            <column header="id" type="numeric"/>
            <column header="name" type="string"/>
        </loadData>
    </changeSet>
    <changeSet id="007-seed-users" author="susimsek">
        <loadData
            encoding="UTF-8"
            file="db/data/users.csv"
            separator=";"
            tableName="users"
            usePreparedStatements="true">
            <column header="username" type="string"/>
            <column header="password" type="string"/>
            <column header="enabled" type="boolean"/>
            <column header="created_by" type="string"/>
            <column header="last_modified_by" type="string"/>
        </loadData>
    </changeSet>
    <changeSet id="008-seed-user-authorities" author="susimsek">
        <loadData
            encoding="UTF-8"
            file="db/data/user-authorities.csv"
            separator=";"
            tableName="user_authorities"
            usePreparedStatements="true">
            <column header="user_id" type="numeric"/>
            <column header="authority_id" type="numeric"/>
        </loadData>
    </changeSet>
</databaseChangeLog>

todos.csv

title;completed;created_by;last_modified_by
Refactor gRPC service;false;system;system
Review pageable todo list;true;system;system
Validate mapper records;false;system;system
Prepare Liquibase changelog;true;system;system
Check auditing fields;false;system;system
Update repository tests;true;system;system
Document todo contract;false;system;system
Exercise patch endpoint;true;system;system
Verify delete behavior;false;system;system
Run Maven coverage;true;system;system

users.csv

username;password;enabled;created_by;last_modified_by
admin;$2a$10$dsEILtFz.VyZL6vXnj1Kg.GFczEdAJ9XlBI234j4ExulU3xub4zTe;true;system;system
user;$2a$10$X4IqH828fc4B.V4t7PtB7.n1eKxlSvCRB6BmntaXnxDCBtj23g6L6;true;system;system

authorities.csv

id;name
1;ROLE_ADMIN
2;ROLE_USER

user-authorities.csv

user_id;authority_id
1;1
1;2
2;2

Native-image metadata lives under src/main/resources/META-INF/native-image. NativeRuntimeHints registers application-specific hints; the dependency metadata covers Protovalidate, Hibernate JCache, and Liquibase resource scanning:

• src/main/resources/META-INF/native-image/build.buf/protovalidate/reflect-config.json Registers Buf validation model types for reflection in GraalVM builds.
• src/main/resources/META-INF/native-image/org.hibernate.orm/hibernate-jcache/reflect-config.json Enables reflective construction of Hibernate’s JCache region factory.
• src/main/resources/META-INF/native-image/org.liquibase/liquibase-core/resource-config.json Keeps Liquibase CSV seed resources reachable in native mode.

reflect-config.json

[
  {
    "name": "org.hibernate.cache.jcache.internal.JCacheRegionFactory",
    "allPublicConstructors": true
  }
]

resource-config.json

{
  "resources": {
    "includes": [
      {
        "pattern": "\\Qdb/data/\\E.*"
      }
    ]
  }
}

🛠️ Step 3: gRPC Bootstrap and Contracts

The application class starts Spring Boot. The protobuf contracts that follow define the public RPC methods and message shapes.

• src/main/java/io/github/susimsek/springgrpcsamples/SpringGrpcSamplesApplication.java Starts the Spring application; component scanning discovers the gRPC service beans.

Java

package io.github.susimsek.springgrpcsamples;

import io.github.susimsek.springgrpcsamples.config.aot.NativeRuntimeHints;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.ConfigurationPropertiesScan;
import org.springframework.context.annotation.ImportRuntimeHints;

@SpringBootApplication
@ConfigurationPropertiesScan
@ImportRuntimeHints(NativeRuntimeHints.class)
public class SpringGrpcSamplesApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringGrpcSamplesApplication.class, args);
    }
}

Kotlin

package io.github.susimsek.springgrpcsamples

import io.github.susimsek.springgrpcsamples.config.aot.NativeRuntimeHints
import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.context.properties.ConfigurationPropertiesScan
import org.springframework.boot.runApplication
import org.springframework.context.annotation.ImportRuntimeHints

@SpringBootApplication
@ConfigurationPropertiesScan
@ImportRuntimeHints(NativeRuntimeHints::class)
class SpringGrpcSamplesApplication

fun main(args: Array<String>) {
    runApplication<SpringGrpcSamplesApplication>(*args)
}

🛠️ Step 4: JPA Integration

The persistence layer brings together application and database settings, shared audit fields, protobuf contracts, and JPA entities.

• ApplicationProperties, DatabaseConfig, AuditableEntity, and AuthorityEntity These classes hold JWT/cache settings, configure JPA auditing, and model shared audit fields and user authorities.

Java

package io.github.susimsek.springgrpcsamples.config;

import java.time.Duration;
import lombok.Getter;
import lombok.Setter;
import org.springframework.boot.context.properties.ConfigurationProperties;

@Getter
@Setter
@ConfigurationProperties(prefix = "app")
public class ApplicationProperties {

    private Cache cache = new Cache();
    private Security security = new Security();

    @Getter
    @Setter
    public static class Cache {
        private Caffeine caffeine = new Caffeine();
    }

    @Getter
    @Setter
    public static class Caffeine {
        private Duration ttl = Duration.ofMinutes(10);
        private int initialCapacity = 100;
        private long maximumSize = 1_000;
    }

    @Getter
    @Setter
    public static class Security {
        private Jwt jwt = new Jwt();
    }

    @Getter
    @Setter
    public static class Jwt {
        private String issuer;
        private String secret;
        private Duration expiresIn;
    }
}

Kotlin

package io.github.susimsek.springgrpcsamples.config

import org.springframework.boot.context.properties.ConfigurationProperties
import java.time.Duration

@ConfigurationProperties(prefix = "app")
class ApplicationProperties {
    var cache: Cache = Cache()
    var security: Security = Security()

    class Cache {
        var caffeine: Caffeine = Caffeine()
    }

    class Caffeine {
        var ttl: Duration = Duration.ofMinutes(10)
        var initialCapacity: Int = 100
        var maximumSize: Long = 1_000
    }

    class Security {
        var jwt: Jwt = Jwt()
    }

    class Jwt {
        var issuer: String? = null
        var secret: String? = null
        var expiresIn: Duration? = null
    }
}

Java

package io.github.susimsek.springgrpcsamples.config;

import io.github.susimsek.springgrpcsamples.security.SecurityAuditorAware;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.domain.AuditorAware;
import org.springframework.data.jpa.repository.config.EnableJpaAuditing;

@Configuration(proxyBeanMethods = false)
@EnableJpaAuditing
public class DatabaseConfig {

    @Bean
    AuditorAware<String> auditorAware() {
        return new SecurityAuditorAware();
    }
}

Kotlin

package io.github.susimsek.springgrpcsamples.config

import io.github.susimsek.springgrpcsamples.security.SecurityAuditorAware
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.data.domain.AuditorAware
import org.springframework.data.jpa.repository.config.EnableJpaAuditing

@Configuration(proxyBeanMethods = false)
@EnableJpaAuditing
class DatabaseConfig {
    @Bean
    fun auditorAware(): AuditorAware<String> = SecurityAuditorAware()
}

Java

package io.github.susimsek.springgrpcsamples.domain;

import jakarta.persistence.Column;
import jakarta.persistence.EntityListeners;
import jakarta.persistence.MappedSuperclass;
import java.time.Instant;
import lombok.Getter;
import lombok.Setter;
import org.jspecify.annotations.Nullable;
import org.springframework.data.annotation.CreatedBy;
import org.springframework.data.annotation.CreatedDate;
import org.springframework.data.annotation.LastModifiedBy;
import org.springframework.data.annotation.LastModifiedDate;
import org.springframework.data.jpa.domain.support.AuditingEntityListener;

@Getter
@Setter
@MappedSuperclass
@EntityListeners(AuditingEntityListener.class)
public abstract class AuditableEntity {
    @CreatedBy
    @Column(name = "created_by", nullable = false, updatable = false, length = 100)
    private String createdBy;

    @CreatedDate
    @Column(name = "created_at", nullable = false, updatable = false)
    private Instant createdAt;

    @LastModifiedBy
    @Column(name = "last_modified_by", length = 100)
    private @Nullable String lastModifiedBy;

    @LastModifiedDate
    @Column(name = "updated_at", nullable = false)
    private Instant updatedAt;
}

Kotlin

package io.github.susimsek.springgrpcsamples.domain

import jakarta.persistence.Column
import jakarta.persistence.EntityListeners
import jakarta.persistence.MappedSuperclass
import org.springframework.data.annotation.CreatedBy
import org.springframework.data.annotation.CreatedDate
import org.springframework.data.annotation.LastModifiedBy
import org.springframework.data.annotation.LastModifiedDate
import org.springframework.data.jpa.domain.support.AuditingEntityListener
import java.time.Instant

@MappedSuperclass
@EntityListeners(AuditingEntityListener::class)
abstract class AuditableEntity {
    @CreatedBy
    @Column(name = "created_by", nullable = false, updatable = false, length = 100)
    lateinit var createdBy: String

    @CreatedDate
    @Column(name = "created_at", nullable = false, updatable = false)
    lateinit var createdAt: Instant

    @LastModifiedBy
    @Column(name = "last_modified_by", length = 100)
    var lastModifiedBy: String? = null

    @LastModifiedDate
    @Column(name = "updated_at", nullable = false)
    lateinit var updatedAt: Instant
}

Java

package io.github.susimsek.springgrpcsamples.domain;

import jakarta.persistence.*;
import lombok.AllArgsConstructor;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;
import org.hibernate.annotations.Cache;
import org.hibernate.annotations.CacheConcurrencyStrategy;

@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@Entity
@Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
@Table(name = "authorities")
public class AuthorityEntity {
    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "authority_seq")
    @SequenceGenerator(name = "authority_seq", sequenceName = "authority_seq", allocationSize = 1)
    private Long id;

    @Column(name = "name", nullable = false, unique = true, length = 50)
    private String name;
}

Kotlin

package io.github.susimsek.springgrpcsamples.domain

import jakarta.persistence.*
import org.hibernate.annotations.Cache
import org.hibernate.annotations.CacheConcurrencyStrategy

@Entity
@Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
@Table(name = "authorities")
class AuthorityEntity(
    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "authority_seq")
    @SequenceGenerator(name = "authority_seq", sequenceName = "authority_seq", allocationSize = 1)
    var id: Long? = null,

    @Column(name = "name", nullable = false, unique = true, length = 50)
    var name: String? = null
)

• src/main/proto/auth.proto Defines the public Login RPC and validates username/password shape.

syntax = "proto3";

import "buf/validate/validate.proto";

option java_multiple_files = true;
option java_package = "io.github.susimsek.springgrpcsamples.proto";
option java_outer_classname = "AuthProto";

service AuthService {
  rpc Login(LoginRequest) returns (Token) {}
}

message LoginRequest {
  string username = 1 [
    (buf.validate.field).ignore = IGNORE_IF_ZERO_VALUE,
    (buf.validate.field).string = {
      min_len: 3
      max_len: 100
    }
  ];

  string password = 2 [
    (buf.validate.field).ignore = IGNORE_IF_ZERO_VALUE,
    (buf.validate.field).string = {
      min_len: 3
      max_len: 100
    }
  ];

  option (buf.validate.message).cel = {
    id: "grpc.validation.constraints.notBlank"
    message: "This field cannot be blank."
    expression: "this.username.matches('.*\\\\S.*') && this.password.matches('.*\\\\S.*')"
  };
}

message Token {
  string access_token = 1;
  string token_type = 2;
  int64 expires_in = 3;
}

• src/main/proto/todo.proto Defines the full CRUD surface and embeds validation rules directly into request messages.

syntax = "proto3";

import "buf/validate/validate.proto";
import "google/protobuf/timestamp.proto";
import "util/pagination.proto";

option java_multiple_files = true;
option java_package = "io.github.susimsek.springgrpcsamples.proto";
option java_outer_classname = "TodoProto";

service TodoService {
  rpc CreateTodo(CreateTodoRequest) returns (Todo) {}
  rpc GetTodo(GetTodoRequest) returns (Todo) {}
  rpc ListTodos(ListTodosRequest) returns (TodoList) {}
  rpc UpdateTodo(UpdateTodoRequest) returns (Todo) {}
  rpc PatchTodo(PatchTodoRequest) returns (Todo) {}
  rpc DeleteTodo(DeleteTodoRequest) returns (DeleteTodoResponse) {}
}

message CreateTodoRequest {
  string title = 1 [
    (buf.validate.field).ignore = IGNORE_IF_ZERO_VALUE,
    (buf.validate.field).string = {
      min_len: 3
      max_len: 255
    }
  ];

  option (buf.validate.message).cel = {
    id: "grpc.validation.constraints.notBlank"
    message: "This field cannot be blank."
    expression: "this.title.matches('.*\\\\S.*')"
  };
}

message GetTodoRequest {
  int64 id = 1 [
    (buf.validate.field).int64 = {
      gt: 0
    }
  ];
}

message ListTodosRequest {
  util.PageRequest page_request = 1;
}

message TodoList {
  repeated Todo items = 1;
  int32 page = 2;
  int32 size = 3;
  int64 total_elements = 4;
  int32 total_pages = 5;
  bool first = 6;
  bool last = 7;
}

message UpdateTodoRequest {
  int64 id = 1 [
    (buf.validate.field).int64 = {
      gt: 0
    }
  ];

  string title = 2 [
    (buf.validate.field).ignore = IGNORE_IF_ZERO_VALUE,
    (buf.validate.field).string = {
      min_len: 3
      max_len: 255
    }
  ];

  bool completed = 3;

  option (buf.validate.message).cel = {
    id: "grpc.validation.constraints.notBlank"
    message: "This field cannot be blank."
    expression: "this.title.matches('.*\\\\S.*')"
  };
}

message PatchTodoRequest {
  int64 id = 1 [
    (buf.validate.field).int64 = {
      gt: 0
    }
  ];

  optional string title = 2 [
    (buf.validate.field).string = {
      min_len: 3
      max_len: 255
    }
  ];

  optional bool completed = 3;

  option (buf.validate.message).cel = {
    id: "grpc.validation.constraints.notEmpty"
    message: "This field cannot be empty."
    expression: "has(this.title) || has(this.completed)"
  };

  option (buf.validate.message).cel = {
    id: "grpc.validation.constraints.notBlank"
    message: "This field cannot be blank."
    expression: "!has(this.title) || this.title.matches('.*\\\\S.*')"
  };
}

message DeleteTodoRequest {
  int64 id = 1 [
    (buf.validate.field).int64 = {
      gt: 0
    }
  ];
}

message DeleteTodoResponse {
  int64 id = 1;
  bool deleted = 2;
}

message Todo {
  int64 id = 1;
  string title = 2;
  bool completed = 3;
  google.protobuf.Timestamp created_at = 4;
  google.protobuf.Timestamp updated_at = 5;
  string created_by = 6;
  string last_modified_by = 7;
}

The protobuf contracts keep validation rules, pagination, and API boundaries close to the RPC definitions, leaving less request-shape logic in the service layer.

• TodoEntity, UserEntity, and UserRepository JPA entities and repositories model Todo persistence, cached user lookups, and authority loading.

Java

package io.github.susimsek.springgrpcsamples.domain;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import jakarta.persistence.SequenceGenerator;
import jakarta.persistence.Table;
import lombok.AllArgsConstructor;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;
import org.hibernate.annotations.Cache;
import org.hibernate.annotations.CacheConcurrencyStrategy;

@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@Entity
@Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
@Table(name = "todos")
public class TodoEntity extends AuditableEntity {

    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "todo_seq")
    @SequenceGenerator(name = "todo_seq", sequenceName = "todo_seq", allocationSize = 1)
    private Long id;

    @Column(name = "title", nullable = false, length = 255)
    private String title;

    @Column(name = "completed", nullable = false)
    private boolean completed;
}

Kotlin

package io.github.susimsek.springgrpcsamples.domain

import jakarta.persistence.*
import org.hibernate.annotations.Cache
import org.hibernate.annotations.CacheConcurrencyStrategy

@Entity
@Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
@Table(name = "todos")
class TodoEntity(
    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "todo_seq")
    @SequenceGenerator(name = "todo_seq", sequenceName = "todo_seq", allocationSize = 1)
    var id: Long? = null,

    @Column(name = "title", nullable = false, length = 255)
    var title: String? = null,

    @Column(name = "completed", nullable = false)
    var completed: Boolean = false
) : AuditableEntity()

Java

package io.github.susimsek.springgrpcsamples.domain;

import jakarta.persistence.*;
import java.util.HashSet;
import java.util.Set;
import lombok.AllArgsConstructor;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;
import org.hibernate.annotations.Cache;
import org.hibernate.annotations.CacheConcurrencyStrategy;

@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@Entity
@Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
@Table(name = "users")
@NamedEntityGraph(
        name = "User.withAuthorities",
        attributeNodes = @NamedAttributeNode("authorities"))
public class UserEntity extends AuditableEntity {

    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "user_seq")
    @SequenceGenerator(name = "user_seq", sequenceName = "user_seq", allocationSize = 1)
    private Long id;

    @Column(name = "username", nullable = false, length = 100)
    private String username;

    @Column(name = "password", nullable = false)
    private String password;

    @Column(name = "enabled", nullable = false)
    private boolean enabled;

    @ManyToMany
    @Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
    @JoinTable(
            name = "user_authorities",
            joinColumns = @JoinColumn(name = "user_id"),
            inverseJoinColumns = @JoinColumn(name = "authority_id"))
    private Set<AuthorityEntity> authorities = new HashSet<>();
}

Kotlin

package io.github.susimsek.springgrpcsamples.domain

import jakarta.persistence.*
import org.hibernate.annotations.Cache
import org.hibernate.annotations.CacheConcurrencyStrategy

@Entity
@Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
@Table(name = "users")
@NamedEntityGraph(
    name = "User.withAuthorities",
    attributeNodes = [NamedAttributeNode("authorities")]
)
class UserEntity(
    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "user_seq")
    @SequenceGenerator(name = "user_seq", sequenceName = "user_seq", allocationSize = 1)
    var id: Long? = null,

    @Column(name = "username", nullable = false, length = 100)
    var username: String? = null,

    @Column(name = "password", nullable = false)
    var password: String? = null,

    @Column(name = "enabled", nullable = false)
    var enabled: Boolean = false,

    @ManyToMany
    @Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
    @JoinTable(
        name = "user_authorities",
        joinColumns = [JoinColumn(name = "user_id")],
        inverseJoinColumns = [JoinColumn(name = "authority_id")]
    )
    var authorities: MutableSet<AuthorityEntity> = linkedSetOf()
) : AuditableEntity()

Java

package io.github.susimsek.springgrpcsamples.repository;

import io.github.susimsek.springgrpcsamples.domain.UserEntity;
import java.util.Optional;
import org.springframework.cache.annotation.Cacheable;
import org.springframework.data.jpa.repository.EntityGraph;
import org.springframework.data.jpa.repository.JpaRepository;

public interface UserRepository extends JpaRepository<UserEntity, Long> {

    String USER_BY_USERNAME_CACHE = "usersByUsername";

    @EntityGraph(value = "User.withAuthorities")
    @Cacheable(cacheNames = USER_BY_USERNAME_CACHE, key = "#username", unless = "#result == null")
    Optional<UserEntity> findByUsername(String username);
}

Kotlin

package io.github.susimsek.springgrpcsamples.repository

import io.github.susimsek.springgrpcsamples.domain.UserEntity
import org.springframework.cache.annotation.Cacheable
import org.springframework.data.jpa.repository.EntityGraph
import org.springframework.data.jpa.repository.JpaRepository
import java.util.Optional

interface UserRepository : JpaRepository<UserEntity, Long> {

    companion object {
        const val USER_BY_USERNAME_CACHE: String = "usersByUsername"
    }

    @EntityGraph(value = "User.withAuthorities")
    @Cacheable(cacheNames = [USER_BY_USERNAME_CACHE], key = "#username", unless = "#result == null")
    fun findByUsername(username: String): Optional<UserEntity>
}

🛠️ Step 5: Authentication & Protected Endpoints

The Todo handlers depend on a repository and mapper; authentication also needs a UserDetailsService that loads JPA users.

• src/main/java/io/github/susimsek/springgrpcsamples/repository/TodoRepository.java Uses Spring Data JPA directly; no custom implementation is needed for basic CRUD and paging.

Java

package io.github.susimsek.springgrpcsamples.repository;

import io.github.susimsek.springgrpcsamples.domain.TodoEntity;
import org.springframework.data.jpa.repository.JpaRepository;

public interface TodoRepository extends JpaRepository<TodoEntity, Long> {}

Kotlin

package io.github.susimsek.springgrpcsamples.repository

import io.github.susimsek.springgrpcsamples.domain.TodoEntity
import org.springframework.data.jpa.repository.JpaRepository

interface TodoRepository : JpaRepository<TodoEntity, Long>

• src/main/java/io/github/susimsek/springgrpcsamples/mapper/TodoMapper.java Converts protobuf requests into JPA entities and maps entities back into protobuf responses.

Java

package io.github.susimsek.springgrpcsamples.mapper;

import io.github.susimsek.springgrpcsamples.domain.TodoEntity;
import io.github.susimsek.springgrpcsamples.proto.CreateTodoRequest;
import io.github.susimsek.springgrpcsamples.proto.PatchTodoRequest;
import io.github.susimsek.springgrpcsamples.proto.Todo;
import io.github.susimsek.springgrpcsamples.proto.UpdateTodoRequest;
import org.mapstruct.BeanMapping;
import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
import org.mapstruct.MappingConstants;
import org.mapstruct.MappingTarget;
import org.mapstruct.NullValueCheckStrategy;
import org.mapstruct.NullValuePropertyMappingStrategy;

@Mapper(
        componentModel = MappingConstants.ComponentModel.SPRING,
        uses = ProtobufMapper.class,
        nullValueCheckStrategy = NullValueCheckStrategy.ALWAYS)
public interface TodoMapper {

    @Mapping(target = "id", ignore = true)
    @Mapping(target = "completed", constant = "false")
    @Mapping(target = "createdBy", ignore = true)
    @Mapping(target = "createdAt", ignore = true)
    @Mapping(target = "lastModifiedBy", ignore = true)
    @Mapping(target = "updatedAt", ignore = true)
    TodoEntity toEntity(CreateTodoRequest request);

    @Mapping(target = "id", ignore = true)
    @Mapping(target = "createdBy", ignore = true)
    @Mapping(target = "createdAt", ignore = true)
    @Mapping(target = "lastModifiedBy", ignore = true)
    @Mapping(target = "updatedAt", ignore = true)
    void updateEntity(UpdateTodoRequest request, @MappingTarget TodoEntity entity);

    @BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)
    @Mapping(target = "id", ignore = true)
    @Mapping(target = "createdBy", ignore = true)
    @Mapping(target = "createdAt", ignore = true)
    @Mapping(target = "lastModifiedBy", ignore = true)
    @Mapping(target = "updatedAt", ignore = true)
    void patchEntity(PatchTodoRequest request, @MappingTarget TodoEntity entity);

    @ProtobufMapping
    @Mapping(target = "mergeCreatedAt", ignore = true)
    @Mapping(target = "mergeUpdatedAt", ignore = true)
    @Mapping(target = "createdByBytes", ignore = true)
    @Mapping(target = "lastModifiedByBytes", ignore = true)
    @Mapping(target = "titleBytes", ignore = true)
    Todo toProto(TodoEntity todo);
}

Kotlin

package io.github.susimsek.springgrpcsamples.mapper

import io.github.susimsek.springgrpcsamples.domain.TodoEntity
import io.github.susimsek.springgrpcsamples.proto.CreateTodoRequest
import io.github.susimsek.springgrpcsamples.proto.PatchTodoRequest
import io.github.susimsek.springgrpcsamples.proto.Todo
import io.github.susimsek.springgrpcsamples.proto.UpdateTodoRequest
import org.mapstruct.BeanMapping
import org.mapstruct.Mapper
import org.mapstruct.Mapping
import org.mapstruct.MappingConstants
import org.mapstruct.MappingTarget
import org.mapstruct.NullValueCheckStrategy
import org.mapstruct.NullValuePropertyMappingStrategy

@Mapper(
    componentModel = MappingConstants.ComponentModel.SPRING,
    uses = [ProtobufMapper::class],
    nullValueCheckStrategy = NullValueCheckStrategy.ALWAYS
)
interface TodoMapper {

    @Mapping(target = "id", ignore = true)
    @Mapping(target = "completed", constant = "false")
    @Mapping(target = "createdBy", ignore = true)
    @Mapping(target = "createdAt", ignore = true)
    @Mapping(target = "lastModifiedBy", ignore = true)
    @Mapping(target = "updatedAt", ignore = true)
    fun toEntity(request: CreateTodoRequest): TodoEntity

    @Mapping(target = "id", ignore = true)
    @Mapping(target = "createdBy", ignore = true)
    @Mapping(target = "createdAt", ignore = true)
    @Mapping(target = "lastModifiedBy", ignore = true)
    @Mapping(target = "updatedAt", ignore = true)
    fun updateEntity(request: UpdateTodoRequest, @MappingTarget entity: TodoEntity)

    @BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)
    @Mapping(target = "id", ignore = true)
    @Mapping(target = "createdBy", ignore = true)
    @Mapping(target = "createdAt", ignore = true)
    @Mapping(target = "lastModifiedBy", ignore = true)
    @Mapping(target = "updatedAt", ignore = true)
    fun patchEntity(request: PatchTodoRequest, @MappingTarget entity: TodoEntity)

    @ProtobufMapping
    @Mapping(target = "mergeCreatedAt", ignore = true)
    @Mapping(target = "mergeUpdatedAt", ignore = true)
    @Mapping(target = "createdByBytes", ignore = true)
    @Mapping(target = "lastModifiedByBytes", ignore = true)
    @Mapping(target = "titleBytes", ignore = true)
    fun toProto(todo: TodoEntity): Todo
}

Two small helpers keep protobuf-specific conversion details out of TodoMapper.

• src/main/java/io/github/susimsek/springgrpcsamples/mapper/ProtobufMapper.java Converts Instant values into protobuf Timestamp instances.

Java

package io.github.susimsek.springgrpcsamples.mapper;

import com.google.protobuf.Timestamp;
import java.time.Instant;
import lombok.AccessLevel;
import lombok.NoArgsConstructor;

@NoArgsConstructor(access = AccessLevel.PRIVATE)
public final class ProtobufMapper {

    public static Timestamp toTimestamp(Instant instant) {
        return Timestamp.newBuilder()
                .setSeconds(instant.getEpochSecond())
                .setNanos(instant.getNano())
                .build();
    }
}

Kotlin

package io.github.susimsek.springgrpcsamples.mapper

import com.google.protobuf.Timestamp
import java.time.Instant

object ProtobufMapper {
    @JvmStatic
    fun toTimestamp(instant: Instant): Timestamp =
        Timestamp.newBuilder()
            .setSeconds(instant.epochSecond)
            .setNanos(instant.nano)
            .build()
}

• src/main/java/io/github/susimsek/springgrpcsamples/mapper/ProtobufMapping.java Ignores protobuf builder internals that should not be mapped by MapStruct.

Java

package io.github.susimsek.springgrpcsamples.mapper;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import org.mapstruct.Mapping;

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.CLASS)
@Mapping(target = "allFields", ignore = true)
@Mapping(target = "clearField", ignore = true)
@Mapping(target = "clearOneof", ignore = true)
@Mapping(target = "mergeFrom", ignore = true)
@Mapping(target = "mergeUnknownFields", ignore = true)
@Mapping(target = "unknownFields", ignore = true)
public @interface ProtobufMapping {}

Kotlin

package io.github.susimsek.springgrpcsamples.mapper

import org.mapstruct.Mapping

@Target(AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.BINARY)
@Mapping(target = "allFields", ignore = true)
@Mapping(target = "clearField", ignore = true)
@Mapping(target = "clearOneof", ignore = true)
@Mapping(target = "mergeFrom", ignore = true)
@Mapping(target = "mergeUnknownFields", ignore = true)
@Mapping(target = "unknownFields", ignore = true)
annotation class ProtobufMapping

• src/main/java/io/github/susimsek/springgrpcsamples/security/DomainUserDetailsService.java Loads a persisted user and adapts it to Spring Security’s UserDetails.

Java

package io.github.susimsek.springgrpcsamples.security;

import io.github.susimsek.springgrpcsamples.domain.UserEntity;
import io.github.susimsek.springgrpcsamples.repository.UserRepository;
import lombok.RequiredArgsConstructor;
import org.springframework.security.core.userdetails.User;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.core.userdetails.UsernameNotFoundException;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
@RequiredArgsConstructor
public class DomainUserDetailsService implements UserDetailsService {

    private final UserRepository userRepository;

    @Transactional(readOnly = true)
    @Override
    public UserDetails loadUserByUsername(String username) {
        return userRepository
                .findByUsername(username)
                .map(
                        user ->
                                User.withUsername(user.getUsername())
                                        .password(user.getPassword())
                                        .authorities(authorities(user))
                                        .disabled(!user.isEnabled())
                                        .build())
                .orElseThrow(() -> new UsernameNotFoundException("user not found"));
    }

    private static String[] authorities(UserEntity user) {
        return user.getAuthorities().stream()
                .map(authority -> authority.getName())
                .toArray(String[]::new);
    }
}

Kotlin

package io.github.susimsek.springgrpcsamples.security

import io.github.susimsek.springgrpcsamples.domain.UserEntity
import io.github.susimsek.springgrpcsamples.repository.UserRepository
import org.springframework.security.core.userdetails.User
import org.springframework.security.core.userdetails.UserDetails
import org.springframework.security.core.userdetails.UserDetailsService
import org.springframework.security.core.userdetails.UsernameNotFoundException
import org.springframework.stereotype.Service
import org.springframework.transaction.annotation.Transactional

@Service
class DomainUserDetailsService(
    private val userRepository: UserRepository
) : UserDetailsService {

    @Transactional(readOnly = true)
    override fun loadUserByUsername(username: String): UserDetails =
        userRepository.findByUsername(username)
            .map { user ->
                User.withUsername(user.username)
                    .password(user.password)
                    .authorities(*authorities(user))
                    .disabled(!user.enabled)
                    .build()
            }
            .orElseThrow { UsernameNotFoundException("user not found") }

    private fun authorities(user: UserEntity): Array<String> =
        user.authorities.map { it.name }.toTypedArray()
}

🛠️ Step 6: Security, Validation, and Error Handling

Both gRPC services are Spring-managed classes that extend generated service base classes.

• src/main/java/io/github/susimsek/springgrpcsamples/service/AuthGrpcService.java Authenticates credentials and returns a JWT-based token response.

Java

package io.github.susimsek.springgrpcsamples.service;

import io.github.susimsek.springgrpcsamples.exception.InvalidCredentialsException;
import io.github.susimsek.springgrpcsamples.proto.AuthServiceGrpc;
import io.github.susimsek.springgrpcsamples.proto.LoginRequest;
import io.github.susimsek.springgrpcsamples.proto.Token;
import io.github.susimsek.springgrpcsamples.security.JwtService;
import io.grpc.stub.StreamObserver;
import lombok.RequiredArgsConstructor;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.AuthenticationException;
import org.springframework.stereotype.Service;

@Service
@RequiredArgsConstructor
public class AuthGrpcService extends AuthServiceGrpc.AuthServiceImplBase {

    private static final String BEARER_TOKEN_TYPE = "Bearer";

    private final AuthenticationManager authenticationManager;
    private final JwtService jwtService;

    @Override
    public void login(LoginRequest request, StreamObserver<Token> responseObserver) {
        Authentication authentication = authenticate(request);
        responseObserver.onNext(
                Token.newBuilder()
                        .setAccessToken(jwtService.generateToken(authentication))
                        .setTokenType(BEARER_TOKEN_TYPE)
                        .setExpiresIn(jwtService.getExpiresInSeconds())
                        .build());
        responseObserver.onCompleted();
    }

    private Authentication authenticate(LoginRequest request) {
        try {
            return authenticationManager.authenticate(
                    UsernamePasswordAuthenticationToken.unauthenticated(
                            request.getUsername(), request.getPassword()));
        } catch (AuthenticationException ex) {
            throw new InvalidCredentialsException();
        }
    }
}

Kotlin

package io.github.susimsek.springgrpcsamples.service

import io.github.susimsek.springgrpcsamples.exception.InvalidCredentialsException
import io.github.susimsek.springgrpcsamples.proto.AuthServiceGrpc
import io.github.susimsek.springgrpcsamples.proto.LoginRequest
import io.github.susimsek.springgrpcsamples.proto.Token
import io.github.susimsek.springgrpcsamples.security.JwtService
import io.grpc.stub.StreamObserver
import org.springframework.security.authentication.AuthenticationManager
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken
import org.springframework.security.core.Authentication
import org.springframework.security.core.AuthenticationException
import org.springframework.stereotype.Service

@Service
class AuthGrpcService(
    private val authenticationManager: AuthenticationManager,
    private val jwtService: JwtService
) : AuthServiceGrpc.AuthServiceImplBase() {

    override fun login(request: LoginRequest, responseObserver: StreamObserver<Token>) {
        val authentication = authenticate(request)
        responseObserver.onNext(
            Token.newBuilder()
                .setAccessToken(jwtService.generateToken(authentication))
                .setTokenType(BEARER_TOKEN_TYPE)
                .setExpiresIn(jwtService.expiresInSeconds)
                .build()
        )
        responseObserver.onCompleted()
    }

    private fun authenticate(request: LoginRequest): Authentication =
        try {
            authenticationManager.authenticate(
                UsernamePasswordAuthenticationToken.unauthenticated(request.username, request.password)
            )
        } catch (ex: AuthenticationException) {
            throw InvalidCredentialsException()
        }

    companion object {
        private const val BEARER_TOKEN_TYPE = "Bearer"
    }
}

• src/main/java/io/github/susimsek/springgrpcsamples/service/TodoGrpcService.java Implements the CRUD flow with JPA repository access and mapper-based protobuf conversion.

Java

package io.github.susimsek.springgrpcsamples.service;

import io.github.susimsek.springgrpcsamples.domain.TodoEntity;
import io.github.susimsek.springgrpcsamples.exception.TodoNotFoundException;
import io.github.susimsek.springgrpcsamples.mapper.TodoMapper;
import io.github.susimsek.springgrpcsamples.proto.CreateTodoRequest;
import io.github.susimsek.springgrpcsamples.proto.DeleteTodoRequest;
import io.github.susimsek.springgrpcsamples.proto.DeleteTodoResponse;
import io.github.susimsek.springgrpcsamples.proto.GetTodoRequest;
import io.github.susimsek.springgrpcsamples.proto.ListTodosRequest;
import io.github.susimsek.springgrpcsamples.proto.PatchTodoRequest;
import io.github.susimsek.springgrpcsamples.proto.Todo;
import io.github.susimsek.springgrpcsamples.proto.TodoList;
import io.github.susimsek.springgrpcsamples.proto.TodoServiceGrpc;
import io.github.susimsek.springgrpcsamples.proto.UpdateTodoRequest;
import io.github.susimsek.springgrpcsamples.repository.TodoRepository;
import io.grpc.stub.StreamObserver;
import lombok.RequiredArgsConstructor;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.PageRequest;
import org.springframework.stereotype.Service;

@Service
@RequiredArgsConstructor
public class TodoGrpcService extends TodoServiceGrpc.TodoServiceImplBase {

    private static final int DEFAULT_PAGE_SIZE = 20;

    private final TodoRepository todoRepository;
    private final TodoMapper todoMapper;

    @Override
    public void createTodo(CreateTodoRequest request, StreamObserver<Todo> responseObserver) {
        TodoEntity created = todoRepository.save(todoMapper.toEntity(request));
        responseObserver.onNext(todoMapper.toProto(created));
        responseObserver.onCompleted();
    }

    @Override
    public void getTodo(GetTodoRequest request, StreamObserver<Todo> responseObserver) {
        TodoEntity todo = findTodo(request.getId());

        responseObserver.onNext(todoMapper.toProto(todo));
        responseObserver.onCompleted();
    }

    @Override
    public void listTodos(ListTodosRequest request, StreamObserver<TodoList> responseObserver) {
        var pageRequest = request.getPageRequest();
        int pageSize = pageRequest.getSize() == 0 ? DEFAULT_PAGE_SIZE : pageRequest.getSize();

        Page<TodoEntity> page =
                todoRepository.findAll(PageRequest.of(pageRequest.getPage(), pageSize));
        TodoList.Builder response =
                TodoList.newBuilder()
                        .setPage(page.getNumber())
                        .setSize(page.getSize())
                        .setTotalElements(page.getTotalElements())
                        .setTotalPages(page.getTotalPages())
                        .setFirst(page.isFirst())
                        .setLast(page.isLast());
        page.stream().map(todoMapper::toProto).forEach(response::addItems);
        responseObserver.onNext(response.build());
        responseObserver.onCompleted();
    }

    @Override
    public void updateTodo(UpdateTodoRequest request, StreamObserver<Todo> responseObserver) {
        TodoEntity updated = findTodo(request.getId());

        todoMapper.updateEntity(request, updated);
        updated = todoRepository.save(updated);
        responseObserver.onNext(todoMapper.toProto(updated));
        responseObserver.onCompleted();
    }

    @Override
    public void patchTodo(PatchTodoRequest request, StreamObserver<Todo> responseObserver) {
        TodoEntity existing = findTodo(request.getId());
        todoMapper.patchEntity(request, existing);
        TodoEntity patched = todoRepository.save(existing);

        responseObserver.onNext(todoMapper.toProto(patched));
        responseObserver.onCompleted();
    }

    @Override
    public void deleteTodo(
            DeleteTodoRequest request, StreamObserver<DeleteTodoResponse> responseObserver) {
        TodoEntity existing = findTodo(request.getId());
        todoRepository.delete(existing);

        responseObserver.onNext(
                DeleteTodoResponse.newBuilder().setId(request.getId()).setDeleted(true).build());
        responseObserver.onCompleted();
    }

    private TodoEntity findTodo(Long id) {
        return todoRepository.findById(id).orElseThrow(() -> new TodoNotFoundException(id));
    }
}

Kotlin

package io.github.susimsek.springgrpcsamples.service

import io.github.susimsek.springgrpcsamples.domain.TodoEntity
import io.github.susimsek.springgrpcsamples.exception.TodoNotFoundException
import io.github.susimsek.springgrpcsamples.mapper.TodoMapper
import io.github.susimsek.springgrpcsamples.proto.*
import io.github.susimsek.springgrpcsamples.repository.TodoRepository
import io.grpc.stub.StreamObserver
import org.springframework.data.domain.PageRequest
import org.springframework.stereotype.Service

@Service
class TodoGrpcService(
    private val todoRepository: TodoRepository,
    private val todoMapper: TodoMapper
) : TodoServiceGrpc.TodoServiceImplBase() {

    override fun createTodo(request: CreateTodoRequest, responseObserver: StreamObserver<Todo>) {
        val created = todoRepository.save(todoMapper.toEntity(request))
        responseObserver.onNext(todoMapper.toProto(created))
        responseObserver.onCompleted()
    }

    override fun getTodo(request: GetTodoRequest, responseObserver: StreamObserver<Todo>) {
        val todo = findTodo(request.id)
        responseObserver.onNext(todoMapper.toProto(todo))
        responseObserver.onCompleted()
    }

    override fun listTodos(request: ListTodosRequest, responseObserver: StreamObserver<TodoList>) {
        val pageRequest = request.pageRequest
        val pageSize = if (pageRequest.size == 0) DEFAULT_PAGE_SIZE else pageRequest.size
        val page = todoRepository.findAll(PageRequest.of(pageRequest.page, pageSize))
        val response = TodoList.newBuilder()
            .setPage(page.number)
            .setSize(page.size)
            .setTotalElements(page.totalElements)
            .setTotalPages(page.totalPages)
            .setFirst(page.isFirst)
            .setLast(page.isLast())
        page.map(todoMapper::toProto).forEach(response::addItems)
        responseObserver.onNext(response.build())
        responseObserver.onCompleted()
    }

    override fun updateTodo(request: UpdateTodoRequest, responseObserver: StreamObserver<Todo>) {
        var updated = findTodo(request.id)
        todoMapper.updateEntity(request, updated)
        updated = todoRepository.save(updated)
        responseObserver.onNext(todoMapper.toProto(updated))
        responseObserver.onCompleted()
    }

    override fun patchTodo(request: PatchTodoRequest, responseObserver: StreamObserver<Todo>) {
        val existing = findTodo(request.id)
        todoMapper.patchEntity(request, existing)
        val patched = todoRepository.save(existing)
        responseObserver.onNext(todoMapper.toProto(patched))
        responseObserver.onCompleted()
    }

    override fun deleteTodo(request: DeleteTodoRequest, responseObserver: StreamObserver<DeleteTodoResponse>) {
        val existing = findTodo(request.id)
        todoRepository.delete(existing)
        responseObserver.onNext(DeleteTodoResponse.newBuilder().setId(request.id).setDeleted(true).build())
        responseObserver.onCompleted()
    }

    private fun findTodo(id: Long): TodoEntity =
        todoRepository.findById(id).orElseThrow { TodoNotFoundException(id) }

    companion object {
        private const val DEFAULT_PAGE_SIZE = 20
    }
}

Each handler receives a protobuf request and completes its response through StreamObserver. Todo handlers delegate persistence and conversion to repositories and mappers; login delegates credential checks to Spring Security.

Security configuration defines password encoding, the authentication manager, and gRPC authorization rules.

• src/main/java/io/github/susimsek/springgrpcsamples/config/security/SecurityConfig.java Wires Spring Security into the gRPC server pipeline and protects TodoService/* with admin authority.

Java

package io.github.susimsek.springgrpcsamples.config.security;

import io.github.susimsek.springgrpcsamples.security.AuthoritiesConstants;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.grpc.server.GlobalServerInterceptor;
import org.springframework.grpc.server.security.AuthenticationProcessInterceptor;
import org.springframework.grpc.server.security.GrpcSecurity;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.ProviderManager;
import org.springframework.security.authentication.dao.DaoAuthenticationProvider;
import org.springframework.security.config.Customizer;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;

@Configuration(proxyBeanMethods = false)
public class SecurityConfig {

    @Bean
    PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }

    @Bean
    AuthenticationManager authenticationManager(
            UserDetailsService userDetailsService, PasswordEncoder passwordEncoder) {
        DaoAuthenticationProvider authenticationProvider =
                new DaoAuthenticationProvider(userDetailsService);
        authenticationProvider.setPasswordEncoder(passwordEncoder);
        return new ProviderManager(authenticationProvider);
    }

    @Bean
    @GlobalServerInterceptor
    @Order(Ordered.HIGHEST_PRECEDENCE + 5)
    AuthenticationProcessInterceptor grpcSecurityFilterChain(GrpcSecurity grpc) throws Exception {
        return grpc.authorizeRequests(
                        requests ->
                                requests.methods("AuthService/Login", "grpc.*/*")
                                        .permitAll()
                                        .methods("TodoService/*")
                                        .hasAuthority(AuthoritiesConstants.ADMIN)
                                        .allRequests()
                                        .authenticated())
                .oauth2ResourceServer(
                        resourceServer -> resourceServer.jwt(Customizer.withDefaults()))
                .build();
    }
}

Kotlin

package io.github.susimsek.springgrpcsamples.config.security

import io.github.susimsek.springgrpcsamples.security.AuthoritiesConstants
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.core.Ordered
import org.springframework.core.annotation.Order
import org.springframework.grpc.server.GlobalServerInterceptor
import org.springframework.grpc.server.security.AuthenticationProcessInterceptor
import org.springframework.grpc.server.security.GrpcSecurity
import org.springframework.security.authentication.AuthenticationManager
import org.springframework.security.authentication.ProviderManager
import org.springframework.security.authentication.dao.DaoAuthenticationProvider
import org.springframework.security.config.Customizer.withDefaults
import org.springframework.security.core.userdetails.UserDetailsService
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder
import org.springframework.security.crypto.password.PasswordEncoder

@Configuration(proxyBeanMethods = false)
class SecurityConfig {

    @Bean
    fun passwordEncoder(): PasswordEncoder = BCryptPasswordEncoder()

    @Bean
    fun authenticationManager(
        userDetailsService: UserDetailsService,
        passwordEncoder: PasswordEncoder
    ): AuthenticationManager {
        val provider = DaoAuthenticationProvider(userDetailsService)
        provider.setPasswordEncoder(passwordEncoder)
        return ProviderManager(provider)
    }

    @Bean
    @GlobalServerInterceptor
    @Order(Ordered.HIGHEST_PRECEDENCE + 5)
    @Throws(Exception::class)
    fun grpcSecurityFilterChain(grpc: GrpcSecurity): AuthenticationProcessInterceptor =
        grpc.authorizeRequests { requests ->
            requests.methods("AuthService/Login", "grpc.*/*")
                .permitAll()
                .methods("TodoService/*")
                .hasAuthority(AuthoritiesConstants.ADMIN)
                .allRequests()
                .authenticated()
        }.oauth2ResourceServer { resourceServer ->
            resourceServer.jwt(withDefaults())
        }.build()
}

The access boundary is explicit: login and infrastructure calls are public, while business RPCs require a bearer token with the expected authority.

• src/main/java/io/github/susimsek/springgrpcsamples/security/JwtService.java Generates JWT tokens from authenticated Spring Security principals.

Java

package io.github.susimsek.springgrpcsamples.security;

import io.github.susimsek.springgrpcsamples.config.ApplicationProperties;
import java.time.Duration;
import java.time.Instant;
import java.util.List;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.oauth2.jose.jws.MacAlgorithm;
import org.springframework.security.oauth2.jwt.JwsHeader;
import org.springframework.security.oauth2.jwt.JwtClaimsSet;
import org.springframework.security.oauth2.jwt.JwtEncoder;
import org.springframework.security.oauth2.jwt.JwtEncoderParameters;
import org.springframework.stereotype.Service;

@Service
public class JwtService {

    private final JwtEncoder jwtEncoder;
    private final String issuer;
    private final Duration expiresIn;

    public JwtService(JwtEncoder jwtEncoder, ApplicationProperties applicationProperties) {
        this.jwtEncoder = jwtEncoder;
        ApplicationProperties.Jwt jwtProperties = applicationProperties.getSecurity().getJwt();
        this.issuer = jwtProperties.getIssuer();
        this.expiresIn = jwtProperties.getExpiresIn();
    }

    public String generateToken(Authentication authentication) {
        Instant issuedAt = Instant.now();
        JwtClaimsSet claims =
                JwtClaimsSet.builder()
                        .issuer(issuer)
                        .issuedAt(issuedAt)
                        .expiresAt(issuedAt.plus(expiresIn))
                        .subject(authentication.getName())
                        .claim(SecurityUtils.AUTHORITIES_CLAIM, resolveRoles(authentication))
                        .build();
        JwsHeader header = JwsHeader.with(MacAlgorithm.HS256).build();
        return jwtEncoder.encode(JwtEncoderParameters.from(header, claims)).getTokenValue();
    }

    public long getExpiresInSeconds() {
        return expiresIn.toSeconds();
    }

    private static List<String> resolveRoles(Authentication authentication) {
        return authentication.getAuthorities().stream()
                .map(GrantedAuthority::getAuthority)
                .toList();
    }
}

Kotlin

package io.github.susimsek.springgrpcsamples.security

import io.github.susimsek.springgrpcsamples.config.ApplicationProperties
import org.springframework.security.core.Authentication
import org.springframework.security.core.GrantedAuthority
import org.springframework.security.oauth2.jose.jws.MacAlgorithm
import org.springframework.security.oauth2.jwt.JwsHeader
import org.springframework.security.oauth2.jwt.JwtClaimsSet
import org.springframework.security.oauth2.jwt.JwtEncoder
import org.springframework.security.oauth2.jwt.JwtEncoderParameters
import org.springframework.stereotype.Service
import java.time.Duration
import java.time.Instant

@Service
class JwtService(
    private val jwtEncoder: JwtEncoder,
    applicationProperties: ApplicationProperties
) {
    private val issuer: String? = applicationProperties.security.jwt.issuer
    private val expiresIn: Duration = applicationProperties.security.jwt.expiresIn ?: Duration.ofHours(1)

    fun generateToken(authentication: Authentication): String {
        val issuedAt = Instant.now()
        val claims = JwtClaimsSet.builder()
            .issuer(issuer)
            .issuedAt(issuedAt)
            .expiresAt(issuedAt.plus(expiresIn))
            .subject(authentication.name)
            .claim(SecurityUtils.AUTHORITIES_CLAIM, resolveRoles(authentication))
            .build()
        val header = JwsHeader.with(MacAlgorithm.HS256).build()
        return jwtEncoder.encode(JwtEncoderParameters.from(header, claims)).tokenValue
    }

    val expiresInSeconds: Long
        get() = expiresIn.seconds

    private fun resolveRoles(authentication: Authentication): List<String> =
        authentication.authorities.map(GrantedAuthority::getAuthority)
}

• src/main/java/io/github/susimsek/springgrpcsamples/security/AuthoritiesConstants.java Defines role names used across bootstrap data, authorization rules, and JWT claims.

Java

package io.github.susimsek.springgrpcsamples.security;

import lombok.AccessLevel;
import lombok.NoArgsConstructor;

/** Constants for Spring Security authorities. */
@NoArgsConstructor(access = AccessLevel.PRIVATE)
public final class AuthoritiesConstants {

    public static final String ADMIN = "ROLE_ADMIN";

    public static final String USER = "ROLE_USER";

    public static final String ANONYMOUS = "ROLE_ANONYMOUS";
}

Kotlin

package io.github.susimsek.springgrpcsamples.security

object AuthoritiesConstants {
    const val ADMIN = "ROLE_ADMIN"
    const val USER = "ROLE_USER"
    const val ANONYMOUS = "ROLE_ANONYMOUS"
}

• src/main/java/io/github/susimsek/springgrpcsamples/security/SecurityUtils.java Extracts the current username from UserDetails, JWT subjects, or plain string principals.

Java

package io.github.susimsek.springgrpcsamples.security;

import java.util.Optional;
import lombok.experimental.UtilityClass;
import org.springframework.security.authentication.AnonymousAuthenticationToken;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.oauth2.jwt.Jwt;

@UtilityClass
public class SecurityUtils {

    public static final String AUTHORITIES_CLAIM = "auth";

    public Optional<String> getCurrentUserLogin() {
        String principal = extractPrincipal(SecurityContextHolder.getContext().getAuthentication());
        return Optional.ofNullable(principal);
    }

    private String extractPrincipal(Authentication authentication) {
        if (authentication == null || authentication instanceof AnonymousAuthenticationToken) {
            return null;
        }
        Object principal = authentication.getPrincipal();
        if (principal instanceof UserDetails userDetails) {
            return userDetails.getUsername();
        }
        if (principal instanceof Jwt jwt) {
            return jwt.getSubject();
        }
        if (principal instanceof String username) {
            return username;
        }
        return null;
    }
}

Kotlin

package io.github.susimsek.springgrpcsamples.security

import org.springframework.security.authentication.AnonymousAuthenticationToken
import org.springframework.security.core.Authentication
import org.springframework.security.core.context.SecurityContextHolder
import org.springframework.security.core.userdetails.UserDetails
import org.springframework.security.oauth2.jwt.Jwt

object SecurityUtils {
    const val AUTHORITIES_CLAIM = "auth"

    fun getCurrentUserLogin(): String? =
        extractPrincipal(SecurityContextHolder.getContext().authentication)

    private fun extractPrincipal(authentication: Authentication?): String? {
        if (authentication == null || authentication is AnonymousAuthenticationToken) {
            return null
        }
        val principal = authentication.principal
        return when (principal) {
            is UserDetails -> principal.username
            is Jwt -> principal.subject
            is String -> principal
            else -> null
        }
    }
}

• src/main/java/io/github/susimsek/springgrpcsamples/security/SecurityAuditorAware.java Bridges Spring Security into JPA auditing so createdBy and lastModifiedBy fields are populated automatically.

Java

package io.github.susimsek.springgrpcsamples.security;

import java.util.Optional;
import org.springframework.data.domain.AuditorAware;

public class SecurityAuditorAware implements AuditorAware<String> {

    private static final String DEFAULT_AUDITOR = "system";

    @Override
    public Optional<String> getCurrentAuditor() {
        return Optional.of(SecurityUtils.getCurrentUserLogin().orElse(DEFAULT_AUDITOR));
    }
}

Kotlin

package io.github.susimsek.springgrpcsamples.security

import org.springframework.data.domain.AuditorAware
import java.util.Optional

class SecurityAuditorAware : AuditorAware<String> {
    override fun getCurrentAuditor(): Optional<String> =
        Optional.of(SecurityUtils.getCurrentUserLogin() ?: DEFAULT_AUDITOR)

    companion object {
        private const val DEFAULT_AUDITOR = "system"
    }
}

• src/main/java/io/github/susimsek/springgrpcsamples/config/security/SecurityJwtConfig.java Creates the HMAC key, JWT encoder/decoder, and a JwtAuthenticationConverter compatible with the custom auth claim.

Java

package io.github.susimsek.springgrpcsamples.config.security;

import io.github.susimsek.springgrpcsamples.config.ApplicationProperties;
import io.github.susimsek.springgrpcsamples.security.SecurityUtils;
import java.nio.charset.StandardCharsets;
import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.oauth2.jose.jws.MacAlgorithm;
import org.springframework.security.oauth2.jwt.JwtDecoder;
import org.springframework.security.oauth2.jwt.JwtEncoder;
import org.springframework.security.oauth2.jwt.NimbusJwtDecoder;
import org.springframework.security.oauth2.jwt.NimbusJwtEncoder;
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter;
import org.springframework.security.oauth2.server.resource.authentication.JwtGrantedAuthoritiesConverter;

@Configuration(proxyBeanMethods = false)
public class SecurityJwtConfig {

    private static final String HMAC_SHA_256 = "HmacSHA256";

    @Bean
    SecretKey jwtSecretKey(ApplicationProperties applicationProperties) {
        String secret = applicationProperties.getSecurity().getJwt().getSecret();
        return new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), HMAC_SHA_256);
    }

    @Bean
    JwtEncoder jwtEncoder(SecretKey jwtSecretKey) {
        return NimbusJwtEncoder.withSecretKey(jwtSecretKey).algorithm(MacAlgorithm.HS256).build();
    }

    @Bean
    JwtDecoder jwtDecoder(SecretKey jwtSecretKey) {
        return NimbusJwtDecoder.withSecretKey(jwtSecretKey)
                .macAlgorithm(MacAlgorithm.HS256)
                .build();
    }

    @Bean
    JwtAuthenticationConverter jwtAuthenticationConverter() {
        JwtGrantedAuthoritiesConverter grantedAuthoritiesConverter =
                new JwtGrantedAuthoritiesConverter();
        grantedAuthoritiesConverter.setAuthoritiesClaimName(SecurityUtils.AUTHORITIES_CLAIM);
        grantedAuthoritiesConverter.setAuthorityPrefix("");

        JwtAuthenticationConverter jwtAuthenticationConverter = new JwtAuthenticationConverter();
        jwtAuthenticationConverter.setJwtGrantedAuthoritiesConverter(grantedAuthoritiesConverter);
        return jwtAuthenticationConverter;
    }
}

Kotlin

package io.github.susimsek.springgrpcsamples.config.security

import io.github.susimsek.springgrpcsamples.config.ApplicationProperties
import io.github.susimsek.springgrpcsamples.security.SecurityUtils
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.security.oauth2.jose.jws.MacAlgorithm
import org.springframework.security.oauth2.jwt.JwtDecoder
import org.springframework.security.oauth2.jwt.JwtEncoder
import org.springframework.security.oauth2.jwt.NimbusJwtDecoder
import org.springframework.security.oauth2.jwt.NimbusJwtEncoder
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter
import org.springframework.security.oauth2.server.resource.authentication.JwtGrantedAuthoritiesConverter
import java.nio.charset.StandardCharsets
import javax.crypto.SecretKey
import javax.crypto.spec.SecretKeySpec

@Configuration(proxyBeanMethods = false)
class SecurityJwtConfig {

    @Bean
    fun jwtSecretKey(applicationProperties: ApplicationProperties): SecretKey {
        val secret = applicationProperties.security.jwt.secret
        return SecretKeySpec(secret.toByteArray(StandardCharsets.UTF_8), HMAC_SHA_256)
    }

    @Bean
    fun jwtEncoder(jwtSecretKey: SecretKey): JwtEncoder =
        NimbusJwtEncoder.withSecretKey(jwtSecretKey).algorithm(MacAlgorithm.HS256).build()

    @Bean
    fun jwtDecoder(jwtSecretKey: SecretKey): JwtDecoder =
        NimbusJwtDecoder.withSecretKey(jwtSecretKey).macAlgorithm(MacAlgorithm.HS256).build()

    @Bean
    fun jwtAuthenticationConverter(): JwtAuthenticationConverter {
        val grantedAuthoritiesConverter = JwtGrantedAuthoritiesConverter()
        grantedAuthoritiesConverter.setAuthoritiesClaimName(SecurityUtils.AUTHORITIES_CLAIM)
        grantedAuthoritiesConverter.setAuthorityPrefix("")

        return JwtAuthenticationConverter().apply {
            setJwtGrantedAuthoritiesConverter(grantedAuthoritiesConverter)
        }
    }

    companion object {
        private const val HMAC_SHA_256 = "HmacSHA256"
    }
}

• src/main/java/io/github/susimsek/springgrpcsamples/config/cache/CacheConfig.java Configures Spring Cache and optional Hibernate second-level caching backed by Caffeine.

Java

package io.github.susimsek.springgrpcsamples.config.cache;

import com.github.benmanes.caffeine.cache.Caffeine;
import com.github.benmanes.caffeine.jcache.configuration.CaffeineConfiguration;
import com.github.benmanes.caffeine.jcache.spi.CaffeineCachingProvider;
import io.github.susimsek.springgrpcsamples.config.ApplicationProperties;
import io.github.susimsek.springgrpcsamples.domain.AuthorityEntity;
import io.github.susimsek.springgrpcsamples.domain.TodoEntity;
import io.github.susimsek.springgrpcsamples.domain.UserEntity;
import io.github.susimsek.springgrpcsamples.repository.UserRepository;
import java.util.OptionalLong;
import javax.cache.CacheManager;
import javax.cache.Caching;
import lombok.RequiredArgsConstructor;
import org.hibernate.cache.jcache.ConfigSettings;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.cache.autoconfigure.JCacheManagerCustomizer;
import org.springframework.boot.hibernate.autoconfigure.HibernatePropertiesCustomizer;
import org.springframework.cache.annotation.EnableCaching;
import org.springframework.cache.caffeine.CaffeineCacheManager;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
@EnableCaching
@RequiredArgsConstructor
public class CacheConfig {

    private final ApplicationProperties applicationProperties;

    @Bean
    public org.springframework.cache.CacheManager cacheManager() {
        CaffeineCacheManager cacheManager = new CaffeineCacheManager();
        cacheManager.setCaffeine(buildCaffeineConfig(cacheProperties()));
        return cacheManager;
    }

    private ApplicationProperties.Caffeine cacheProperties() {
        return applicationProperties.getCache().getCaffeine();
    }

    private Caffeine<Object, Object> buildCaffeineConfig(ApplicationProperties.Caffeine config) {
        return Caffeine.newBuilder()
                .expireAfterWrite(config.getTtl())
                .initialCapacity(config.getInitialCapacity())
                .maximumSize(config.getMaximumSize())
                .recordStats();
    }

    @Configuration(proxyBeanMethods = false)
    @ConditionalOnProperty(
            name = "spring.jpa.properties.hibernate.cache.use_second_level_cache",
            havingValue = "true")
    @RequiredArgsConstructor
    static class HibernateSecondLevelCacheConfiguration {

        private final ApplicationProperties applicationProperties;

        @Bean
        CacheManager jcacheManager(JCacheManagerCustomizer customizer) {
            CacheManager manager =
                    Caching.getCachingProvider(CaffeineCachingProvider.class.getName())
                            .getCacheManager();
            customizer.customize(manager);
            return manager;
        }

        @Bean
        HibernatePropertiesCustomizer hibernatePropertiesCustomizer(CacheManager jcacheManager) {
            return properties -> properties.put(ConfigSettings.CACHE_MANAGER, jcacheManager);
        }

        @Bean
        JCacheManagerCustomizer cacheManagerCustomizer() {
            return cacheManager -> {
                createCache(cacheManager, "default-update-timestamps-region");
                createCache(cacheManager, "default-query-results-region");
                createCache(cacheManager, AuthorityEntity.class.getName());
                createCache(cacheManager, TodoEntity.class.getName());
                createCache(cacheManager, UserEntity.class.getName());
                createCache(cacheManager, UserEntity.class.getName() + ".authorities");
                createCache(cacheManager, UserRepository.USER_BY_USERNAME_CACHE);
            };
        }

        private void createCache(CacheManager cacheManager, String cacheName) {
            javax.cache.Cache<Object, Object> cache = cacheManager.getCache(cacheName);
            if (cache != null) {
                cache.clear();
                return;
            }
            ApplicationProperties.Caffeine config = applicationProperties.getCache().getCaffeine();
            CaffeineConfiguration<Object, Object> caffeineConfig = new CaffeineConfiguration<>();
            caffeineConfig.setMaximumSize(OptionalLong.of(config.getMaximumSize()));
            caffeineConfig.setExpireAfterWrite(OptionalLong.of(config.getTtl().toNanos()));
            caffeineConfig.setStatisticsEnabled(true);
            cacheManager.createCache(cacheName, caffeineConfig);
        }
    }
}

Kotlin

package io.github.susimsek.springgrpcsamples.config.cache

import com.github.benmanes.caffeine.cache.Caffeine
import com.github.benmanes.caffeine.jcache.configuration.CaffeineConfiguration
import com.github.benmanes.caffeine.jcache.spi.CaffeineCachingProvider
import io.github.susimsek.springgrpcsamples.config.ApplicationProperties
import io.github.susimsek.springgrpcsamples.domain.AuthorityEntity
import io.github.susimsek.springgrpcsamples.domain.TodoEntity
import io.github.susimsek.springgrpcsamples.domain.UserEntity
import io.github.susimsek.springgrpcsamples.repository.UserRepository
import org.hibernate.cache.jcache.ConfigSettings
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty
import org.springframework.boot.cache.autoconfigure.JCacheManagerCustomizer
import org.springframework.boot.hibernate.autoconfigure.HibernatePropertiesCustomizer
import org.springframework.cache.annotation.EnableCaching
import org.springframework.cache.caffeine.CaffeineCacheManager
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import java.util.OptionalLong
import javax.cache.CacheManager
import javax.cache.Caching

@Configuration(proxyBeanMethods = false)
@EnableCaching
class CacheConfig(
    private val applicationProperties: ApplicationProperties
) {

    @Bean
    fun cacheManager(): org.springframework.cache.CacheManager =
        CaffeineCacheManager().apply {
            setCaffeine(buildCaffeineConfig(cacheProperties()))
        }

    private fun cacheProperties(): ApplicationProperties.Caffeine =
        applicationProperties.cache.caffeine

    private fun buildCaffeineConfig(config: ApplicationProperties.Caffeine): Caffeine<Any, Any> =
        Caffeine.newBuilder()
            .expireAfterWrite(config.ttl)
            .initialCapacity(config.initialCapacity)
            .maximumSize(config.maximumSize)
            .recordStats()

    @Configuration(proxyBeanMethods = false)
    @ConditionalOnProperty(
        name = ["spring.jpa.properties.hibernate.cache.use_second_level_cache"],
        havingValue = "true"
    )
    class HibernateSecondLevelCacheConfiguration(
        private val applicationProperties: ApplicationProperties
    ) {

        @Bean
        fun jcacheManager(customizer: JCacheManagerCustomizer): CacheManager =
            Caching.getCachingProvider(CaffeineCachingProvider::class.java.name)
                .cacheManager
                .also(customizer::customize)

        @Bean
        fun hibernatePropertiesCustomizer(jcacheManager: CacheManager): HibernatePropertiesCustomizer =
            HibernatePropertiesCustomizer { properties ->
                properties[ConfigSettings.CACHE_MANAGER] = jcacheManager
            }

        @Bean
        fun cacheManagerCustomizer(): JCacheManagerCustomizer =
            JCacheManagerCustomizer { cacheManager ->
                createCache(cacheManager, "default-update-timestamps-region")
                createCache(cacheManager, "default-query-results-region")
                createCache(cacheManager, AuthorityEntity::class.java.name)
                createCache(cacheManager, TodoEntity::class.java.name)
                createCache(cacheManager, UserEntity::class.java.name)
                createCache(cacheManager, UserEntity::class.java.name + ".authorities")
                createCache(cacheManager, UserRepository.USER_BY_USERNAME_CACHE)
            }

        private fun createCache(cacheManager: CacheManager, cacheName: String) {
            val cache = cacheManager.getCache(cacheName)
            if (cache != null) {
                cache.clear()
                return
            }
            val config = applicationProperties.cache.caffeine
            val caffeineConfig = CaffeineConfiguration<Any, Any>()
            caffeineConfig.setMaximumSize(OptionalLong.of(config.maximumSize))
            caffeineConfig.setExpireAfterWrite(OptionalLong.of(config.ttl.toNanos()))
            caffeineConfig.isStatisticsEnabled = true
            cacheManager.createCache(cacheName, caffeineConfig)
        }
    }
}

The sample does not validate requests manually in every service method. Instead, it uses a global server interceptor to run Protovalidate against application protobuf messages, then translates failures through a centralized gRPC advice.

• src/main/java/io/github/susimsek/springgrpcsamples/config/validation/GrpcValidationConfig.java Registers the shared Protovalidate Validator bean used by the interceptor.

Java

package io.github.susimsek.springgrpcsamples.config.validation;

import build.buf.protovalidate.Validator;
import build.buf.protovalidate.ValidatorFactory;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
public class GrpcValidationConfig {

    @Bean
    public Validator grpcValidator() {
        return ValidatorFactory.newBuilder().build();
    }
}

Kotlin

package io.github.susimsek.springgrpcsamples.config.validation

import build.buf.protovalidate.Validator
import build.buf.protovalidate.ValidatorFactory
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration

@Configuration(proxyBeanMethods = false)
class GrpcValidationConfig {
    @Bean
    fun grpcValidator(): Validator = ValidatorFactory.newBuilder().build()
}

• src/main/java/io/github/susimsek/springgrpcsamples/config/validation/GrpcValidationServerInterceptor.java Applies protobuf validation before service logic runs.

Java

package io.github.susimsek.springgrpcsamples.config.validation;

import build.buf.protovalidate.ValidationResult;
import build.buf.protovalidate.Validator;
import build.buf.protovalidate.exceptions.ValidationException;
import com.google.protobuf.Message;
import io.github.susimsek.springgrpcsamples.exception.GrpcValidationException;
import io.github.susimsek.springgrpcsamples.exception.GrpcViolation;
import io.grpc.ForwardingServerCallListener;
import io.grpc.Metadata;
import io.grpc.ServerCall;
import io.grpc.ServerCallHandler;
import io.grpc.ServerInterceptor;
import lombok.RequiredArgsConstructor;
import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.grpc.server.GlobalServerInterceptor;
import org.springframework.stereotype.Component;

@Component
@GlobalServerInterceptor
@Order(Ordered.HIGHEST_PRECEDENCE + 10)
@RequiredArgsConstructor
public class GrpcValidationServerInterceptor implements ServerInterceptor {

    private static final String APPLICATION_PROTO_PACKAGE =
            "io.github.susimsek.springgrpcsamples.proto";

    private final Validator validator;

    @Override
    public <ReqT, RespT> ServerCall.Listener<ReqT> interceptCall(
            ServerCall<ReqT, RespT> call, Metadata headers, ServerCallHandler<ReqT, RespT> next) {
        ServerCall.Listener<ReqT> listener = next.startCall(call, headers);
        return new ValidationServerCallListener<>(listener, validator);
    }

    private static final class ValidationServerCallListener<ReqT>
            extends ForwardingServerCallListener.SimpleForwardingServerCallListener<ReqT> {

        private final Validator validator;

        private ValidationServerCallListener(
                ServerCall.Listener<ReqT> delegate, Validator validator) {
            super(delegate);
            this.validator = validator;
        }

        @Override
        public void onMessage(ReqT message) {
            if (message instanceof Message protoMessage
                    && APPLICATION_PROTO_PACKAGE.equals(protoMessage.getClass().getPackageName())) {
                validate(protoMessage);
            }
            super.onMessage(message);
        }

        private void validate(Message message) {
            try {
                ValidationResult result = validator.validate(message);
                if (!result.isSuccess()) {
                    throw new GrpcValidationException(
                            result.getViolations().stream()
                                    .map(v -> GrpcViolation.from(v))
                                    .toList());
                }
            } catch (ValidationException ex) {
                throw new IllegalStateException("Failed to validate gRPC request", ex);
            }
        }
    }
}

Kotlin

package io.github.susimsek.springgrpcsamples.config.validation

import build.buf.protovalidate.ValidationResult
import build.buf.protovalidate.Validator
import build.buf.protovalidate.exceptions.ValidationException
import com.google.protobuf.Message
import io.github.susimsek.springgrpcsamples.exception.GrpcValidationException
import io.github.susimsek.springgrpcsamples.exception.GrpcViolation
import io.grpc.*
import org.springframework.core.Ordered
import org.springframework.core.annotation.Order
import org.springframework.grpc.server.GlobalServerInterceptor
import org.springframework.stereotype.Component

@Component
@GlobalServerInterceptor
@Order(Ordered.HIGHEST_PRECEDENCE + 10)
class GrpcValidationServerInterceptor(
    private val validator: Validator
) : ServerInterceptor {

    override fun <ReqT : Any?, RespT : Any?> interceptCall(
        call: ServerCall<ReqT, RespT>,
        headers: Metadata,
        next: ServerCallHandler<ReqT, RespT>
    ): ServerCall.Listener<ReqT> {
        val listener = next.startCall(call, headers)
        return ValidationServerCallListener(listener, validator)
    }

    private class ValidationServerCallListener<ReqT>(
        delegate: ServerCall.Listener<ReqT>,
        private val validator: Validator
    ) : ForwardingServerCallListener.SimpleForwardingServerCallListener<ReqT>(delegate) {

        override fun onMessage(message: ReqT) {
            if (message is Message && message.javaClass.packageName == APPLICATION_PROTO_PACKAGE) {
                validate(message)
            }
            super.onMessage(message)
        }

        private fun validate(message: Message) {
            try {
                val result: ValidationResult = validator.validate(message)
                if (!result.isSuccess) {
                    throw GrpcValidationException(result.violations.map { GrpcViolation.from(it) })
                }
            } catch (ex: ValidationException) {
                throw IllegalStateException("Failed to validate gRPC request", ex)
            }
        }
    }

    companion object {
        private const val APPLICATION_PROTO_PACKAGE = "io.github.susimsek.springgrpcsamples.proto"
    }
}

• src/main/java/io/github/susimsek/springgrpcsamples/exception/GlobalGrpcExceptionHandler.java Converts validation, authentication, authorization, and unexpected failures into structured gRPC status responses.

Java

package io.github.susimsek.springgrpcsamples.exception;

import build.buf.validate.FieldPathElement;
import build.buf.validate.Violation;
import com.google.protobuf.Any;
import com.google.rpc.BadRequest;
import io.grpc.Status;
import io.grpc.StatusException;
import io.grpc.protobuf.StatusProto;
import java.util.Locale;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.context.MessageSource;
import org.springframework.context.i18n.LocaleContextHolder;
import org.springframework.grpc.server.advice.GrpcAdvice;
import org.springframework.grpc.server.advice.GrpcExceptionHandler;
import org.springframework.security.access.AccessDeniedException;
import org.springframework.security.core.AuthenticationException;
import org.springframework.security.oauth2.server.resource.InvalidBearerTokenException;
import org.springframework.util.StringUtils;

@GrpcAdvice
@RequiredArgsConstructor
@Slf4j
public class GlobalGrpcExceptionHandler {

    private final MessageSource messageSource;

    @GrpcExceptionHandler(GrpcApiException.class)
    public StatusException handleGrpcApiException(GrpcApiException exception) {
        return Status.fromCode(exception.getStatusCode())
                .withDescription(resolveMessage(exception))
                .asException();
    }

    @GrpcExceptionHandler(GrpcValidationException.class)
    public StatusException handleGrpcValidationException(GrpcValidationException exception) {
        BadRequest.Builder badRequest = BadRequest.newBuilder();
        exception.getViolations().stream()
                .map(this::toFieldViolation)
                .forEach(badRequest::addFieldViolations);

        com.google.rpc.Status status =
                com.google.rpc.Status.newBuilder()
                        .setCode(com.google.rpc.Code.INVALID_ARGUMENT_VALUE)
                        .setMessage(
                                resolveMessage(
                                        "grpc.validation.failed",
                                        "One or more validation errors occurred."))
                        .addDetails(Any.pack(badRequest.build()))
                        .build();

        return StatusProto.toStatusException(status);
    }

    @GrpcExceptionHandler(InvalidBearerTokenException.class)
    public StatusException handleInvalidBearerTokenException(
            InvalidBearerTokenException exception) {
        return Status.UNAUTHENTICATED
                .withDescription(
                        resolveMessage("grpc.auth.invalidToken", "Invalid or expired token."))
                .asException();
    }

    @GrpcExceptionHandler(AuthenticationException.class)
    public StatusException handleAuthenticationException(AuthenticationException exception) {
        return Status.UNAUTHENTICATED
                .withDescription(
                        resolveMessage("grpc.auth.unauthenticated", "Authentication failed."))
                .asException();
    }

    @GrpcExceptionHandler(AccessDeniedException.class)
    public StatusException handleAccessDeniedException(AccessDeniedException exception) {
        return Status.PERMISSION_DENIED
                .withDescription(resolveMessage("grpc.auth.accessDenied", "Access denied."))
                .asException();
    }

    @GrpcExceptionHandler(Exception.class)
    public StatusException handleException(Exception exception) {
        log.error("Unhandled gRPC exception", exception);
        return Status.INTERNAL
                .withDescription(
                        resolveMessage(
                                "grpc.internal",
                                "An unexpected error occurred. Please try again later."))
                .asException();
    }

    private String resolveMessage(GrpcApiException exception) {
        return resolveMessage(
                exception.getMessageCode(),
                exception.getMessage(),
                exception.getMessageArguments());
    }

    private String resolveMessage(
            String messageCode, String defaultMessage, Object... messageArguments) {
        Locale locale = LocaleContextHolder.getLocale();
        return messageSource.getMessage(messageCode, messageArguments, defaultMessage, locale);
    }

    private BadRequest.FieldViolation toFieldViolation(GrpcViolation validationViolation) {
        Violation violation = validationViolation.violation();
        return BadRequest.FieldViolation.newBuilder()
                .setField(resolveField(violation))
                .setDescription(resolveValidationMessage(validationViolation))
                .build();
    }

    private String resolveValidationMessage(GrpcViolation validationViolation) {
        Violation violation = validationViolation.violation();
        String defaultMessage = violation.hasMessage() ? violation.getMessage() : "invalid value";
        return resolveMessage(
                validationViolation.messageCode(),
                defaultMessage,
                validationViolation.messageArguments());
    }

    private static String resolveField(Violation violation) {
        if (!violation.hasField() || violation.getField().getElementsCount() == 0) {
            return resolveMessageLevelField();
        }
        return violation.getField().getElementsList().stream()
                .map(GlobalGrpcExceptionHandler::resolveFieldElement)
                .filter(StringUtils::hasText)
                .reduce((left, right) -> left + "." + right)
                .orElseGet(GlobalGrpcExceptionHandler::resolveMessageLevelField);
    }

    private static String resolveFieldElement(FieldPathElement element) {
        if (element.hasFieldName()) {
            return element.getFieldName();
        }
        if (element.hasFieldNumber()) {
            return String.valueOf(element.getFieldNumber());
        }
        return "";
    }

    private static String resolveMessageLevelField() {
        return "request";
    }
}

Kotlin

package io.github.susimsek.springgrpcsamples.exception

import build.buf.validate.FieldPathElement
import build.buf.validate.Violation
import com.google.protobuf.Any
import com.google.rpc.BadRequest
import io.grpc.Status
import io.grpc.StatusException
import io.grpc.protobuf.StatusProto
import org.slf4j.LoggerFactory
import org.springframework.context.MessageSource
import org.springframework.context.i18n.LocaleContextHolder
import org.springframework.grpc.server.advice.GrpcAdvice
import org.springframework.grpc.server.advice.GrpcExceptionHandler
import org.springframework.security.access.AccessDeniedException
import org.springframework.security.core.AuthenticationException
import org.springframework.security.oauth2.server.resource.InvalidBearerTokenException
import org.springframework.util.StringUtils

@GrpcAdvice
class GlobalGrpcExceptionHandler(
    private val messageSource: MessageSource
) {
    private val log = LoggerFactory.getLogger(javaClass)

    @GrpcExceptionHandler(GrpcApiException::class)
    fun handleGrpcApiException(exception: GrpcApiException): StatusException =
        Status.fromCode(exception.statusCode).withDescription(resolveMessage(exception)).asException()

    @GrpcExceptionHandler(GrpcValidationException::class)
    fun handleGrpcValidationException(exception: GrpcValidationException): StatusException {
        val badRequest = BadRequest.newBuilder()
        exception.violations.map(::toFieldViolation).forEach(badRequest::addFieldViolations)
        val status = com.google.rpc.Status.newBuilder()
            .setCode(com.google.rpc.Code.INVALID_ARGUMENT_VALUE)
            .setMessage(resolveMessage("grpc.validation.failed", "One or more validation errors occurred."))
            .addDetails(Any.pack(badRequest.build()))
            .build()
        return StatusProto.toStatusException(status)
    }

    @GrpcExceptionHandler(InvalidBearerTokenException::class)
    fun handleInvalidBearerTokenException(exception: InvalidBearerTokenException): StatusException =
        Status.UNAUTHENTICATED.withDescription(resolveMessage("grpc.auth.invalidToken", "Invalid or expired token.")).asException()

    @GrpcExceptionHandler(AuthenticationException::class)
    fun handleAuthenticationException(exception: AuthenticationException): StatusException =
        Status.UNAUTHENTICATED.withDescription(resolveMessage("grpc.auth.unauthenticated", "Authentication failed.")).asException()

    @GrpcExceptionHandler(AccessDeniedException::class)
    fun handleAccessDeniedException(exception: AccessDeniedException): StatusException =
        Status.PERMISSION_DENIED.withDescription(resolveMessage("grpc.auth.accessDenied", "Access denied.")).asException()

    @GrpcExceptionHandler(Exception::class)
    fun handleException(exception: Exception): StatusException {
        log.error("Unhandled gRPC exception", exception)
        return Status.INTERNAL.withDescription(resolveMessage("grpc.internal", "An unexpected error occurred. Please try again later.")).asException()
    }

    private fun resolveMessage(exception: GrpcApiException): String =
        resolveMessage(exception.messageCode, exception.message ?: "", *exception.messageArguments)

    private fun resolveMessage(messageCode: String, defaultMessage: String, vararg args: Any?): String =
        messageSource.getMessage(messageCode, args, defaultMessage, LocaleContextHolder.getLocale())

    private fun toFieldViolation(validationViolation: GrpcViolation): BadRequest.FieldViolation =
        BadRequest.FieldViolation.newBuilder()
            .setField(resolveField(validationViolation.violation()))
            .setDescription(resolveValidationMessage(validationViolation))
            .build()

    private fun resolveValidationMessage(validationViolation: GrpcViolation): String {
        val violation = validationViolation.violation()
        val defaultMessage = if (violation.hasMessage()) violation.message else "invalid value"
        return resolveMessage(validationViolation.messageCode(), defaultMessage, *validationViolation.messageArguments())
    }

    private fun resolveField(violation: Violation): String {
        if (!violation.hasField() || violation.field.elementsCount == 0) return "request"
        return violation.field.elementsList.map(::resolveFieldElement).filter(StringUtils::hasText).reduceOrNull { left, right -> "$left.$right" } ?: "request"
    }

    private fun resolveFieldElement(element: FieldPathElement): String =
        when {
            element.hasFieldName() -> element.fieldName
            element.hasFieldNumber() -> element.fieldNumber.toString()
            else -> ""
        }
}

• src/main/java/io/github/susimsek/springgrpcsamples/exception/GrpcApiException.java Defines the base contract for application-level gRPC exceptions with a status code and message metadata.

Java

package io.github.susimsek.springgrpcsamples.exception;

import io.grpc.Status;
import lombok.Getter;

@Getter
public abstract class GrpcApiException extends RuntimeException {

    private final Status.Code statusCode;
    private final String messageCode;
    private final Object[] messageArguments;

    protected GrpcApiException(
            Status.Code statusCode,
            String messageCode,
            String defaultMessage,
            Object... messageArguments) {
        super(defaultMessage);
        this.statusCode = statusCode;
        this.messageCode = messageCode;
        this.messageArguments = messageArguments;
    }
}

Kotlin

package io.github.susimsek.springgrpcsamples.exception

import io.grpc.Status

abstract class GrpcApiException(
    val statusCode: Status.Code,
    val messageCode: String,
    defaultMessage: String,
    vararg val messageArguments: Any?
) : RuntimeException(defaultMessage)

• src/main/java/io/github/susimsek/springgrpcsamples/exception/GrpcValidationException.java Wraps all Protovalidate violations into a single runtime exception handled by the global advice.

Java

package io.github.susimsek.springgrpcsamples.exception;

import java.util.List;
import lombok.Getter;

@Getter
public class GrpcValidationException extends RuntimeException {

    private final List<GrpcViolation> violations;

    public GrpcValidationException(List<GrpcViolation> violations) {
        super("gRPC request validation failed");
        this.violations = List.copyOf(violations);
    }
}

Kotlin

package io.github.susimsek.springgrpcsamples.exception

class GrpcValidationException(
    val violations: List<GrpcViolation>
) : RuntimeException("gRPC request validation failed")

• src/main/java/io/github/susimsek/springgrpcsamples/exception/GrpcViolation.java Normalizes Protovalidate violations into i18n-friendly message codes and arguments.

Java

package io.github.susimsek.springgrpcsamples.exception;

import build.buf.validate.Violation;
import java.util.Arrays;

public record GrpcViolation(Violation violation, String messageCode, Object[] messageArguments) {

    private static final String CUSTOM_RULE_ID_PREFIX = "grpc.";
    private static final String STANDARD_RULE_MESSAGE_CODE_PREFIX = "grpc.validation.constraints.";
    private static final String UNKNOWN_MESSAGE_CODE = "grpc.validation.unknown";

    public static GrpcViolation from(build.buf.protovalidate.Violation violation) {
        Violation proto = violation.toProto();
        Object[] args =
                isStandardRule(proto)
                        ? new Object[] {violation.getRuleValue().getValue()}
                        : new Object[0];
        return new GrpcViolation(proto, resolveMessageCode(proto), args);
    }

    private static boolean isStandardRule(Violation violation) {
        return violation.hasRuleId() && !violation.getRuleId().startsWith(CUSTOM_RULE_ID_PREFIX);
    }

    private static String resolveMessageCode(Violation violation) {
        if (!violation.hasRuleId()) {
            return UNKNOWN_MESSAGE_CODE;
        }
        String ruleId = violation.getRuleId();
        boolean standardRule = !ruleId.startsWith(CUSTOM_RULE_ID_PREFIX);
        return standardRule ? STANDARD_RULE_MESSAGE_CODE_PREFIX + ruleId : ruleId;
    }

    @Override
    public Object[] messageArguments() {
        return messageArguments;
    }

    @Override
    public boolean equals(Object object) {
        if (object == this) {
            return true;
        }
        return object
                        instanceof
                        GrpcViolation(Violation violation1, String code, Object[] arguments)
                && violation.equals(violation1)
                && messageCode.equals(code)
                && Arrays.equals(messageArguments, arguments);
    }

    @Override
    public int hashCode() {
        int result = violation.hashCode();
        result = 31 * result + messageCode.hashCode();
        result = 31 * result + Arrays.hashCode(messageArguments);
        return result;
    }

    @Override
    public String toString() {
        return "GrpcViolation[violation="
                + violation
                + ", messageCode="
                + messageCode
                + ", messageArguments="
                + Arrays.toString(messageArguments)
                + "]";
    }
}

Kotlin

package io.github.susimsek.springgrpcsamples.exception

import build.buf.validate.Violation

data class GrpcViolation(
    val violation: Violation,
    val messageCode: String,
    private val args: Array<out Any?>
) {
    fun messageArguments(): Array<out Any?> = args

    companion object {
        private const val CUSTOM_RULE_ID_PREFIX = "grpc."
        private const val STANDARD_RULE_MESSAGE_CODE_PREFIX = "grpc.validation.constraints."
        private const val UNKNOWN_MESSAGE_CODE = "grpc.validation.unknown"

        fun from(violation: build.buf.protovalidate.Violation): GrpcViolation {
            val proto = violation.toProto()
            val arguments =
                if (isStandardRule(proto)) arrayOf(violation.ruleValue.value) else emptyArray()
            return GrpcViolation(proto, resolveMessageCode(proto), arguments)
        }

        private fun isStandardRule(violation: Violation): Boolean =
            violation.hasRuleId() && !violation.ruleId.startsWith(CUSTOM_RULE_ID_PREFIX)

        private fun resolveMessageCode(violation: Violation): String {
            if (!violation.hasRuleId()) {
                return UNKNOWN_MESSAGE_CODE
            }
            val ruleId = violation.ruleId
            val standardRule = !ruleId.startsWith(CUSTOM_RULE_ID_PREFIX)
            return if (standardRule) STANDARD_RULE_MESSAGE_CODE_PREFIX + ruleId else ruleId
        }
    }
}

• src/main/java/io/github/susimsek/springgrpcsamples/exception/InvalidCredentialsException.java Represents failed login attempts as a gRPC UNAUTHENTICATED application exception.

Java

package io.github.susimsek.springgrpcsamples.exception;

import io.grpc.Status;

public class InvalidCredentialsException extends GrpcApiException {

    public InvalidCredentialsException() {
        super(
                Status.Code.UNAUTHENTICATED,
                "grpc.auth.invalidCredentials",
                "invalid username or password");
    }
}

Kotlin

package io.github.susimsek.springgrpcsamples.exception

import io.grpc.Status

class InvalidCredentialsException : GrpcApiException(
    Status.Code.UNAUTHENTICATED,
    "grpc.auth.invalidCredentials",
    "invalid username or password"
)

• src/main/java/io/github/susimsek/springgrpcsamples/exception/TodoNotFoundException.java Exposes missing records as a gRPC NOT_FOUND failure with the missing Todo ID.

Java

package io.github.susimsek.springgrpcsamples.exception;

import io.grpc.Status;

public class TodoNotFoundException extends GrpcApiException {

    public TodoNotFoundException(Long id) {
        super(
                Status.Code.NOT_FOUND,
                "grpc.todo.notFound",
                "todo not found with id: " + id,
                id.toString());
    }
}

Kotlin

package io.github.susimsek.springgrpcsamples.exception

import io.grpc.Status

class TodoNotFoundException(id: Long) : GrpcApiException(
    Status.Code.NOT_FOUND,
    "grpc.todo.notFound",
    "todo not found with id: $id",
    id.toString()
)

• src/main/java/io/github/susimsek/springgrpcsamples/config/aot/NativeRuntimeHints.java Registers i18n resources, protobuf request classes, and exception handler reflection hints for native builds.

Java

package io.github.susimsek.springgrpcsamples.config.aot;

import io.github.susimsek.springgrpcsamples.exception.GlobalGrpcExceptionHandler;
import java.io.IOException;
import java.util.List;
import java.util.stream.Stream;
import org.springframework.aot.hint.MemberCategory;
import org.springframework.aot.hint.RuntimeHints;
import org.springframework.aot.hint.RuntimeHintsRegistrar;
import org.springframework.aot.hint.TypeReference;
import org.springframework.core.io.Resource;
import org.springframework.core.io.support.PathMatchingResourcePatternResolver;
import org.springframework.core.type.classreading.MetadataReader;
import org.springframework.core.type.classreading.SimpleMetadataReaderFactory;

public class NativeRuntimeHints implements RuntimeHintsRegistrar {

    private static final String APPLICATION_PROTO_REQUEST_PATTERN =
            "classpath*:io/github/susimsek/springgrpcsamples/proto/*Request.class";

    @Override
    public void registerHints(RuntimeHints hints, ClassLoader classLoader) {
        hints.resources().registerPattern("i18n/**");
        hints.reflection()
                .registerTypes(
                        findApplicationProtoRequestTypes(classLoader).stream()
                                .flatMap(
                                        typeName ->
                                                Stream.of(
                                                        TypeReference.of(typeName),
                                                        TypeReference.of(typeName + "$Builder")))
                                .toList(),
                        builder -> builder.withMembers(MemberCategory.INVOKE_PUBLIC_METHODS));
        hints.reflection()
                .registerType(
                        GlobalGrpcExceptionHandler.class, MemberCategory.INVOKE_PUBLIC_METHODS);
    }

    private static List<String> findApplicationProtoRequestTypes(ClassLoader classLoader) {
        PathMatchingResourcePatternResolver resolver =
                new PathMatchingResourcePatternResolver(classLoader);
        SimpleMetadataReaderFactory metadataReaderFactory =
                new SimpleMetadataReaderFactory(classLoader);
        try {
            return Stream.of(resolver.getResources(APPLICATION_PROTO_REQUEST_PATTERN))
                    .filter(Resource::isReadable)
                    .map(resource -> className(resource, metadataReaderFactory))
                    .sorted()
                    .toList();
        } catch (IOException ex) {
            throw new IllegalStateException("Failed to scan application proto request types", ex);
        }
    }

    private static String className(
            Resource resource, SimpleMetadataReaderFactory metadataReaderFactory) {
        try {
            MetadataReader metadataReader = metadataReaderFactory.getMetadataReader(resource);
            return metadataReader.getClassMetadata().getClassName();
        } catch (IOException ex) {
            throw new IllegalStateException("Failed to read proto request metadata", ex);
        }
    }
}

Kotlin

package io.github.susimsek.springgrpcsamples.config.aot

import io.github.susimsek.springgrpcsamples.exception.GlobalGrpcExceptionHandler
import org.springframework.aot.hint.MemberCategory
import org.springframework.aot.hint.RuntimeHints
import org.springframework.aot.hint.RuntimeHintsRegistrar
import org.springframework.aot.hint.TypeReference
import org.springframework.core.io.Resource
import org.springframework.core.io.support.PathMatchingResourcePatternResolver
import org.springframework.core.type.classreading.MetadataReader
import org.springframework.core.type.classreading.SimpleMetadataReaderFactory
import java.io.IOException

class NativeRuntimeHints : RuntimeHintsRegistrar {

    override fun registerHints(hints: RuntimeHints, classLoader: ClassLoader) {
        hints.resources().registerPattern("i18n/**")
        hints.reflection().registerTypes(
            findApplicationProtoRequestTypes(classLoader).flatMap { typeName ->
                listOf(TypeReference.of(typeName), TypeReference.of("${typeName}\$Builder"))
            }
        ) { builder ->
            builder.withMembers(MemberCategory.INVOKE_PUBLIC_METHODS)
        }
        hints.reflection().registerType(
            GlobalGrpcExceptionHandler::class.java,
            MemberCategory.INVOKE_PUBLIC_METHODS
        )
    }

    private fun findApplicationProtoRequestTypes(classLoader: ClassLoader): List<String> {
        val resolver = PathMatchingResourcePatternResolver(classLoader)
        val metadataReaderFactory = SimpleMetadataReaderFactory(classLoader)
        try {
            return resolver.getResources(APPLICATION_PROTO_REQUEST_PATTERN)
                .asSequence()
                .filter(Resource::isReadable)
                .map { resource -> className(resource, metadataReaderFactory) }
                .sorted()
                .toList()
        } catch (ex: IOException) {
            throw IllegalStateException("Failed to scan application proto request types", ex)
        }
    }

    private fun className(
        resource: Resource,
        metadataReaderFactory: SimpleMetadataReaderFactory
    ): String =
        try {
            val metadataReader: MetadataReader = metadataReaderFactory.getMetadataReader(resource)
            metadataReader.classMetadata.className
        } catch (ex: IOException) {
            throw IllegalStateException("Failed to read proto request metadata", ex)
        }

    companion object {
        private const val APPLICATION_PROTO_REQUEST_PATTERN =
            "classpath*:io/github/susimsek/springgrpcsamples/proto/*Request.class"
    }
}

▶️ Run the App

Start the server with the Maven Wrapper:

./mvnw spring-boot:run

grpcurl -plaintext localhost:9090 list

TOKEN=$(grpcurl -plaintext \
  -d '{"username":"admin","password":"admin"}' \
  localhost:9090 \
  AuthService/Login | jq -r '.access_token')

grpcurl -plaintext \
  -rpc-header "authorization: Bearer ${TOKEN}" \
  -d '{"pageRequest":{"page":0,"size":5}}' \
  localhost:9090 \
  TodoService/ListTodos

Expected behavior:

• grpcurl ... list should show AuthService, TodoService, grpc.health.v1.Health, and reflection support.
• AuthService/Login should return access_token, token_type, and expires_in.
• TodoService/ListTodos should work only with a valid bearer token that has the expected authority.
• Invalid payloads should return InvalidArgument with structured field violations.

The repository also uses in-process gRPC transport for integration tests. Its README shows @AutoConfigureTestGrpcTransport and explicit stub registration with @ImportGrpcClients.

🧪 Test gRPC Endpoints

Use grpcurl to exercise both authorization paths: the seeded admin account should complete Todo operations, while user should receive an authorization error.

Admin Flow

Login as admin and capture the JWT token:

grpcurl -plaintext \
  -d '{"username":"admin","password":"admin"}' \
  localhost:9090 \
  AuthService/Login

Expected response:

{
  "accessToken": "<jwt-token>",
  "tokenType": "Bearer",
  "expiresIn": "3600"
}

Use that token to list Todos:

grpcurl -plaintext \
  -rpc-header "authorization: Bearer <jwt-token>" \
  -d '{"pageRequest":{"page":0,"size":5}}' \
  localhost:9090 \
  TodoService/ListTodos

Create a Todo:

grpcurl -plaintext \
  -rpc-header "authorization: Bearer <jwt-token>" \
  -d '{"title":"Write article examples"}' \
  localhost:9090 \
  TodoService/CreateTodo

Patch an existing Todo:

grpcurl -plaintext \
  -rpc-header "authorization: Bearer <jwt-token>" \
  -d '{"id":1,"completed":true}' \
  localhost:9090 \
  TodoService/PatchTodo

Delete a Todo:

grpcurl -plaintext \
  -rpc-header "authorization: Bearer <jwt-token>" \
  -d '{"id":1}' \
  localhost:9090 \
  TodoService/DeleteTodo

User Flow

Login as the lower-privileged user account:

grpcurl -plaintext \
  -d '{"username":"user","password":"user"}' \
  localhost:9090 \
  AuthService/Login

Then try to call an admin-protected RPC:

grpcurl -plaintext \
  -rpc-header "authorization: Bearer <jwt-token>" \
  -d '{"pageRequest":{"page":0,"size":5}}' \
  localhost:9090 \
  TodoService/ListTodos

Expected behavior:

• admin can call every TodoService/* RPC successfully.
• user receives PermissionDenied because the service requires ROLE_ADMIN.
• Invalid credentials return Unauthenticated.

Validation and i18n Check

Send an invalid payload to verify Protovalidate and localized error handling:

grpcurl -plaintext \
  -rpc-header "authorization: Bearer <jwt-token>" \
  -rpc-header "accept-language: tr" \
  -d '{"title":""}' \
  localhost:9090 \
  TodoService/CreateTodo

Expected behavior:

• The RPC fails with InvalidArgument.
• The response details contain structured field violations.
• Validation messages are resolved from messages_tr.properties when accept-language: tr is present.

🏁 Conclusion

The example combines protobuf contracts, JPA persistence, Spring Security, interceptor-based validation, and centralized gRPC error mapping. Before production, move the sample JWT defaults and database settings into secure environment-specific configuration, then add regression tests for the RPC contracts your clients depend on.

In this article, I separate confirmed details from early assumptions, using the official Bandai Namco page as the primary source and the community wiki as a secondary tracking reference.

🌟 Why This Announcement Matters

What makes this announcement notable is not only the sequel label, but the scale implied by the official messaging: broader platform reach, a larger cast, and a stronger emphasis on cinematic match presentation.

• Official page already lists a 2026 release window
• Platform coverage includes console + PC (Steam)
• The reveal messaging emphasizes scale: teams, characters, and cinematic cutscenes
• Gameplay wording suggests a deeper on-field action system rather than a simple roster refresh

📋 Prerequisites

This breakdown is written for readers who already know the Captain Tsubasa anime/manga universe and want a clean, decision-friendly snapshot of what is confirmed today.

• Familiarity with arcade football / anime sports game design
• Interest in launch-platform planning (PS5, Xbox Series X|S, Switch, PC)
• Expectation that early announcement pages may still change before release

🛠️ Official Facts

Start with the official Bandai Namco page. At this stage, it is the most reliable source for release-window, platform, and publisher-facing metadata.

Source links:

• Bandai Namco - CAPTAIN TSUBASA 2: WORLD FIGHTERS
• Captain Tsubasa Fandom Wiki page
• Announcement Trailer (YouTube)

Confirmed on the official page:

• Title: CAPTAIN TSUBASA 2: WORLD FIGHTERS
• Release window: 2026
• Developer listed: Tamsoft Corporation
• Genre listing: Sport (Arcade)
• Feature tag shown: Single-player
• Platforms shown: PlayStation 5, Xbox Series X|S, Steam, Nintendo Switch

The page also includes wishlist/store entry points, media assets, and a news card tied to the reveal announcement dated February 5, 2026.

🛠️ Gameplay Pitch

Even without a full gameplay breakdown, the wording on the official page is enough to outline the intended player experience.

The official overview highlights:

• 22 national teams
• 110+ playable characters
• A “super action soccer” style with constant superhuman plays

The feature section adds more detail:

• 150+ cutscenes/move highlights on the pitch
• New and improved on-field action for passing, dribbling, tackling, and blocking
• A new goalkeeper-versus-shooter interaction system for super shots and blocks

Taken together, these points suggest a cinematic arcade formula that leans into anime spectacle while adding more structured shot-versus-save moments.

🛠️ Community References

The Fandom page is useful as a fast-moving reference hub, but it should still be treated as a secondary source until the official site and storefront pages publish fuller details.

As of February 26, 2026, the Fandom page is helpful for tracking updates, but several areas still appear to be in-progress:

• Story section placeholders are still being filled
• Team listings exist, but coverage may be incomplete
• Gallery/media and metadata sections can update quickly after trailers/news drops

That is normal for a newly announced title. Use the wiki to monitor changes, but verify release-critical details against official sources before making purchase assumptions.

🧪 Key Unknowns

Reveal pages usually lock in the marketing pitch first, while the most purchase-relevant details arrive later. These are the key items to watch next.

• Exact release date (official page currently shows 2026 only)
• Full mode list (single-player is listed, but online/local modes need explicit confirmation)
• Pricing and edition breakdowns by platform/store
• Performance targets on Switch vs PS5/Xbox Series X|S/PC
• Monetization details (the official page already shows ESRB interactive notice for In-Game Purchases)
• Region-specific availability and language support

The official page also lists ESRB-related descriptors such as Mild Violence and Mild Language, which helps set early expectations for the U.S. rating context.

▶️ Tracking Updates

If you want to stay updated without chasing every rumor, this order keeps the signal-to-noise ratio high:

1. Official Bandai Namco game page for platform and release metadata changes
2. Official trailers/media on the game page and store pages
3. Community wiki/Fandom page for aggregated roster/team/story references
4. Store pages (Steam, console storefronts) for pricing, edition, and system requirement updates

If you plan to buy at launch, wishlist the game on your preferred platform and re-check the official page after each trailer or news drop.

🎬 Media

This media section is split into two parts so you can quickly check the official trailer first, then browse the visual gallery snapshots.

Trailer

Gallery

This gallery gives you a quick visual read on the game’s art direction, character presentation, and match effects while the official rollout is still in its early phase.

Source gallery: Captain Tsubasa Fandom Wiki page

Cover art Flying Drive Shot scene Wakabayashi Genzo character art Jito Hiroshi character art Hayabusa Volley scene Neo Tiger Shot scene Tsubasa Ozora character art Misugi Jun character art Heel Lift confrontation scene Drive Shot scene

🏁 Conclusion

Based on the current reveal materials, Captain Tsubasa 2: World Fighters looks like a significantly bigger anime arcade football release with broad platform coverage, a large roster, and a more cinematic gameplay pitch. The practical next step is to track the official Bandai Namco page for the exact release date and full mode breakdown before choosing a launch platform.

This article looks at the game from a current editorial angle: what was officially confirmed at launch, what the edition and DLC structure tells us, and why the game still matters if you are revisiting the series today.

🌟 Why This Game Still Matters

Rise of New Champions was positioned as the first new Captain Tsubasa console game in roughly a decade, and that context still matters. It set the template that later discussions around the franchise continue to reference: anime-faithful presentation, exaggerated super plays, and a clear preference for arcade speed over simulation.

• Official release date on the Bandai Namco Europe page is August 28, 2020
• The official page lists TAMSOFT as developer and Arcade as the genre label
• Platform listing on the official page covers PlayStation 4, Nintendo Switch, and Steam
• The current official page still reflects a sizable edition and DLC footprint, which makes it a useful baseline when comparing later Captain Tsubasa releases

📋 Prerequisites

This breakdown is written for readers who want a practical picture of Rise of New Champions today, not just a launch-day recap.

• Basic familiarity with the Captain Tsubasa anime/manga universe
• Interest in anime-styled arcade football rather than realistic football simulation
• Willingness to check edition/store details carefully, because this game’s content rollout extended beyond the base launch package

🛠️ Official Facts

Start with the Bandai Namco Europe page. For release date, platform support, and official product framing, it remains the cleanest primary source.

Source links:

• Bandai Namco Europe - CAPTAIN TSUBASA: RISE OF NEW CHAMPIONS
• Captain Tsubasa Fandom Wiki page
• Fandom Art gallery
• Fandom Japan gallery reference
• Official trailer embed on Bandai page (YouTube)

Confirmed on the official page:

• Title: CAPTAIN TSUBASA: RISE OF NEW CHAMPIONS
• Release date: 28/08/2020
• Developer: TAMSOFT
• Genre: Arcade
• Platforms shown: PlayStation 4, Nintendo Switch, Steam

The official description also frames the game as the series’ return to consoles after roughly ten years, with an explicit promise of anime spectacle and up-to-date presentation.

🛠️ Gameplay Pitch

The official key-features section makes the game’s direction very clear: this is not a grounded football sim. It is an anime football action game built around visual impact and fast exchanges.

The official page emphasizes:

• Toon shading combined with more realistic effects
• Detailed presentation for signature character styles
• High-speed “arcade football action”
• Simple controls designed to make special moves and highlight plays accessible

That framing is important because it explains both the game’s appeal and its limits. If you want structured, sim-like football, this is the wrong entry point. If you want exaggerated shots, tackles, rivalries, and momentum swings that feel close to the anime, this is exactly the lane the game targets.

🛠️ Editions and DLC

One of the most practical things about the current official page is that it still exposes how much post-launch content was attached to the game.

The page shows multiple editions and related content references, including:

• Champions Edition
• Collector's Edition
• Deluxe Edition
• Legends Edition
• New Hero Edition
• Character Pass: 9 DLC players
• Season Pass Bonus: New Champions Uniform Set
• Deluxe Edition Bonus: V Jump Collaboration Uniform Set

From a player’s perspective, this matters more than marketing nostalgia. If you are buying or replaying the game now, edition structure directly affects how much roster-related and cosmetic content you actually receive.

The official page also still surfaces later DLC/news references such as EPISODE: RISING STARS, which shows that the game’s support window expanded well beyond the base launch moment.

🛠️ Community References

The Fandom page is still useful, especially when you want a single place for roster references, story structure summaries, and archived promotional art. That includes the Art and Japan gallery sections, which are useful visual references when official media blocks rotate over time.

Use it for:

• Aggregated roster/team references
• Story-mode and character reference browsing
• Archived gallery snapshots and regional cover/art references

Use official sources first for:

• Release date and platform confirmation
• Edition/store metadata
• Current DLC/storefront navigation

The right split is simple: official pages for buying facts, community pages for context and archival browsing.

▶️ What to Verify Today

Because this is a 2020 release with layered editions and DLC, the key questions today are not the same as they were at launch.

Check these points first:

1. Which edition is actually available on your preferred platform today
2. Whether the Character Pass or later DLC content is bundled or separate
3. Whether you want the game mainly for arcade match play, series presentation, or collection value
4. Whether the platform you are considering (PS4, Switch, or Steam) is the one you actually want to play long-term

If your goal is to understand the modern Captain Tsubasa console formula before World Fighters, this game still does that job well. If your goal is simply to own the most complete package, edition details matter enough that you should not treat storefront listings as interchangeable.

🎬 Media

This media section starts with the official trailer and then moves into a quick visual gallery built from stable official assets. For additional archived artwork and the Japan cover reference, the Fandom gallery links above remain useful companion sources.

Trailer

Gallery

This gallery gives you a fast read on the game’s visual identity: anime-faithful key art, match presentation frames, and edition packaging that defined the launch period.

Additional reference links:

• Fandom Art gallery
• Fandom Japan cover reference

Tsubasa's Drive Shot Tsubasa's Neo Drive Shot Hyuga's Straight Line Dribble Hyuga's Neo Tiger Shot Hyuga and Tsubasa's Neo Drive Tiger Twin Shot Schneider's Fire Shot Wakabayashi's save Misugi's Slice Shot Misugi's Crystal Overhead Carlos Turn

🏁 Conclusion

Captain Tsubasa: Rise of New Champions is still the clearest modern template for the franchise’s console direction before World Fighters: aggressive arcade pacing, anime-faithful spectacle, and a product structure shaped heavily by editions and DLC. If you are revisiting the series now, the smartest move is to verify edition contents first, then decide whether you want this game as a playable entry point, a collection piece, or a baseline for comparing the next Captain Tsubasa release.

In this post, you’ll learn:

• How to model configuration as a class (Java/Kotlin)
• How to validate configuration at startup
• How profile-specific config files (application-{profile}.yml) override defaults

🌟 Why @ConfigurationProperties?

In this section, we clarify Why @ConfigurationProperties? and summarize the key points you will apply in implementation.

• ✅ Type-safe access to config (IDE autocomplete, refactoring-safe)
• ✅ Group and document related settings under a single prefix
• ✅ Validate misconfigurations early (fail fast on startup)

📋 Prerequisites

In this section, we clarify Prerequisites and summarize the key points you will apply in implementation.

• Java 17+
• Spring Boot 3.x
• Maven or Gradle

🛠️ Step 1: Define configuration in application.yml

Create a namespace (prefix) for your app config, for example app:

app:
  security:
    enabled: true
    token-expiry-seconds: 3600
  allowed-origins:
    - 'https://example.com'
    - 'http://localhost:3000'

🛠️ Step 2: Create a @ConfigurationProperties class

Java

import java.util.List;

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties(prefix = "app")
public class AppProperties {

  private Security security = new Security();
  private List<String> allowedOrigins = List.of();

  public Security getSecurity() {
    return security;
  }

  public void setSecurity(Security security) {
    this.security = security;
  }

  public List<String> getAllowedOrigins() {
    return allowedOrigins;
  }

  public void setAllowedOrigins(List<String> allowedOrigins) {
    this.allowedOrigins = allowedOrigins;
  }

  public static class Security {
    private boolean enabled = true;
    private int tokenExpirySeconds = 3600;

    public boolean isEnabled() {
      return enabled;
    }

    public void setEnabled(boolean enabled) {
      this.enabled = enabled;
    }

    public int getTokenExpirySeconds() {
      return tokenExpirySeconds;
    }

    public void setTokenExpirySeconds(int tokenExpirySeconds) {
      this.tokenExpirySeconds = tokenExpirySeconds;
    }
  }
}

Kotlin

import org.springframework.boot.context.properties.ConfigurationProperties

@ConfigurationProperties(prefix = "app")
data class AppProperties(
  val security: Security = Security(),
  val allowedOrigins: List<String> = emptyList(),
) {
  data class Security(
    val enabled: Boolean = true,
    val tokenExpirySeconds: Int = 3600,
  )
}

🛠️ Step 3: Enable configuration properties

You have two common options:

1. Scan for @ConfigurationProperties types:

import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.ConfigurationPropertiesScan;

@SpringBootApplication
@ConfigurationPropertiesScan
public class DemoApplication {}

2. Register specific classes explicitly:

import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.EnableConfigurationProperties;

@SpringBootApplication
@EnableConfigurationProperties(AppProperties.class)
public class DemoApplication {}

🧪 Step 4: Validate properties at startup (fail fast)

Add validation constraints and annotate the class with @Validated.

Java

import java.util.List;

import jakarta.validation.Valid;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotEmpty;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;

@ConfigurationProperties(prefix = "app")
@Validated
public class AppProperties {

  @Valid
  private Security security = new Security();

  @NotEmpty
  private List<String> allowedOrigins = List.of();

  public Security getSecurity() { return security; }
  public void setSecurity(Security security) { this.security = security; }

  public List<String> getAllowedOrigins() { return allowedOrigins; }
  public void setAllowedOrigins(List<String> allowedOrigins) { this.allowedOrigins = allowedOrigins; }

  public static class Security {
    private boolean enabled = true;

    @Min(60)
    private int tokenExpirySeconds = 3600;

    public boolean isEnabled() { return enabled; }
    public void setEnabled(boolean enabled) { this.enabled = enabled; }

    public int getTokenExpirySeconds() { return tokenExpirySeconds; }
    public void setTokenExpirySeconds(int tokenExpirySeconds) { this.tokenExpirySeconds = tokenExpirySeconds; }
  }
}

Kotlin

import jakarta.validation.Valid
import jakarta.validation.constraints.Min
import jakarta.validation.constraints.NotEmpty
import org.springframework.boot.context.properties.ConfigurationProperties
import org.springframework.validation.annotation.Validated

@ConfigurationProperties(prefix = "app")
@Validated
data class AppProperties(
  @field:Valid
  val security: Security = Security(),

  @field:NotEmpty
  val allowedOrigins: List<String> = emptyList(),
) {
  data class Security(
    val enabled: Boolean = true,

    @field:Min(60)
    val tokenExpirySeconds: Int = 3600,
  )
}

Note: you need a Bean Validation implementation on the classpath (e.g., spring-boot-starter-validation) for these constraints to be enforced.

🛠️ Step 5: Use profile-specific files (application-{profile}.yml)

Spring Boot loads application.yml and then applies profile-specific overrides.

Example:

• application.yml (defaults)
• application-prod.yml (production overrides)

# application-prod.yml
app:
  security:
    enabled: true
  allowed-origins:
    - 'https://mycompany.com'

When multiple profiles are active, profile files are applied with a “last wins” strategy (the last active profile can override earlier ones).

🌟 Tips

In this section, we clarify Tips and summarize the key points you will apply in implementation.

• Prefer @ConfigurationProperties over scattered @Value for anything non-trivial.
• Keep a single AppProperties root per bounded domain (security, mail, storage, etc.).
• Add validation constraints for anything that must not be empty or must be within a safe range.

🏁 Conclusion

You now have a type-safe Spring Boot configuration layer with startup validation and profile-based overrides. As a next step, externalize environment-specific secrets and add configuration tests to catch regressions early.

🌟 Why Use GraphQL + JWE Authentication?

In this section, we clarify Why Use GraphQL + JWE Authentication? and summarize the key points you will apply in implementation.

• Stateless Security: Tokens are self-contained and require no server-side storage.
• GraphQL Flexibility: Secure any query or mutation uniformly.
• Data Precision: Fetch exactly what clients request.
• Integrity: Signed tokens ensure tamper evidence.
• Confidentiality: Encrypted JWTs hide sensitive claims.
• Standards-based: Leverage JOSE, Spring Security, and GraphQL.
• Scalable: Scale horizontally without session replication or sticky sessions.

📋 Prerequisites

In this section, we clarify Prerequisites and summarize the key points you will apply in implementation.

• ☕ Java Development Kit (JDK) 17 or higher
• 📦 Spring Boot 3.2+
• 🔤 IDE (IntelliJ IDEA, Eclipse)
• 🛢️ PostgreSQL (or H2 for dev)

🛠️ Step 1: Add Dependencies

Include these in your pom.xml or build.gradle file.

Maven:

<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-websocket</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.security</groupId>
    <artifactId>spring-security-oauth2-resource-server</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-graphql</artifactId>
  </dependency>
  <dependency>
    <groupId>com.graphql-java</groupId>
    <artifactId>graphql-java-extended-scalars</artifactId>
    <version>22.0</version>
  </dependency>
  <dependency>
    <groupId>org.liquibase</groupId>
    <artifactId>liquibase-core</artifactId>
  </dependency>
  <dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <optional>true</optional>
  </dependency>
  <dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <scope>runtime</scope>
  </dependency>
</dependencies>

<build>
<plugins>
  <plugin>
    <groupId>org.hibernate.orm.tooling</groupId>
    <artifactId>hibernate-enhance-maven-plugin</artifactId>
    <version>${hibernate.version}</version>
    <executions>
      <execution>
        <id>enhance</id>
        <goals>
          <goal>enhance</goal>
        </goals>
        <configuration>
          <enableLazyInitialization>true</enableLazyInitialization>
          <enableDirtyTracking>true</enableDirtyTracking>
          <enableAssociationManagement>true</enableAssociationManagement>
        </configuration>
      </execution>
    </executions>
  </plugin>
  <plugin>
    <groupId>org.graalvm.buildtools</groupId>
    <artifactId>native-maven-plugin</artifactId>
  </plugin>
</plugins>
</build>

Gradle:

dependencies {
  implementation 'org.springframework.boot:spring-boot-starter-web'
  implementation 'org.springframework.boot:spring-boot-starter-websocket'
  implementation 'org.springframework.security:spring-security-oauth2-resource-server'
  implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
  implementation 'org.springframework.boot:spring-boot-starter-graphql'
  implementation 'com.graphql-java:graphql-java-extended-scalars:22.0'
  implementation 'org.liquibase:liquibase-core'
  compileOnly 'org.projectlombok:lombok'
  runtimeOnly 'com.h2database:h2'
}

plugins {
  id 'org.hibernate.orm' version '6.6.13.Final'
  id 'org.graalvm.buildtools.native' version '0.10.6'
}

hibernate {
  enhancement {
    enableAssociationManagement = true
  }
}

🛠️ Step 2: Configuration Files

In this section, we define all of the application- and database-level configuration files required to wire up our Spring Boot app with H2/PostgreSQL, JPA, Liquibase changelogs, initial data loads, JWE key properties and GraphQL schema definitions, and GraalVM native-image reflection config.

• application.yml Holds Spring datasource, H2 console, JPA/Hibernate settings, Liquibase changelog path, GraphQL subscriptions path, and all JWT/JWE keys, issuer, and expiration configurations.

• liquibase/master.xml The Liquibase master changelog, with includes and DBMS-specific properties for H2 and PostgreSQL.

• liquibase/changelog/changelog-user.xml Your core schema changelog defining user_identity, authority, and user_authority_mapping tables, indexes, FKs, and initial <loadData> steps.

• liquibase/data/user.csv Initial user records (UUID, username, bcrypt-hashed password, email, enabled flag, timestamps, auditor).

• liquibase/data/authority.csv Initial authority records (UUID, name, description, timestamps, auditor).

• liquibase/data/user_authority_mapping.csv Initial mapping of users ↔ authorities (composite PK, timestamps, auditor).

• graphql/schema.graphqls GraphQL schema definitions for the API, including custom scalars, query, subscription and mutation types, and DTO definitions.

• META-INF/native-image/liquibase/reflect-config.json Native-image reflection configuration for Liquibase classes to ensure compatibility when building a GraalVM native image.

application.yml

spring:
  datasource:
    url: jdbc:h2:mem:testdb;MODE=PostgreSQL;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE
    driver-class-name: org.h2.Driver
    username: sa
    password: password
  h2:
    console:
      enabled: true
  jpa:
    open-in-view: false
    hibernate:
      ddl-auto: none
    show-sql: true
    properties:
      hibernate.format_sql: true
  liquibase:
    change-log: classpath:liquibase/master.xml
  graphql:
    websocket:
      path: /subscriptions
    graphiql:
      enabled: true
security:
  admin:
    username: admin
    password: adminpass
  user:
    username: user
    password: userpass
  jwt:
    issuer: demo-issuer
    expiration-duration: 3600s
    signing:
      key-id: signing-key
      public-key: |-
        -----BEGIN PUBLIC KEY-----
        MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAjZEcz5itWkDGOSqZdB5P
        JE0ccOCckskp0hN3kQbT1qnv+9/k66jlWgVi4HSTppwdNF/Ylu5u541Qj+Okyg+u
        8o2PvKo5CfgvTDsFLTrZHUXU6hCSGatLAQoeN6lT8wzov2r4DFecXrIqcO6SvMB5
        ecPqsfiTi4trsNKgJ4cWS6gILH62ISd1ipUadfpnUzDMO1OulV0CJNV6bcBk7Es9
        RW6AHfg9j8osSanpwvRM4MJkB0SRxYUnrN9faGpkBZISZJ8TShhaTHEGfSNgKe5y
        8iu+AMGGZu8DYczVmqS3Ske1fq6y5HEGCma7Mo019GmwKeHBo1obuET6cZRygj4y
        twIDAQAB
        -----END PUBLIC KEY-----
      private-key: |-
        -----BEGIN PRIVATE KEY-----
        MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQCNkRzPmK1aQMY5
        Kpl0Hk8kTRxw4JySySnSE3eRBtPWqe/73+TrqOVaBWLgdJOmnB00X9iW7m7njVCP
        46TKD67yjY+8qjkJ+C9MOwUtOtkdRdTqEJIZq0sBCh43qVPzDOi/avgMV5xesipw
        7pK8wHl5w+qx+JOLi2uw0qAnhxZLqAgsfrYhJ3WKlRp1+mdTMMw7U66VXQIk1Xpt
        wGTsSz1FboAd+D2PyixJqenC9EzgwmQHRJHFhSes319oamQFkhJknxNKGFpMcQZ9
        I2Ap7nLyK74AwYZm7wNhzNWapLdKR7V+rrLkcQYKZrsyjTX0abAp4cGjWhu4RPpx
        lHKCPjK3AgMBAAECggEABMo/sNCIMREXA/EqjxDFecN4LmOTOK5A0YBiH9Cc01sd
        qSaavtSQqhqbjV+0bUNEA7UohXbc3s3bx3qa5VFhiIh8sBQMaQdyRkCK/MxMc16d
        BSx5XQ/8MjVO73A1zHgH2g47BWPjgRrDL94KrgNPOO0FoG76QxL9GlcOHzhFa1rf
        xbb2auLBtflKy+5TZNnB/sbFC9ISpWywzfblD2Fsvxupl0vNWtA0Y2rPbKMZRnY+
        V6NC38yxW3HHAdWQRYLGOitM59I0HBgnjQKzTBNIsjPnJA2BSZvMBtQ1e3RQV0qE
        8VVoktZ8A0KDUxqdKWYlGYAY5hIw1y3UUsPRUbS3fQKBgQDAZehu+Kb5Sw+h00Qu
        vViNHDvi0PwmhQrHVpgjrppCnWsTk6FJFm+EBLY+87usXuRCnfZ1semb6P+yjLh2
        bJ9IXIrFAztcyE+7eZfn0H7mHA7E2ICKTjNdKbjy8kHViHpgdXREnAOrFTTk/BqW
        dq+weG2OuxYczWsY4XliWaVyiwKBgQC8XYExpSmoyI37o+jr9405k30tbGUw4X+/
        xYOvSUuafI8IOSLfKTpsvkMN3hxpJO6apIRAjOALbotKUA5FrHQPenuBWOr3mBJT
        euLiaWphqU8YN5dbNd+JhC/Jh5DLhY5FpB2Fv2MKSoF7+onpjDy9pEU5aReeBB0v
        ekUw4nWiBQKBgHxyrnjxP1frFG5xMB4nfZqw04+v7BmiXsl3mqsh6kgCeNtN17pl
        17YGMjfgAdnJ+02XzW5tqRSfDp3YZgy7z//HVD+BCqnGK8SxLu/ULfD73xW2kNZl
        JNYzAZ2r06eiQr4X2x/x5nGIIxGmfDAtDxFPpFX5b6ErwgVy+sgCAoFnAoGAWSpu
        EMEdQk+FnnwNsz2g9YNSuyDXmdb08SOfXWd1yXBzCLJ7RmYuyPEbrsHYcxFPfZap
        ICFPoTm35/qTdvnWiskxE56yw3eSHUBLjF/YQtixn0YZeMy8v0z6jgyFR0I2gdLZ
        QsnBKUrxlm2XwR1oV2Eef7m2u085PZNEk4pvor0CgYA6n060r48/CgRVslAeGder
        fZ3n+2ru8q2UVB38evepjLifn5+tKdFzZ7/NckXMC0NOVzm74qG46VFLMw5TtyT4
        /hRvGSYxA6dMjXy+tcrAns9Isrz2PnYFntlbhU6hw0um809tFunbvITfyeOjAsDW
        stC4thnhzXXT1Y3RfFtYEg==
        -----END PRIVATE KEY-----
    encryption:
      key-id: encryption-key
      public-key: |-
        -----BEGIN PUBLIC KEY-----
        MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtU7Vu4tML8qg9BISaUH0
        BTU0+qkHJS3TUl3R0hEPttZJGf8EgT7bpWqRjdhMC2SYt2ifNF82EgMo/eva1rLn
        wYtCsxjJ7oB4U2m16/JKHtphmMUGhSLgbp+Y8pGAQ+P6u4HLlI0qbL92Syb6QCTr
        nYIlzZ2uUAvUQg/SbuAvdS4kdauZtpMNbhryusMVvILVBC5yUhfLJAkjbU3qWo/n
        2NKPr4kjwwFh6FaAf0HLsXCFmJbPPok6WMZeDqPORPZCt5gU2t04fS7s/2SSbhQ/
        i+7yyT4pl44cUlNLLN3Qo73sai5H90q7Dvmk3M5/YMJB0Ueyb705LHyOO5xA618s
        qQIDAQAB
        -----END PUBLIC KEY-----
      private-key: |-
        -----BEGIN PRIVATE KEY-----
        MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC1TtW7i0wvyqD0
        EhJpQfQFNTT6qQclLdNSXdHSEQ+21kkZ/wSBPtulapGN2EwLZJi3aJ80XzYSAyj9
        69rWsufBi0KzGMnugHhTabXr8koe2mGYxQaFIuBun5jykYBD4/q7gcuUjSpsv3ZL
        JvpAJOudgiXNna5QC9RCD9Ju4C91LiR1q5m2kw1uGvK6wxW8gtUELnJSF8skCSNt
        Tepaj+fY0o+viSPDAWHoVoB/QcuxcIWYls8+iTpYxl4Oo85E9kK3mBTa3Th9Luz/
        ZJJuFD+L7vLJPimXjhxSU0ss3dCjvexqLkf3SrsO+aTczn9gwkHRR7JvvTksfI47
        nEDrXyypAgMBAAECggEAREnJHrY8n9OGA+e6n4KD0mJT7gUz98Dm0yMbIC/k50yW
        hAAVRkjSmd8lq3NIURI2ov342NTznJ0sF1d6OVtxBujY2nP/uqEQsPoj1xaO7Ef8
        cnnjFsooFgJurQ44bVm02mLstqrky8jhWTT5FKfTRqP6cRNu0B9kdu1WqQQvW8a/
        C8xD8XUFzzJFQsEstJ076NjlZNH3EeqFiLxyVdV7tPEJRnOe2V2BAAgda3ByA6Jc
        Nd4xYHTVr5rZ+KES9gaAgb86+S7hNigsxz5Gp58NimLEyz1Qd+d9QCgPRgKOV5Uq
        0ci6c28ZrxW9wa/2CGCpoow1V7hRy1fZ24g2Tz91cQKBgQDbSdP/FQYuem0pUf8u
        mA/niEC8Jz30FW3ix5aqbQ8YRudK48Xy8F7AWnlS0wT2k/Xaeppn9YSPK4HlsNk2
        1gnpNfzdqXpJQtuxcPPeFNzUdXzBrsLXYqtlhOX/afrzqMhp73gkqoxXtqwD7BqN
        VfMcVXsWrEZQrRPBn/RUnnLdJwKBgQDTqUGupm93UlhoPgLXHGF/seQwPPHcU6lS
        SS9l512Ie21B+vZecgO4r77BXJwbY4rZVA5/m+wrsNmsT2f8yfdbs84cBDDWiKy5
        t2Um8zrus+BCIffxc9Fck9/htK33jLLcYwdSAm3a9pJxR9f/kAdredSTGBNJ3W/2
        rfh3cdNprwKBgDi7WfBFRSsjGzi0cPth9cNlubGzyVBrdtlT34PJ4Tzboxz53o1i
        aHEFNxwZYdBVKSbTzzyUBS5xCBMfdKK+LyQ5hmjmXq+zb1jxqvXKmfMRTixhhSDp
        8wO5pTM1/Omqwea+QGvj/5j1tnzxSVFFajbrWoPcH/jhPho6wqBducPDAoGBALOJ
        MEOavZXy7TaO0w3v7uvH0wzvxR/kfw1jMqc3l2j7ePOskmoOQAXaXO3bRjcdOlua
        Jyoq8islOZ4lRMlx7zWD0OKG035GNGzbmRtu2aA8R48RDSVr3jyu2gqznZULbXPv
        M/hmQxSmbhVUoW0PmJubnaqfk0zmXeBaNRXsIS3VAoGBALdsAtqR23PVeL6sYj2l
        dRNTDXpfvjFqJ5NThRO/4mT0CrPHQVj+Mz2bTc/Dxiwi8s8m3L+g23i3hodh/QMb
        Iz+UbcJZBGAKsFbPKGOtj6Bi07y/L11mcuNJzOWe61/JbVmJss0s+N/v3XucK/Ge
        CUaGOccsMO221v6JoBh9J3Hz
        -----END PRIVATE KEY-----

master.xml

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
  xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="
      http://www.liquibase.org/xml/ns/dbchangelog
      http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.9.xsd">

  <!-- H2 defaults -->
  <property name="now" value="now()" dbms="h2"/>
  <property name="floatType" value="float4" dbms="h2"/>
  <property name="uuidType" value="uuid" dbms="h2"/>
  <property name="datetimeType" value="datetime(6)" dbms="h2"/>
  <property name="binaryType" value="LONGVARBINARY" dbms="h2"/>
  <property name="clobType" value="longvarchar" dbms="h2"/>
  <property name="blobType" value="blob" dbms="h2"/>

  <!-- PostgreSQL overrides -->
  <property name="now" value="current_timestamp" dbms="postgresql"/>
  <property name="floatType" value="float4" dbms="postgresql"/>
  <property name="uuidType" value="uuid" dbms="postgresql"/>
  <property name="datetimeType" value="datetime" dbms="postgresql"/>
  <property name="binaryType" value="BYTEA" dbms="postgresql"/>
  <property name="clobType" value="clob" dbms="postgresql"/>
  <property name="blobType" value="blob" dbms="postgresql"/>

  <!-- include the core auth changelog -->
  <include file="classpath:db/changelog/changelog-user.xml"/>

</databaseChangeLog>

changelog-user.xml

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
  xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="
      http://www.liquibase.org/xml/ns/dbchangelog
      http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.9.xsd">

  <changeSet id="20250510-1" author="susimsek">
    <createTable tableName="user_identity">
      <column name="id" type="varchar(36)">
        <constraints primaryKey="true" primaryKeyName="pk_user_identity" nullable="false"/>
      </column>
      <column name="username" type="varchar(50)">
        <constraints nullable="false" unique="true"/>
      </column>
      <column name="password" type="varchar(100)">
        <constraints nullable="false"/>
      </column>
      <column name="email" type="varchar(100)">
        <constraints nullable="false" unique="true"/>
      </column>
      <column name="first_name" type="varchar(50)"/>
      <column name="last_name" type="varchar(50)"/>
      <column name="enabled" type="boolean">
        <constraints nullable="false"/>
      </column>
      <column name="created_at" type="datetime">
        <constraints nullable="false"/>
      </column>
      <column name="created_by" type="varchar(50)">
        <constraints nullable="false"/>
      </column>
      <column name="updated_at" type="datetime"/>
      <column name="updated_by" type="varchar(50)"/>
    </createTable>

    <createIndex indexName="idx_user_identity_username" tableName="user_identity">
      <column name="username"/>
    </createIndex>
    <createIndex indexName="idx_user_identity_email" tableName="user_identity">
      <column name="email"/>
    </createIndex>
  </changeSet>

  <changeSet id="20250510-2" author="susimsek">
    <createTable tableName="authority">
      <column name="id" type="varchar(36)">
        <constraints primaryKey="true" primaryKeyName="pk_authority" nullable="false"/>
      </column>
      <column name="name" type="varchar(50)">
        <constraints nullable="false" unique="true"/>
      </column>
      <column name="description" type="varchar(255)"/>
      <column name="created_at" type="datetime">
        <constraints nullable="false"/>
      </column>
      <column name="created_by" type="varchar(50)">
        <constraints nullable="false"/>
      </column>
      <column name="updated_at" type="datetime"/>
      <column name="updated_by" type="varchar(50)"/>
    </createTable>

    <createIndex indexName="idx_authority_name" tableName="authority">
      <column name="name"/>
    </createIndex>
  </changeSet>

  <changeSet id="20250510-3" author="susimsek">
    <createTable tableName="user_authority_mapping">
      <column name="user_id" type="varchar(36)">
        <constraints nullable="false"/>
      </column>
      <column name="authority_id" type="varchar(36)">
        <constraints nullable="false"/>
      </column>
      <column name="created_at" type="datetime">
        <constraints nullable="false"/>
      </column>
      <column name="created_by" type="varchar(50)">
        <constraints nullable="false"/>
      </column>
      <column name="updated_at" type="datetime"/>
      <column name="updated_by" type="varchar(50)"/>
    </createTable>

    <addPrimaryKey
      tableName="user_authority_mapping"
      columnNames="user_id, authority_id"
      constraintName="pk_user_authority_mapping"/>
  </changeSet>

  <changeSet id="20250510-4" author="susimsek">
    <addForeignKeyConstraint
      baseTableName="user_authority_mapping"
      baseColumnNames="user_id"
      constraintName="fk_user_authority_user"
      referencedTableName="user_identity"
      referencedColumnNames="id"/>
  </changeSet>

  <changeSet id="20250510-5" author="susimsek">
    <addForeignKeyConstraint
      baseTableName="user_authority_mapping"
      baseColumnNames="authority_id"
      constraintName="fk_user_authority_authority"
      referencedTableName="authority"
      referencedColumnNames="id"/>
  </changeSet>

  <changeSet id="20250510-1-data" author="susimsek">
    <loadData
      file="db/data/user.csv"
      separator=";"
      tableName="user_identity">
      <column name="id" type="string"/>
      <column name="username" type="string"/>
      <column name="password" type="string"/>
      <column name="email" type="string"/>
      <column name="first_name" type="string"/>
      <column name="last_name" type="string"/>
      <column name="enabled" type="boolean"/>
      <column name="created_at" type="datetime"/>
      <column name="created_by" type="string"/>
      <column name="updated_at" type="datetime"/>
      <column name="updated_by" type="string"/>
    </loadData>
  </changeSet>

  <changeSet id="20250510-2-data" author="susimsek">
    <loadData
      file="db/data/authority.csv"
      separator=";"
      tableName="authority">
      <column name="id" type="string"/>
      <column name="name" type="string"/>
      <column name="description" type="string"/>
      <column name="created_at" type="datetime"/>
      <column name="created_by" type="string"/>
      <column name="updated_at" type="datetime"/>
      <column name="updated_by" type="string"/>
    </loadData>
  </changeSet>

  <changeSet id="20250510-3-data" author="susimsek">
    <loadData
      file="db/data/user_authority_mapping.csv"
      separator=";"
      tableName="user_authority_mapping">
      <column name="user_id" type="string"/>
      <column name="authority_id" type="string"/>
      <column name="created_at" type="datetime"/>
      <column name="created_by" type="string"/>
      <column name="updated_at" type="datetime"/>
      <column name="updated_by" type="string"/>
    </loadData>
  </changeSet>

</databaseChangeLog>

user.csv

id;username;password;email;first_name;last_name;enabled;created_at;created_by;updated_at;updated_by
a1b2c3d4-e5f6-7890-abcd-ef1234567890;admin;$2a$10$sva6wl8pmGKJE6NIWrxwcuJK1Jaa2I/LOI43iHVpbR4YB8KjGViiK;admin@example.com;Admin;User;true;2025-05-10 12:00:00;system;2025-05-10 12:00:00;system
09876543-21fe-dcba-0987-654321fedcba;user;$2a$10$5Py4PyteLuXEqnGpSigzfu0V55C7Hi7zX18lmh.J8Bpmft.h23voG;user@example.com;Normal;User;true;2025-05-10 12:00:00;system;2025-05-10 12:00:00;system

authority.csv

id;name;description;created_at;created_by;updated_at;updated_by
f47ac10b-58cc-4372-a567-0e02b2c3d479;ROLE_ADMIN;Administrator role;2025-05-10 12:00:00;system;2025-05-10 12:00:00;system
9c858901-8a57-4791-81fe-4c455b099bc9;ROLE_USER;User role;2025-05-10 12:00:00;system;2025-05-10 12:00:00;system

user_authority_mapping.csv

user_id;authority_id;created_at;created_by;updated_at;updated_by
a1b2c3d4-e5f6-7890-abcd-ef1234567890;9c858901-8a57-4791-81fe-4c455b099bc9;2025-05-10 12:00:00;system;2025-05-10 12:00:00;system
a1b2c3d4-e5f6-7890-abcd-ef1234567890;f47ac10b-58cc-4372-a567-0e02b2c3d479;2025-05-10 12:00:00;system;2025-05-10 12:00:00;system
09876543-21fe-dcba-0987-654321fedcba;9c858901-8a57-4791-81fe-4c455b099bc9;2025-05-10 12:00:00;system;2025-05-10 12:00:00;system

schema.graphqls

scalar Long
scalar Date
scalar Instant

type Query {
  helloAll: String!
  helloAdmin: String!
}

type Mutation {
  login(input: LoginInput!): TokenDTO!
  logout: Boolean!
  greet(input: GreetInput!): GreetDTO!
}

type Subscription {
  greetStream(input: GreetInput!): GreetDTO!
  greetStreamAdmin(input: GreetInput!): GreetDTO!
}

input LoginInput {
  username: String!
  password: String!
}

input GreetInput {
  message: String!
}

type TokenDTO {
  accessToken: String!
  tokenType: String!
  accessTokenExpiresIn: Long!
}

type GreetDTO {
  greeting: String!
  timestamp: Instant!
}

reflect-config.json

[
  {
    "name": "liquibase.logging.mdc.MdcManagerFactory",
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.change.core.LoadDataColumnConfig",
    "queryAllPublicMethods": true,
    "allDeclaredMethods": true,
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.command.CommandFactory",
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.changelog.ChangeLogHistoryServiceFactory",
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.datatype.core.BigIntType",
    "allPublicMethods": true,
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.datatype.core.BlobType",
    "allPublicMethods": true,
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.datatype.core.BooleanType",
    "allPublicMethods": true,
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.datatype.core.CharType",
    "allPublicMethods": true,
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.datatype.core.ClobType",
    "allPublicMethods": true,
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.datatype.core.CurrencyType",
    "allPublicMethods": true,
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.datatype.core.DatabaseFunctionType",
    "allPublicMethods": true,
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.datatype.core.DateTimeType",
    "allPublicMethods": true,
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.datatype.core.DateType",
    "allPublicMethods": true,
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.datatype.core.DecimalType",
    "allPublicMethods": true,
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.datatype.core.DoubleType",
    "allPublicMethods": true,
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.datatype.core.FloatType",
    "allPublicMethods": true,
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.datatype.core.IntType",
    "allPublicMethods": true,
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.datatype.core.MediumIntType",
    "allPublicMethods": true,
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.datatype.core.NCharType",
    "allPublicMethods": true,
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.datatype.core.NumberType",
    "allPublicMethods": true,
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.datatype.core.NVarcharType",
    "allPublicMethods": true,
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.datatype.core.SmallIntType",
    "allPublicMethods": true,
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.datatype.core.TimestampType",
    "allPublicMethods": true,
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.datatype.core.TimeType",
    "allPublicMethods": true,
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.datatype.core.TinyIntType",
    "allPublicMethods": true,
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.datatype.core.UnknownType",
    "allPublicMethods": true,
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.datatype.core.UUIDType",
    "allPublicMethods": true,
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.datatype.core.VarcharType",
    "allPublicMethods": true,
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  },
  {
    "name": "liquibase.datatype.core.XMLType",
    "allPublicMethods": true,
    "methods": [{ "name": "<init>", "parameterTypes": [] }]
  }
]

🛠️ Step 3: GraphQL & Security & Database Configuration

In this section, we define the beans and properties RSA keys, HTTP security filters, and JPA repository/auditing setup for JWE‑based authentication, GraalVM native-image runtime hints, GraphQL wiring and custom scalars:

• JwtProperties: Configures JWT issuer, expiration, and signing/encryption key pairs.
• SecurityJwtConfig: Builds RSA keys and JWK sources; configures JWT encoder/decoder, authentication converter, token resolver, and WebSocket interceptor beans.
• SecurityConfig: Integrates DomainUserDetailsService, configures authentication manager, password encoder, and stateless security filter chain with JWE support.
• DatabaseConfig: Enables JPA repositories, auditing, and transaction management.
• GraphQLConfig: Registers custom scalars for GraphQL (Long, Date, Instant).
• InstantScalar: Defines an ISO-8601 Instant scalar for GraphQL.
• NativeConfig: Registers runtime hints for GraalVM native-image, including reflection and resource patterns.

SecurityJwtConfig

Java

package io.github.susimsek.springbootgraphqljwedemo.config;

import com.nimbusds.jose.EncryptionMethod;
import com.nimbusds.jose.JWEAlgorithm;
import com.nimbusds.jose.JWSAlgorithm;
import com.nimbusds.jose.jwk.JWKSet;
import com.nimbusds.jose.jwk.RSAKey;
import com.nimbusds.jose.jwk.source.JWKSource;
import com.nimbusds.jose.proc.JWEDecryptionKeySelector;
import com.nimbusds.jose.proc.JWSVerificationKeySelector;
import com.nimbusds.jose.proc.SecurityContext;
import com.nimbusds.jwt.proc.DefaultJWTProcessor;
import io.github.susimsek.springbootgraphqljwedemo.security.CookieAuthenticationWebSocketInterceptor;
import io.github.susimsek.springbootgraphqljwedemo.security.CookieBearerTokenResolver;
import io.github.susimsek.springbootgraphqljwedemo.security.KeyUtils;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.graphql.server.WebSocketGraphQlInterceptor;
import org.springframework.graphql.server.support.BearerTokenAuthenticationExtractor;
import org.springframework.security.authentication.ProviderManager;
import org.springframework.security.oauth2.jwt.JwtDecoder;
import org.springframework.security.oauth2.jwt.JwtEncoder;
import org.springframework.security.oauth2.jwt.NimbusJwtDecoder;
import org.springframework.security.oauth2.jwt.NimbusJwtEncoder;
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter;
import org.springframework.security.oauth2.server.resource.authentication.JwtGrantedAuthoritiesConverter;
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationProvider;
import org.springframework.security.oauth2.server.resource.web.BearerTokenResolver;

import java.util.List;

import static io.github.susimsek.springbootgraphqljwedemo.security.SecurityUtils.AUTHORITIES_KEY;

@Configuration
public class SecurityJwtConfig {

  private final JwtProperties props;

  public SecurityJwtConfig(JwtProperties props) {
    this.props = props;
  }

  @Bean
  public RSAKey signingKey() throws Exception {
    return KeyUtils.buildRsaKey(
      props.getSigning().getPublicKey(),
      props.getSigning().getPrivateKey(),
      props.getSigning().getKeyId(),
      true
    );
  }

  @Bean
  public RSAKey encryptionKey() throws Exception {
    return KeyUtils.buildRsaKey(
      props.getEncryption().getPublicKey(),
      props.getEncryption().getPrivateKey(),
      props.getEncryption().getKeyId(),
      false
    );
  }

  @Bean
  public JWKSource<SecurityContext> jwkSource(RSAKey signingKey, RSAKey encryptionKey) {
    JWKSet jwkSet = new JWKSet(List.of(signingKey, encryptionKey));
    return (jwkSelector, context) -> jwkSelector.select(jwkSet);
  }

  @Bean
  public JwtDecoder jwtDecoder(JWKSource<SecurityContext> jwkSource) {
    DefaultJWTProcessor<SecurityContext> jwtProcessor = new DefaultJWTProcessor<>();

    jwtProcessor.setJWEKeySelector(new JWEDecryptionKeySelector<>(
      JWEAlgorithm.RSA_OAEP_256,
      EncryptionMethod.A128GCM,
      jwkSource
    ));
    jwtProcessor.setJWSKeySelector(new JWSVerificationKeySelector<>(
      JWSAlgorithm.RS256,
      jwkSource
    ));
    jwtProcessor.setJWTClaimsSetVerifier((claims, ctx) -> {});

    return new NimbusJwtDecoder(jwtProcessor);
  }

  @Bean
  public JwtEncoder jwtEncoder(JWKSource<SecurityContext> jwkSource) {
    return new NimbusJwtEncoder(jwkSource);
  }

  @Bean
  public JwtAuthenticationConverter jwtAuthenticationConverter() {
    JwtGrantedAuthoritiesConverter converter = new JwtGrantedAuthoritiesConverter();
    converter.setAuthorityPrefix("");
    converter.setAuthoritiesClaimName(AUTHORITIES_KEY);

    JwtAuthenticationConverter authConverter = new JwtAuthenticationConverter();
    authConverter.setJwtGrantedAuthoritiesConverter(converter);
    return authConverter;
  }

  @Bean
  public BearerTokenResolver bearerTokenResolver() {
    CookieBearerTokenResolver resolver = new CookieBearerTokenResolver();
    resolver.setAllowUriQueryParameter(false);
    resolver.setAllowFormEncodedBodyParameter(false);
    resolver.setAllowCookie(true);
    return resolver;
  }

  @Bean
  public WebSocketGraphQlInterceptor authenticationInterceptor(JwtDecoder jwtDecoder) {
    return new CookieAuthenticationWebSocketInterceptor(
      new BearerTokenAuthenticationExtractor(),
      new ProviderManager(new JwtAuthenticationProvider(jwtDecoder))
    );
  }
}

Kotlin

package io.github.susimsek.springbootgraphqljwedemo.config

import com.nimbusds.jose.EncryptionMethod
import com.nimbusds.jose.JWEAlgorithm
import com.nimbusds.jose.JWSAlgorithm
import com.nimbusds.jose.jwk.JWKSet
import com.nimbusds.jose.jwk.RSAKey
import com.nimbusds.jose.jwk.source.JWKSource
import com.nimbusds.jose.proc.JWEDecryptionKeySelector
import com.nimbusds.jose.proc.JWSVerificationKeySelector
import com.nimbusds.jose.proc.SecurityContext
import com.nimbusds.jwt.proc.DefaultJWTProcessor
import io.github.susimsek.springbootgraphqljwedemo.security.CookieAuthenticationWebSocketInterceptor
import io.github.susimsek.springbootgraphqljwedemo.security.CookieBearerTokenResolver
import io.github.susimsek.springbootgraphqljwedemo.security.KeyUtils
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.graphql.server.WebSocketGraphQlInterceptor
import org.springframework.graphql.server.support.BearerTokenAuthenticationExtractor
import org.springframework.security.authentication.ProviderManager
import org.springframework.security.oauth2.jwt.JwtDecoder
import org.springframework.security.oauth2.jwt.JwtEncoder
import org.springframework.security.oauth2.jwt.NimbusJwtDecoder
import org.springframework.security.oauth2.jwt.NimbusJwtEncoder
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter
import org.springframework.security.oauth2.server.resource.authentication.JwtGrantedAuthoritiesConverter
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationProvider
import org.springframework.security.oauth2.server.resource.web.BearerTokenResolver

@Configuration
class SecurityJwtConfig(
  private val props: JwtProperties
) {

  @Bean
  @Throws(Exception::class)
  fun signingKey(): RSAKey = KeyUtils.buildRsaKey(
    props.signing.publicKey,
    props.signing.privateKey,
    props.signing.keyId,
    true
  )

  @Bean
  @Throws(Exception::class)
  fun encryptionKey(): RSAKey = KeyUtils.buildRsaKey(
    props.encryption.publicKey,
    props.encryption.privateKey,
    props.encryption.keyId,
    false
  )

  @Bean
  fun jwkSource(
    signingKey: RSAKey,
    encryptionKey: RSAKey
  ): JWKSource<SecurityContext> {
    val jwkSet = JWKSet(listOf(signingKey, encryptionKey))
    return JWKSource { jwkSelector, _ -> jwkSelector.select(jwkSet) }
  }

  @Bean
  fun jwtDecoder(jwkSource: JWKSource<SecurityContext>): JwtDecoder {
    val processor = DefaultJWTProcessor<SecurityContext>().apply {
      setJWEKeySelector(JWEDecryptionKeySelector(
        JWEAlgorithm.RSA_OAEP_256,
        EncryptionMethod.A128GCM,
        jwkSource
      ))
      setJWSKeySelector(JWSVerificationKeySelector(
        JWSAlgorithm.RS256,
        jwkSource
      ))
      setJWTClaimsSetVerifier { _, _ -> }
    }
    return NimbusJwtDecoder(processor)
  }

  @Bean
  fun jwtEncoder(jwkSource: JWKSource<SecurityContext>): JwtEncoder =
    NimbusJwtEncoder(jwkSource)

  @Bean
  fun jwtAuthenticationConverter(): JwtAuthenticationConverter {
    val granted = JwtGrantedAuthoritiesConverter().apply {
      authorityPrefix = ""
      authoritiesClaimName = SecurityUtils.AUTHORITIES_KEY
    }
    return JwtAuthenticationConverter().apply {
      setJwtGrantedAuthoritiesConverter(granted)
    }
  }

  @Bean
  fun bearerTokenResolver(): BearerTokenResolver =
    CookieBearerTokenResolver().apply {
      setAllowUriQueryParameter(false)
      setAllowFormEncodedBodyParameter(false)
      setAllowCookie(true)
    }

  @Bean
  fun authenticationInterceptor(jwtDecoder: JwtDecoder): WebSocketGraphQlInterceptor =
    CookieAuthenticationWebSocketInterceptor(
      BearerTokenAuthenticationExtractor(),
      ProviderManager(JwtAuthenticationProvider(jwtDecoder))
    )
}

SecurityConfig

Java

package io.github.susimsek.springbootgraphqljwedemo.config;

import io.github.susimsek.springbootgraphqljwedemo.repository.UserRepository;
import io.github.susimsek.springbootgraphqljwedemo.security.DomainUserDetailsService;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.ProviderManager;
import org.springframework.security.authentication.dao.DaoAuthenticationProvider;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.servlet.util.matcher.MvcRequestMatcher;
import org.springframework.web.servlet.handler.HandlerMappingIntrospector;

import static org.springframework.security.config.Customizer.withDefaults;

@Configuration
@EnableMethodSecurity(securedEnabled = true)
public class SecurityConfig {

  @Bean
  public SecurityFilterChain securityFilterChain(HttpSecurity http,
                                                 MvcRequestMatcher.Builder mvc) throws Exception {
    http
      .cors(withDefaults())
      .csrf(AbstractHttpConfigurer::disable)
      .authorizeHttpRequests(authz ->
        authz
          .requestMatchers(
            mvc.pattern("/webjars/**"),
            mvc.pattern("/css/**"),
            mvc.pattern("/js/**")
          ).permitAll()
          .requestMatchers(
            mvc.pattern("/*.ico"),
            mvc.pattern("/*.png"),
            mvc.pattern("/*.svg"),
            mvc.pattern("/*.webapp")
          ).permitAll()
          .requestMatchers("/actuator/**").permitAll()
          .requestMatchers(
            "/v3/api-docs/**",
            "/swagger-ui.html",
            "/swagger-ui/**"
          ).permitAll()
          .requestMatchers(
            mvc.pattern("/graphql"),
            mvc.pattern("/graphiql"),
            mvc.pattern("/subscriptions")
          ).permitAll()
          .anyRequest().authenticated()
      )
      .sessionManagement(session ->
        session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
      .oauth2ResourceServer(oauth2 -> oauth2
        .jwt(withDefaults())
      );

    return http.build();
  }

  @Bean
  public UserDetailsService userDetailsService(UserRepository userRepository) {
    return new DomainUserDetailsService(userRepository);
  }

  @Bean
  public PasswordEncoder passwordEncoder() {
    return new BCryptPasswordEncoder();
  }

  @Bean
  public AuthenticationManager authenticationManager(
    UserDetailsService userDetailsService,
    PasswordEncoder passwordEncoder) {
    DaoAuthenticationProvider provider = new DaoAuthenticationProvider();
    provider.setUserDetailsService(userDetailsService);
    provider.setPasswordEncoder(passwordEncoder);
    return new ProviderManager(provider);
  }

  @Bean
  public MvcRequestMatcher.Builder mvc(HandlerMappingIntrospector introspector) {
    return new MvcRequestMatcher.Builder(introspector);
  }
}

Kotlin

package io.github.susimsek.springbootgraphqljwedemo.config

import io.github.susimsek.springbootgraphqljwedemo.repository.UserRepository
import io.github.susimsek.springbootgraphqljwedemo.security.DomainUserDetailsService
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.security.authentication.AuthenticationManager
import org.springframework.security.authentication.ProviderManager
import org.springframework.security.authentication.dao.DaoAuthenticationProvider
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity
import org.springframework.security.config.annotation.web.builders.HttpSecurity
import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer
import org.springframework.security.config.http.SessionCreationPolicy
import org.springframework.security.core.userdetails.UserDetailsService
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder
import org.springframework.security.crypto.password.PasswordEncoder
import org.springframework.security.web.SecurityFilterChain
import org.springframework.security.web.servlet.util.matcher.MvcRequestMatcher
import org.springframework.web.servlet.handler.HandlerMappingIntrospector
import org.springframework.security.config.Customizer.withDefaults

@Configuration
@EnableMethodSecurity(securedEnabled = true)
class SecurityConfig {

  @Bean
  @Throws(Exception::class)
  fun securityFilterChain(
    http: HttpSecurity,
    mvc: MvcRequestMatcher.Builder
  ): SecurityFilterChain {
    http
      .cors(withDefaults())
      .csrf { it.disable() }
      .authorizeHttpRequests { authz ->
        authz
          .requestMatchers(
            mvc.pattern("/webjars/**"),
            mvc.pattern("/css/**"),
            mvc.pattern("/js/**")
          ).permitAll()
          .requestMatchers(
            mvc.pattern("/*.ico"),
            mvc.pattern("/*.png"),
            mvc.pattern("/*.svg"),
            mvc.pattern("/*.webapp")
          ).permitAll()
          .requestMatchers("/actuator/**").permitAll()
          .requestMatchers(
            "/v3/api-docs/**",
            "/swagger-ui.html",
            "/swagger-ui/**"
          ).permitAll()
          .requestMatchers(
            mvc.pattern("/graphql"),
            mvc.pattern("/graphiql"),
            mvc.pattern("/subscriptions")
          ).permitAll()
          .anyRequest().authenticated()
      }
      .sessionManagement {
        it.sessionCreationPolicy(SessionCreationPolicy.STATELESS)
      }
      .oauth2ResourceServer {
        it.jwt(withDefaults())
      }

    return http.build()
  }

  @Bean
  fun userDetailsService(userRepository: UserRepository): UserDetailsService =
    DomainUserDetailsService(userRepository)

  @Bean
  fun passwordEncoder(): PasswordEncoder = BCryptPasswordEncoder()

  @Bean
  fun authenticationManager(
    userDetailsService: UserDetailsService,
    passwordEncoder: PasswordEncoder
  ): AuthenticationManager {
    val provider = DaoAuthenticationProvider().apply {
      setUserDetailsService(userDetailsService)
      setPasswordEncoder(passwordEncoder)
    }
    return ProviderManager(provider)
  }

  @Bean
  fun mvc(introspector: HandlerMappingIntrospector): MvcRequestMatcher.Builder =
    MvcRequestMatcher.Builder(introspector)
}

JwtProperties

Java

package io.github.susimsek.springbootgraphqljwedemo.config;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;

import java.time.Duration;

@Configuration
@ConfigurationProperties(prefix = "security.jwt")
@Data
public class JwtProperties {

    @Data
    public static class Pair {
        private String publicKey;
        private String privateKey;
        private String keyId;
    }

    private Pair signing;
    private Pair encryption;
    private String issuer;
    private Duration expirationDuration;
}

Kotlin

package io.github.susimsek.springbootgraphqljwedemo.config

import org.springframework.boot.context.properties.ConfigurationProperties
import org.springframework.context.annotation.Configuration
import java.time.Duration

@Configuration
@ConfigurationProperties(prefix = "security.jwt")
class JwtProperties {

  class Pair {
    lateinit var publicKey: String
    lateinit var privateKey: String
    lateinit var keyId: String
  }

  lateinit var signing: Pair
  lateinit var encryption: Pair
  lateinit var issuer: String
  lateinit var expirationDuration: Duration
}

DatabaseConfig

Java

package io.github.susimsek.springbootgraphqljwedemo.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.data.jpa.repository.config.EnableJpaAuditing;
import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
import org.springframework.transaction.annotation.EnableTransactionManagement;

@Configuration
@EnableJpaRepositories("io.github.susimsek.springbootgraphqljwedemo.repository")
@EnableJpaAuditing(auditorAwareRef = "springSecurityAuditorAware")
@EnableTransactionManagement
public class DatabaseConfig {

}

Kotlin

package io.github.susimsek.springbootgraphqljwedemo.config

import org.springframework.context.annotation.Configuration
import org.springframework.data.jpa.repository.config.EnableJpaAuditing
import org.springframework.data.jpa.repository.config.EnableJpaRepositories
import org.springframework.transaction.annotation.EnableTransactionManagement

@Configuration
@EnableJpaRepositories("io.github.susimsek.springbootgraphqljwedemo.repository")
@EnableJpaAuditing(auditorAwareRef = "springSecurityAuditorAware")
@EnableTransactionManagement
class DatabaseConfig

GraphQLConfig

Java

package io.github.susimsek.springbootgraphqljwedemo.config;

import graphql.scalars.ExtendedScalars;
import io.github.susimsek.springbootgraphqljwedemo.scalar.InstantScalar;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.graphql.execution.RuntimeWiringConfigurer;

@Configuration
public class GraphQLConfig {

  @Bean
  public RuntimeWiringConfigurer runtimeWiringConfigurer() {
    return wiring -> wiring
      .scalar(ExtendedScalars.GraphQLLong)
      .scalar(ExtendedScalars.Date)
      .scalar(InstantScalar.INSTANCE);
  }
}

Kotlin

package io.github.susimsek.springbootgraphqljwedemo.config

import graphql.scalars.ExtendedScalars
import io.github.susimsek.springbootgraphqljwedemo.scalar.InstantScalar
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.graphql.execution.RuntimeWiringConfigurer

@Configuration
class GraphQLConfig {

  @Bean
  fun runtimeWiringConfigurer(): RuntimeWiringConfigurer {
    return RuntimeWiringConfigurer { wiring ->
      wiring
        .scalar(ExtendedScalars.GraphQLLong)
        .scalar(ExtendedScalars.Date)
        .scalar(InstantScalar.INSTANCE)
    }
  }
}

InstantScalar

Java

package io.github.susimsek.springbootgraphqljwedemo.scalar;

import graphql.GraphQLContext;
import graphql.execution.CoercedVariables;
import graphql.language.StringValue;
import graphql.language.Value;
import graphql.scalars.util.Kit;
import graphql.schema.Coercing;
import graphql.schema.CoercingParseLiteralException;
import graphql.schema.CoercingParseValueException;
import graphql.schema.CoercingSerializeException;
import graphql.schema.GraphQLScalarType;
import lombok.AccessLevel;
import lombok.NoArgsConstructor;
import org.springframework.lang.NonNull;

import java.time.Instant;
import java.time.format.DateTimeParseException;
import java.util.Locale;

@NoArgsConstructor(access = AccessLevel.PRIVATE)
public final class InstantScalar {

  public static final GraphQLScalarType INSTANCE;

  static {
    Coercing<Instant, String> coercing = new Coercing<>() {
      @Override
      public String serialize(
        @NonNull Object input,
        @NonNull GraphQLContext context,
        @NonNull Locale locale
      ) throws CoercingSerializeException {
        if (input instanceof Instant instant) {
          return instant.toString();
        }
        throw new CoercingSerializeException(
          "Expected java.time.Instant but was: " + Kit.typeName(input) + "'."
        );
      }

      @Override
      public Instant parseValue(
        @NonNull Object input,
        @NonNull GraphQLContext context,
        @NonNull Locale locale
      ) throws CoercingParseValueException {
        if (input instanceof String s) {
          try {
            return Instant.parse(s);
          } catch (DateTimeParseException e) {
            throw new CoercingParseValueException("Invalid Instant value: " + e.getMessage() + "'.");
          }
        }
        throw new CoercingParseValueException(
          "Expected a String for Instant but was: " + Kit.typeName(input) + "'."
        );
      }

      @Override
      public Instant parseLiteral(
        @NonNull Value<?> input,
        @NonNull CoercedVariables variables,
        @NonNull GraphQLContext context,
        @NonNull Locale locale
      ) throws CoercingParseLiteralException {
        if (input instanceof StringValue sv) {
          String s = sv.getValue();
          try {
            return Instant.parse(s);
          } catch (DateTimeParseException e) {
            throw new CoercingParseLiteralException("Invalid Instant literal: " + e.getMessage() + "'");
          }
        }
        throw new CoercingParseLiteralException(
          "Expected AST type 'StringValue' but was: " + Kit.typeName(input) + "'."
        );
      }

      @Override
      @NonNull
      public Value<?> valueToLiteral(
        @NonNull Object input,
        @NonNull GraphQLContext context,
        @NonNull Locale locale
      ) {
        String serialized = serialize(input, context, locale);
        return StringValue.newStringValue(serialized).build();
      }
    };

    INSTANCE = GraphQLScalarType.newScalar()
      .name("Instant")
      .description("An ISO-8601 compliant java.time.Instant scalar")
      .specifiedByUrl("https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6")
      .coercing(coercing)
      .build();
  }
}

Kotlin

package io.github.susimsek.springbootgraphqljwedemo.scalar

import graphql.GraphQLContext
import graphql.execution.CoercedVariables
import graphql.language.StringValue
import graphql.language.Value
import graphql.scalars.util.Kit
import graphql.schema.Coercing
import graphql.schema.CoercingParseLiteralException
import graphql.schema.CoercingParseValueException
import graphql.schema.CoercingSerializeException
import graphql.schema.GraphQLScalarType
import java.time.Instant
import java.time.format.DateTimeParseException
import java.util.Locale

object InstantScalar {

  @JvmField
  val INSTANCE: GraphQLScalarType = GraphQLScalarType.newScalar()
    .name("Instant")
    .description("An ISO-8601 compliant java.time.Instant scalar")
    .specifiedByUrl("https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6")
    .coercing(object : Coercing<Instant, String> {
      override fun serialize(
        input: Any,
        context: GraphQLContext,
        locale: Locale
      ): String {
        return if (input is Instant) {
          input.toString()
        } else {
          throw CoercingSerializeException("Expected java.time.Instant but was: ${Kit.typeName(input)}'.")
        }
      }

      override fun parseValue(
        input: Any,
        context: GraphQLContext,
        locale: Locale
      ): Instant {
        if (input is String) {
          return try {
            Instant.parse(input)
          } catch (e: DateTimeParseException) {
            throw CoercingParseValueException("Invalid Instant value: ${e.message}'.")
          }
        }
        throw CoercingParseValueException("Expected a String for Instant but was: ${Kit.typeName(input)}'.")
      }

      override fun parseLiteral(
        input: Value<*>,
        variables: CoercedVariables,
        context: GraphQLContext,
        locale: Locale
      ): Instant {
        if (input is StringValue) {
          return try {
            Instant.parse(input.value)
          } catch (e: DateTimeParseException) {
            throw CoercingParseLiteralException("Invalid Instant literal: ${e.message}'")
          }
        }
        throw CoercingParseLiteralException("Expected AST type 'StringValue' but was: ${Kit.typeName(input)}'.")
      }

      override fun valueToLiteral(
        input: Any,
        context: GraphQLContext,
        locale: Locale
      ): Value<*> {
        val serialized = serialize(input, context, locale)
        return StringValue.newStringValue(serialized).build()
      }
    })
    .build()
}

NativeConfig

Java

package io.github.susimsek.springbootgraphqljwedemo.config;

import org.springframework.aot.hint.MemberCategory;
import org.springframework.aot.hint.RuntimeHints;
import org.springframework.aot.hint.RuntimeHintsRegistrar;

public class NativeConfig {

  public static class AppNativeRuntimeHints implements RuntimeHintsRegistrar {

    @Override
    public void registerHints(RuntimeHints hints, ClassLoader classLoader) {
      hints.reflection()
        .registerType(sun.misc.Unsafe.class,
          hint -> hint.withMembers(MemberCategory.INVOKE_PUBLIC_METHODS));
      hints.reflection()
        .registerType(java.util.Locale.class,
          hint -> hint.withMembers(MemberCategory.INVOKE_PUBLIC_METHODS));
      hints.reflection()
        .registerType(org.hibernate.binder.internal.BatchSizeBinder.class,
          hint -> hint.withMembers(MemberCategory.INVOKE_PUBLIC_CONSTRUCTORS));
      hints.resources().registerPattern("liquibase/*");
      hints.reflection()
        .registerType(liquibase.ui.LoggerUIService.class,
          hint -> hint.withMembers(MemberCategory.INVOKE_PUBLIC_CONSTRUCTORS));
      hints.reflection()
        .registerType(liquibase.database.LiquibaseTableNamesFactory.class,
          hint -> hint.withMembers(MemberCategory.INVOKE_DECLARED_CONSTRUCTORS));
      hints.reflection()
        .registerType(liquibase.report.ShowSummaryGeneratorFactory.class,
          hint -> hint.withMembers(MemberCategory.INVOKE_DECLARED_CONSTRUCTORS));
      hints.reflection()
        .registerType(liquibase.changelog.FastCheckService.class,
          hint -> hint.withMembers(MemberCategory.INVOKE_DECLARED_CONSTRUCTORS));
      hints.reflection()
        .registerType(liquibase.changelog.visitor.ValidatingVisitorGeneratorFactory.class,
          hint -> hint.withMembers(MemberCategory.INVOKE_DECLARED_CONSTRUCTORS));
    }
  }
}

Kotlin

package io.github.susimsek.springbootgraphqljwedemo.config

import org.springframework.aot.hint.MemberCategory
import org.springframework.aot.hint.RuntimeHints
import org.springframework.aot.hint.RuntimeHintsRegistrar

class NativeConfig {

  class AppNativeRuntimeHints : RuntimeHintsRegistrar {
    override fun registerHints(hints: RuntimeHints, classLoader: ClassLoader) {
      hints.reflection().registerType(
        sun.misc.Unsafe::class.java,
        hint = hint@{ it.withMembers(MemberCategory.INVOKE_PUBLIC_METHODS) }
      )
      hints.reflection().registerType(
        java.util.Locale::class.java,
        hint = hint@{ it.withMembers(MemberCategory.INVOKE_PUBLIC_METHODS) }
      )
      hints.reflection().registerType(
        org.hibernate.binder.internal.BatchSizeBinder::class.java,
        hint = hint@{ it.withMembers(MemberCategory.INVOKE_PUBLIC_CONSTRUCTORS) }
      )
      hints.resources().registerPattern("liquibase/*")
      hints.reflection().registerType(
        liquibase.ui.LoggerUIService::class.java,
        hint = hint@{ it.withMembers(MemberCategory.INVOKE_PUBLIC_CONSTRUCTORS) }
      )
      hints.reflection().registerType(
        liquibase.database.LiquibaseTableNamesFactory::class.java,
        hint = hint@{ it.withMembers(MemberCategory.INVOKE_DECLARED_CONSTRUCTORS) }
      )
      hints.reflection().registerType(
        liquibase.report.ShowSummaryGeneratorFactory::class.java,
        hint = hint@{ it.withMembers(MemberCategory.INVOKE_DECLARED_CONSTRUCTORS) }
      )
      hints.reflection().registerType(
        liquibase.changelog.FastCheckService::class.java,
        hint = hint@{ it.withMembers(MemberCategory.INVOKE_DECLARED_CONSTRUCTORS) }
      )
      hints.reflection().registerType(
        liquibase.changelog.visitor.ValidatingVisitorGeneratorFactory::class.java,
        hint = hint@{ it.withMembers(MemberCategory.INVOKE_DECLARED_CONSTRUCTORS) }
      )
    }
  }
}

Main

Java

package io.github.susimsek.springbootgraphqljwedemo;

import io.github.susimsek.springbootgraphqljwedemo.config.NativeConfig;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ImportRuntimeHints;

@SpringBootApplication
@ImportRuntimeHints({ NativeConfig.AppNativeRuntimeHints.class })
public class SpringBootJweAuthJpaDemoApplication {

  public static void main(String[] args) {
    SpringApplication.run(SpringBootJweAuthJpaDemoApplication.class, args);
  }

}

Kotlin

package io.github.susimsek.springbootgraphqljwedemo

import io.github.susimsek.springbootgraphqljwedemo.config.NativeConfig
import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.context.annotation.ImportRuntimeHints

@SpringBootApplication
@ImportRuntimeHints(NativeConfig.AppNativeRuntimeHints::class)
class SpringBootJweAuthJpaDemoApplication

fun main(args: Array<String>) {
  runApplication<SpringBootJweAuthJpaDemoApplication>(*args)
}

🛠️ Step 4: JPA Integration

In this section, we define the JPA entities representing users, authorities, and their mappings, along with the Spring Data repository for loading users with their authorities.

• BaseEntity: Abstract superclass providing audit fields (createdAt, createdBy, updatedAt, updatedBy).
• Authority: authority table entity storing role data.
• User: user_identity table entity storing user credentials and profile.
• UserAuthorityMapping: user_authority_mapping join table entity linking users and authorities.
• UserAuthorityMappingId: Composite key class for UserAuthorityMapping.
• UserRepository: Spring Data JPA repository for User with an entity graph to load authorities.

BaseEntity

Java

package io.github.susimsek.springbootgraphqljwedemo.entity;

import jakarta.persistence.Column;
import jakarta.persistence.EntityListeners;
import jakarta.persistence.MappedSuperclass;
import lombok.Getter;
import lombok.Setter;
import org.springframework.data.annotation.CreatedBy;
import org.springframework.data.annotation.CreatedDate;
import org.springframework.data.annotation.LastModifiedBy;
import org.springframework.data.annotation.LastModifiedDate;
import org.springframework.data.jpa.domain.support.AuditingEntityListener;

import java.time.Instant;

@MappedSuperclass
@EntityListeners(AuditingEntityListener.class)
@Getter
@Setter
public abstract class BaseEntity {

  @CreatedDate
  @Column(name = "created_at", nullable = false, updatable = false)
  private Instant createdAt;

  @CreatedBy
  @Column(name = "created_by", nullable = false, updatable = false, length = 50)
  private String createdBy;

  @LastModifiedDate
  @Column(name = "updated_at")
  private Instant updatedAt;

  @LastModifiedBy
  @Column(name = "updated_by", length = 50)
  private String updatedBy;
}

Kotlin

package io.github.susimsek.springbootgraphqljwedemo.entity

import jakarta.persistence.Column
import jakarta.persistence.EntityListeners
import jakarta.persistence.MappedSuperclass
import org.springframework.data.annotation.CreatedBy
import org.springframework.data.annotation.CreatedDate
import org.springframework.data.annotation.LastModifiedBy
import org.springframework.data.annotation.LastModifiedDate
import org.springframework.data.jpa.domain.support.AuditingEntityListener
import java.time.Instant

@MappedSuperclass
@EntityListeners(AuditingEntityListener::class)
abstract class BaseEntity {

  @CreatedDate
  @Column(name = "created_at", nullable = false, updatable = false)
  lateinit var createdAt: Instant

  @CreatedBy
  @Column(name = "created_by", nullable = false, updatable = false, length = 50)
  lateinit var createdBy: String

  @LastModifiedDate
  @Column(name = "updated_at")
  var updatedAt: Instant? = null

  @LastModifiedBy
  @Column(name = "updated_by", length = 50)
  var updatedBy: String? = null
}

Authority

Java

package io.github.susimsek.springbootgraphqljwedemo.entity;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.persistence.Table;
import lombok.AllArgsConstructor;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;
import org.hibernate.proxy.HibernateProxy;

import java.util.Objects;

@Entity
@Table(name = "authority")
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class Authority extends BaseEntity {

  @Id
  @Column(length = 36, nullable = false)
  private String id;

  @Column(length = 50, nullable = false, unique = true)
  private String name;

  @Column(length = 255)
  private String description;

  @Override
  public final boolean equals(Object obj) {
    if (this == obj) {
      return true;
    }
    if (!(obj instanceof Authority other)) {
      return false;
    }
    Class<?> objClass = obj instanceof HibernateProxy proxy
      ? proxy.getHibernateLazyInitializer().getPersistentClass()
      : obj.getClass();
    Class<?> thisClass = this instanceof HibernateProxy proxy
      ? proxy.getHibernateLazyInitializer().getPersistentClass()
      : this.getClass();
    if (!thisClass.equals(objClass)) {
      return false;
    }
    return id != null && Objects.equals(id, other.id);
  }

  @Override
  public final int hashCode() {
    return this instanceof HibernateProxy proxy
      ? proxy.getHibernateLazyInitializer().getPersistentClass().hashCode()
      : getClass().hashCode();
  }
}

Kotlin

package io.github.susimsek.springbootgraphqljwedemo.entity

import jakarta.persistence.Column
import jakarta.persistence.Entity
import jakarta.persistence.Id
import jakarta.persistence.Table
import org.hibernate.proxy.HibernateProxy
import java.util.Objects

@Entity
@Table(name = "authority")
class Authority(
  @Id
  @Column(length = 36, nullable = false)
  var id: String,

  @Column(length = 50, nullable = false, unique = true)
  var name: String,

  @Column(length = 255)
  var description: String?
) : BaseEntity() {

  override fun equals(other: Any?): Boolean {
    if (this === other) return true
    if (other !is Authority) return false
    val objClass = (other as? HibernateProxy)?.hibernateLazyInitializer?.persistentClass ?: other::class.java
    val thisClass = (this as? HibernateProxy)?.hibernateLazyInitializer?.persistentClass ?: this::class.java
    if (thisClass != objClass) return false
    return id == other.id
  }

  override fun hashCode(): Int {
    return (this as? HibernateProxy)?.hibernateLazyInitializer?.persistentClass?.hashCode()
      ?: javaClass.hashCode()
  }
}

User

Java

package io.github.susimsek.springbootgraphqljwedemo.entity;

import jakarta.persistence.CascadeType;
import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.FetchType;
import jakarta.persistence.Id;
import jakarta.persistence.NamedAttributeNode;
import jakarta.persistence.NamedEntityGraph;
import jakarta.persistence.NamedSubgraph;
import jakarta.persistence.OneToMany;
import jakarta.persistence.Table;
import lombok.AllArgsConstructor;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;
import org.hibernate.proxy.HibernateProxy;

import java.util.HashSet;
import java.util.Objects;
import java.util.Set;

@Entity
@Table(name = "user_identity")
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@NamedEntityGraph(
  name = "User.withAuthorities",
  attributeNodes = @NamedAttributeNode(value = "authorities", subgraph = "auth-subgraph"),
  subgraphs = @NamedSubgraph(
    name = "auth-subgraph",
    attributeNodes = @NamedAttributeNode("authority")
  )
)
public class User extends BaseEntity {

  @Id
  @Column(name = "id", length = 36, nullable = false, updatable = false)
  private String id;

  @Column(name = "username", length = 50, nullable = false, unique = true)
  private String username;

  @Column(name = "password", length = 100, nullable = false)
  private String password;

  @Column(name = "email", length = 100, nullable = false, unique = true)
  private String email;

  @Column(name = "first_name", length = 50)
  private String firstName;

  @Column(name = "last_name", length = 50)
  private String lastName;

  @Column(name = "enabled", nullable = false)
  private boolean enabled;

  @OneToMany(mappedBy = "user", fetch = FetchType.LAZY,
    cascade = CascadeType.ALL, orphanRemoval = true)
  private Set<UserAuthorityMapping> authorities = new HashSet<>();

  @Override
  public final boolean equals(Object obj) {
    if (this == obj) return true;
    if (!(obj instanceof User other)) return false;
    Class<?> objClass = (obj instanceof HibernateProxy hp
      ? hp.getHibernateLazyInitializer().getPersistentClass()
      : obj.getClass());
    Class<?> thisClass = (this instanceof HibernateProxy hp
      ? hp.getHibernateLazyInitializer().getPersistentClass()
      : this.getClass());
    if (!thisClass.equals(objClass)) return false;
    return id != null && id.equals(other.id);
  }

  @Override
  public final int hashCode() {
    return (this instanceof HibernateProxy hp
      ? hp.getHibernateLazyInitializer().getPersistentClass().hashCode()
      : getClass().hashCode());
  }
}

Kotlin

package io.github.susimsek.springbootgraphqljwedemo.entity

import jakarta.persistence.CascadeType
import jakarta.persistence.Column
import jakarta.persistence.Entity
import jakarta.persistence.FetchType
import jakarta.persistence.Id
import jakarta.persistence.NamedAttributeNode
import jakarta.persistence.NamedEntityGraph
import jakarta.persistence.NamedSubgraph
import jakarta.persistence.OneToMany
import jakarta.persistence.Table
import org.hibernate.proxy.HibernateProxy
import java.util.*

@Entity
@Table(name = "user_identity")
@NamedEntityGraph(
  name = "User.withAuthorities",
  attributeNodes = [NamedAttributeNode(value = "authorities", subgraph = "auth-subgraph")],
  subgraphs = [
    NamedSubgraph(
      name = "auth-subgraph",
      attributeNodes = [NamedAttributeNode("authority")]
    )
  ]
)
class User(

  @Id
  @Column(name = "id", length = 36, nullable = false, updatable = false)
  var id: String,

  @Column(name = "username", length = 50, nullable = false, unique = true)
  var username: String,

  @Column(name = "password", length = 100, nullable = false)
  var password: String,

  @Column(name = "email", length = 100, nullable = false, unique = true)
  var email: String,

  @Column(name = "first_name", length = 50)
  var firstName: String? = null,

  @Column(name = "last_name", length = 50)
  var lastName: String? = null,

  @Column(name = "enabled", nullable = false)
  var enabled: Boolean = true

) : BaseEntity() {

  @OneToMany(
    mappedBy = "user",
    fetch = FetchType.LAZY,
    cascade = [CascadeType.ALL],
    orphanRemoval = true
  )
  var authorities: MutableSet<UserAuthorityMapping> = HashSet()

  override fun equals(other: Any?): Boolean {
    if (this === other) return true
    if (other !is User) return false
    val objClass = (other as? HibernateProxy)?.hibernateLazyInitializer?.persistentClass
      ?: other::class.java
    val thisClass = (this as? HibernateProxy)?.hibernateLazyInitializer?.persistentClass
      ?: this::class.java
    if (thisClass != objClass) return false
    return id == other.id
  }

  override fun hashCode(): Int =
    ((this as? HibernateProxy)?.hibernateLazyInitializer?.persistentClass?.hashCode()
      ?: javaClass.hashCode())
}

UserAuthorityMapping

Java

package io.github.susimsek.springbootgraphqljwedemo.entity;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.FetchType;
import jakarta.persistence.Id;
import jakarta.persistence.IdClass;
import jakarta.persistence.JoinColumn;
import jakarta.persistence.ManyToOne;
import jakarta.persistence.Table;
import lombok.AllArgsConstructor;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;
import org.hibernate.proxy.HibernateProxy;

import java.util.Objects;

@Entity
@Table(name = "user_authority_mapping")
@IdClass(UserAuthorityMappingId.class)
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class UserAuthorityMapping extends BaseEntity {

  @Id
  @Column(name = "user_id", length = 36, nullable = false)
  private String userId;

  @Id
  @Column(name = "authority_id", length = 36, nullable = false)
  private String authorityId;

  @ManyToOne(fetch = FetchType.LAZY)
  @JoinColumn(name = "user_id", insertable = false, updatable = false)
  private User user;

  @ManyToOne(fetch = FetchType.LAZY)
  @JoinColumn(name = "authority_id", insertable = false, updatable = false)
  private Authority authority;

  @Override
  public final boolean equals(Object obj) {
    if (this == obj) return true;
    if (!(obj instanceof UserAuthorityMapping other)) return false;
    Class<?> objCls = (obj instanceof HibernateProxy hp
      ? hp.getHibernateLazyInitializer().getPersistentClass()
      : obj.getClass());
    Class<?> thisCls = (this instanceof HibernateProxy hp
      ? hp.getHibernateLazyInitializer().getPersistentClass()
      : this.getClass());
    if (!thisCls.equals(objCls)) return false;
    return userId != null && userId.equals(other.userId)
      && authorityId != null && authorityId.equals(other.authorityId);
  }

  @Override
  public final int hashCode() {
    return (this instanceof HibernateProxy hp
      ? hp.getHibernateLazyInitializer().getPersistentClass().hashCode()
      : Objects.hash(userId, authorityId));
  }
}

Kotlin

package io.github.susimsek.springbootgraphqljwedemo.entity

import jakarta.persistence.*
import org.hibernate.proxy.HibernateProxy
import java.util.*

@Entity
@Table(name = "user_authority_mapping")
@IdClass(UserAuthorityMappingId::class)
data class UserAuthorityMapping(

  @Id
  @Column(name = "user_id", length = 36, nullable = false)
  var userId: String = "",

  @Id
  @Column(name = "authority_id", length = 36, nullable = false)
  var authorityId: String = "",

  @ManyToOne(fetch = FetchType.LAZY)
  @JoinColumn(name = "user_id", insertable = false, updatable = false)
  var user: User? = null,

  @ManyToOne(fetch = FetchType.LAZY)
  @JoinColumn(name = "authority_id", insertable = false, updatable = false)
  var authority: Authority? = null

) : BaseEntity() {

  override fun equals(other: Any?): Boolean {
    if (this === other) return true
    if (other !is UserAuthorityMapping) return false

    val objCls = (other as? HibernateProxy)?.hibernateLazyInitializer?.persistentClass
      ?: other::class.java
    val thisCls = (this as? HibernateProxy)?.hibernateLazyInitializer?.persistentClass
      ?: this::class.java

    if (thisCls != objCls) return false
    return userId == other.userId && authorityId == other.authorityId
  }

  override fun hashCode(): Int {
    return (this as? HibernateProxy)?.hibernateLazyInitializer?.persistentClass?.hashCode()
      ?: Objects.hash(userId, authorityId)
  }
}

UserAuthorityMappingId

Java

package io.github.susimsek.springbootgraphqljwedemo.entity;

import java.io.Serializable;
import java.util.Objects;
import lombok.AllArgsConstructor;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;

@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class UserAuthorityMappingId implements Serializable {

  private String userId;
  private String authorityId;

  @Override
  public boolean equals(Object o) {
    if (this == o) return true;
    if (o == null || getClass() != o.getClass()) return false;
    UserAuthorityMappingId that = (UserAuthorityMappingId) o;
    return Objects.equals(userId, that.userId) &&
      Objects.equals(authorityId, that.authorityId);
  }

  @Override
  public int hashCode() {
    return Objects.hash(userId, authorityId);
  }
}

Kotlin

package io.github.susimsek.springbootgraphqljwedemo.entity

import java.io.Serializable
import java.util.Objects

data class UserAuthorityMappingId(
  var userId: String = "",
  var authorityId: String = ""
) : Serializable {

  override fun equals(other: Any?): Boolean {
    if (this === other) return true
    if (other == null || this::class != other::class) return false
    other as UserAuthorityMappingId
    return userId == other.userId && authorityId == other.authorityId
  }

  override fun hashCode(): Int {
    return Objects.hash(userId, authorityId)
  }
}

UserRepository

Java

package io.github.susimsek.springbootgraphqljwedemo.repository;

import io.github.susimsek.springbootgraphqljwedemo.entity.User;
import org.springframework.data.jpa.repository.EntityGraph;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

import java.util.Optional;

@Repository
public interface UserRepository extends JpaRepository<User, String> {

  @EntityGraph("User.withAuthorities")
  Optional<User> findOneWithAuthoritiesByUsername(String username);
}

Kotlin

package io.github.susimsek.springbootgraphqljwedemo.repository

import io.github.susimsek.springbootgraphqljwedemo.entity.User
import org.springframework.data.jpa.repository.EntityGraph
import org.springframework.data.jpa.repository.JpaRepository
import org.springframework.stereotype.Repository
import java.util.Optional

@Repository
interface UserRepository : JpaRepository<User, String> {

  @EntityGraph("User.withAuthorities")
  fun findOneWithAuthoritiesByUsername(username: String): Optional<User>
}

🛠️ Step 5: Secure JWE Token Utilities

In this section, we define the core utility classes and constants needed to generate, encrypt, and resolve JSON Web Encryption (JWE) tokens in your Spring Boot application, integrate auditing, and implement a JPA-based user details service:

• AuthoritiesConstants: Centralize role names with the ROLE_ prefix.
• CookieBearerTokenResolver: Resolve bearer tokens from Authorization headers or HTTP cookies.
• CookieUtils: Generates HTTP-only, secure ResponseCookie for new or expired tokens, and extracts the raw accessToken from HttpHeaders
• JweUtil: Sign (JWS) and encrypt (JWE) JWTs using RSA keys and Nimbus.
• KeyUtils: Build RSA JWKs from PEM‐encoded key material.
• SecurityUtils: Extract the current user’s login from the security context.
• SpringSecurityAuditorAware: Implement AuditorAware to provide the current user for auditing.
• DomainUserDetailsService: JPA-based UserDetailsService loading user and authorities for authentication.
• GraphQlTokenCookieInterceptor: Intercepts GraphQL responses to set or clear the access token cookie based on accessToken and clearAccessToken flags in the GraphQLContext.
• CookieAuthenticationWebSocketInterceptor: Intercept WebSocket connections to authenticate using JWE tokens from headers or cookies.

These utilities form the foundation for a stateless, JWE‐based authentication flow in Spring Security.

AuthoritiesConstants

Java

package io.github.susimsek.springbootgraphqljwedemo.security;

import lombok.AccessLevel;
import lombok.NoArgsConstructor;

@NoArgsConstructor(access = AccessLevel.PRIVATE)
public final class AuthoritiesConstants {
    public static final String ADMIN = "ROLE_ADMIN";
    public static final String USER = "ROLE_USER";
    public static final String ANONYMOUS = "ROLE_ANONYMOUS";
}

Kotlin

package io.github.susimsek.springbootgraphqljwedemo.security

object AuthoritiesConstants {
  const val ADMIN = "ROLE_ADMIN"
  const val USER = "ROLE_USER"
  const val ANONYMOUS = "ROLE_ANONYMOUS"
}

CookieBearerTokenResolver

Java

package io.github.susimsek.springbootgraphqljwedemo.security;

import jakarta.servlet.http.Cookie;
import jakarta.servlet.http.HttpServletRequest;
import lombok.Setter;
import org.springframework.http.HttpMethod;
import org.springframework.security.oauth2.core.OAuth2AuthenticationException;
import org.springframework.security.oauth2.server.resource.BearerTokenError;
import org.springframework.security.oauth2.server.resource.BearerTokenErrors;
import org.springframework.security.oauth2.server.resource.web.BearerTokenResolver;
import org.springframework.util.StringUtils;

import java.util.regex.Matcher;
import java.util.regex.Pattern;

@Setter
public class CookieBearerTokenResolver implements BearerTokenResolver {
    private static final String ACCESS_TOKEN_PARAMETER_NAME = "access_token";
    private static final Pattern AUTHORIZATION_PATTERN =
        Pattern.compile("^Bearer (?<token>[A-Za-z0-9-._~+/]+=*)$", Pattern.CASE_INSENSITIVE);

    private boolean allowFormEncodedBodyParameter = false;
    private boolean allowUriQueryParameter       = false;
    private boolean allowCookie                  = true;
    private String  bearerTokenHeaderName       = "Authorization";
    private String  cookieName                  = "accessToken";

    @Override
    public String resolve(HttpServletRequest request) {
        String headerToken = resolveFromAuthorizationHeader(request);
        String queryToken  = resolveAccessTokenFromQueryString(request);
        String bodyToken   = resolveAccessTokenFromBody(request);
        String cookieToken = (headerToken == null && queryToken == null && bodyToken == null)
            ? resolveFromCookie(request)
            : null;

        return resolveToken(headerToken, queryToken, bodyToken, cookieToken);
    }

    private String resolveFromAuthorizationHeader(HttpServletRequest request) {
        String authorization = request.getHeader(this.bearerTokenHeaderName);
        if (!StringUtils.hasText(authorization) || !authorization.toLowerCase().startsWith("bearer")) {
            return null;
        }
        Matcher matcher = AUTHORIZATION_PATTERN.matcher(authorization.trim());
        if (!matcher.matches()) {
            BearerTokenError error = BearerTokenErrors.invalidToken("Bearer token is malformed");
            throw new OAuth2AuthenticationException(error);
        }
        return matcher.group("token");
    }

    private String resolveAccessTokenFromQueryString(HttpServletRequest request) {
        if (allowUriQueryParameter && HttpMethod.GET.matches(request.getMethod())) {
            return resolveToken(request.getParameterValues(ACCESS_TOKEN_PARAMETER_NAME));
        }
        return null;
    }

    private String resolveAccessTokenFromBody(HttpServletRequest request) {
        if (allowFormEncodedBodyParameter
            && HttpMethod.POST.matches(request.getMethod())
            && "application/x-www-form-urlencoded".equals(request.getContentType())) {
            return resolveToken(request.getParameterValues(ACCESS_TOKEN_PARAMETER_NAME));
        }
        return null;
    }

    private String resolveFromCookie(HttpServletRequest request) {
        if (!allowCookie || request.getCookies() == null) {
            return null;
        }
        for (Cookie cookie : request.getCookies()) {
            if (cookieName.equals(cookie.getName())) {
                String val = cookie.getValue();
                return StringUtils.hasText(val) ? val : null;
            }
        }
        return null;
    }

    private String resolveToken(String... tokens) {
        String found = null;
        for (String token : tokens) {
            if (token == null) continue;
            if (found != null) {
                BearerTokenError error = BearerTokenErrors.invalidRequest("Found multiple bearer tokens in the request");
                throw new OAuth2AuthenticationException(error);
            }
            found = token;
        }
        if (found != null && found.isBlank()) {
            BearerTokenError error = BearerTokenErrors.invalidRequest("The requested token parameter is an empty string");
            throw new OAuth2AuthenticationException(error);
        }
        return found;
    }

Kotlin

package io.github.susimsek.springbootgraphqljwedemo.security

import jakarta.servlet.http.Cookie
import jakarta.servlet.http.HttpServletRequest
import org.springframework.http.HttpMethod
import org.springframework.security.oauth2.core.OAuth2AuthenticationException
import org.springframework.security.oauth2.server.resource.BearerTokenError
import org.springframework.security.oauth2.server.resource.BearerTokenErrors
import org.springframework.security.oauth2.server.resource.web.BearerTokenResolver
import org.springframework.util.StringUtils
import java.util.regex.Pattern

class CookieBearerTokenResolver {
    var allowFormEncodedBodyParameter: Boolean = false
    var allowUriQueryParameter: Boolean = false
    var allowCookie: Boolean = true
    var bearerTokenHeaderName: String = "Authorization"
    var cookieName: String = "accessToken"

    companion object {
        private const val ACCESS_TOKEN_PARAMETER_NAME = "access_token"
        private val AUTHORIZATION_PATTERN =
            Pattern.compile("^Bearer (?<token>[A-Za-z0-9-._~+/]+=*)$", Pattern.CASE_INSENSITIVE)
    }

    fun resolve(request: HttpServletRequest): String? {
        val header = resolveFromAuthorizationHeader(request)
        val query  = if (allowUriQueryParameter && HttpMethod.GET.matches(request.method))
            request.getParameterValues(ACCESS_TOKEN_PARAMETER_NAME)?.let(::resolveToken)
        else null
        val body   = if (allowFormEncodedBodyParameter && HttpMethod.POST.matches(request.method)
            && request.contentType == "application/x-www-form-urlencoded")
            request.getParameterValues(ACCESS_TOKEN_PARAMETER_NAME)?.let(::resolveToken)
        else null
        val cookie = if (header == null && query == null && body == null)
            resolveFromCookie(request)
        else null
      return listOf(header, query, body, cookie).filterNotNull().let {
            if (it.size > 1) throw OAuth2AuthenticationException(BearerTokenErrors.invalidRequest("Found multiple bearer tokens"))
            it.firstOrNull()?: null
        }
    }

    private fun resolveFromAuthorizationHeader(request: HttpServletRequest): String? {
        val auth = request.getHeader(bearerTokenHeaderName) ?: return null
        if (!auth.startsWith("Bearer ", true)) return null
        val matcher = AUTHORIZATION_PATTERN.matcher(auth.trim())
        return if (matcher.matches()) matcher.group("token")
        else throw OAuth2AuthenticationException(BearerTokenErrors.invalidToken("Malformed token"))
    }

    private fun resolveFromCookie(request: HttpServletRequest): String? {
        if (!allowCookie) return null
        return request.cookies?.firstOrNull { it.name == cookieName }?.value?.takeIf { it.isNotBlank() }
    }

    private fun resolveToken(tokens: Array<String>): String? {
        return tokens.filter { it.isNotBlank() }.let {
            when {
                it.isEmpty() -> null
                it.size > 1   -> throw OAuth2AuthenticationException(BearerTokenErrors.invalidRequest("Multiple tokens"))
                else          -> it[0]
            }
        }
    }

CookieUtils

Java

package io.github.susimsek.springbootjweauthjpademo.security;

import io.github.susimsek.springbootjweauthjpademo.dto.TokenDTO;
import lombok.experimental.UtilityClass;
import org.springframework.http.HttpHeaders;
import org.springframework.http.ResponseCookie;

import java.net.HttpCookie;
import java.util.Arrays;
import java.util.Optional;

@UtilityClass
public class CookieUtils {

  public static final String COOKIE_NAME = "accessToken";

  public ResponseCookie createAccessTokenCookie(TokenDTO tokenDto) {
    return ResponseCookie.from(COOKIE_NAME, tokenDto.accessToken())
      .httpOnly(true)
      .secure(true)
      .path("/")
      .maxAge(tokenDto.accessTokenExpiresIn())
      .sameSite("Strict")
      .build();
  }

  public static ResponseCookie removeAccessTokenCookie() {
    return ResponseCookie.from(COOKIE_NAME, "")
      .httpOnly(true)
      .secure(true)
      .path("/")
      .maxAge(0)
      .sameSite("Strict")
      .build();
  }

  public String resolveToken(HttpHeaders headers) {
    return Optional.ofNullable(headers.getFirst(HttpHeaders.COOKIE))
      .map(h -> h.split(";"))
      .stream()
      .flatMap(Arrays::stream)
      .flatMap(part -> HttpCookie.parse(part).stream())
      .filter(c -> COOKIE_NAME.equals(c.getName()))
      .map(HttpCookie::getValue)
      .findFirst()
      .orElse(null);
  }
}

Kotlin

package io.github.susimsek.springbootjweauthjpademo.security

import io.github.susimsek.springbootjweauthjpademo.dto.TokenDTO
import org.springframework.http.HttpHeaders
import org.springframework.http.ResponseCookie
import java.net.HttpCookie

object CookieUtils {

  const val COOKIE_NAME = "accessToken"

  fun createAccessTokenCookie(tokenDto: TokenDTO): ResponseCookie =
    ResponseCookie.from(COOKIE_NAME, tokenDto.accessToken())
      .httpOnly(true)
      .secure(true)
      .path("/")
      .maxAge(tokenDto.accessTokenExpiresIn())
      .sameSite("Strict")
      .build()

  fun removeAccessTokenCookie(): ResponseCookie =
    ResponseCookie.from(COOKIE_NAME, "")
      .httpOnly(true)
      .secure(true)
      .path("/")
      .maxAge(0)
      .sameSite("Strict")
      .build()

  fun resolveToken(headers: HttpHeaders): String? =
    headers.getFirst(HttpHeaders.COOKIE)
      ?.split(";")
      .orEmpty()
      .asSequence()
      .flatMap { HttpCookie.parse(it).asSequence() }
      .firstOrNull { it.name == COOKIE_NAME }
      ?.value
}

JweUtil

Java

package io.github.susimsek.springbootgraphqljwedemo.security;

import com.nimbusds.jose.EncryptionMethod;
import com.nimbusds.jose.JOSEException;
import com.nimbusds.jose.JWEAlgorithm;
import com.nimbusds.jose.JWEHeader;
import com.nimbusds.jose.JWEObject;
import com.nimbusds.jose.Payload;
import com.nimbusds.jose.crypto.RSAEncrypter;
import com.nimbusds.jose.jwk.RSAKey;
import io.github.susimsek.springbootgraphqljwedemo.config.JwtProperties;
import io.github.susimsek.springbootgraphqljwedemo.dto.TokenDTO;
import lombok.RequiredArgsConstructor;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.oauth2.jose.jws.SignatureAlgorithm;
import org.springframework.security.oauth2.jwt.*;
import org.springframework.stereotype.Component;

import java.time.Instant;
import java.util.List;

import static io.github.susimsek.springbootgraphqljwedemo.security.SecurityUtils.AUTHORITIES_KEY;

@Component
@RequiredArgsConstructor
public class JweUtil {

    private final JwtEncoder jwtEncoder;
    private final RSAKey signingKey;
    private final RSAKey encryptionKey;
    private final JwtProperties props;

    public TokenDTO generateToken(Authentication authentication) throws JOSEException {
        String subject = authentication.getName();
        List<String> roles = authentication.getAuthorities()
            .stream()
            .map(GrantedAuthority::getAuthority)
            .toList();

        Instant now = Instant.now();
        long expiresIn = props.getExpirationDuration().getSeconds();
        Instant exp = now.plusSeconds(expiresIn);

        JwtClaimsSet claims = JwtClaimsSet.builder()
            .issuer(props.getIssuer())
            .issuedAt(now)
            .expiresAt(exp)
            .subject(subject)
            .claim(AUTHORITIES_KEY, roles)
            .build();

        JwsHeader jwsHeader = JwsHeader.with(SignatureAlgorithm.RS256)
            .keyId(signingKey.getKeyID())
            .build();

        String jws = jwtEncoder
            .encode(JwtEncoderParameters.from(jwsHeader, claims))
            .getTokenValue();

        JWEHeader jweHeader = new JWEHeader.Builder(JWEAlgorithm.RSA_OAEP_256, EncryptionMethod.A128GCM)
            .contentType("JWT")
            .keyID(encryptionKey.getKeyID())
            .build();

        JWEObject jweObject = new JWEObject(jweHeader, new Payload(jws));
        jweObject.encrypt(new RSAEncrypter(encryptionKey.toRSAPublicKey()));
        String token = jweObject.serialize();

        return new TokenDTO(token, "Bearer", expiresIn);
    }
}

Kotlin

package io.github.susimsek.springbootgraphqljwedemo.security

import com.nimbusds.jose.EncryptionMethod
import com.nimbusds.jose.JOSEException
import com.nimbusds.jose.JWEAlgorithm
import com.nimbusds.jose.JWEHeader
import com.nimbusds.jose.JWEObject
import com.nimbusds.jose.Payload
import com.nimbusds.jose.crypto.RSAEncrypter
import com.nimbusds.jose.jwk.RSAKey
import io.github.susimsek.springbootgraphqljwedemo.config.JwtProperties
import io.github.susimsek.springbootgraphqljwedemo.dto.TokenDTO
import lombok.RequiredArgsConstructor
import org.springframework.security.core.Authentication
import org.springframework.security.oauth2.jose.jws.SignatureAlgorithm
import org.springframework.security.oauth2.jwt.JwtClaimsSet
import org.springframework.security.oauth2.jwt.JwtEncoder
import org.springframework.security.oauth2.jwt.JwtEncoderParameters
import org.springframework.stereotype.Component

import java.time.Instant

@Component
@RequiredArgsConstructor
class JweUtil(
    private val jwtEncoder: JwtEncoder,
    private val signingKey: RSAKey,
    private val encryptionKey: RSAKey,
    private val props: JwtProperties
) {
    fun generateToken(authentication: Authentication): TokenDTO {
        val subject = authentication.name
        val roles = authentication.authorities.map { it.authority }

        val now = Instant.now()
        val expiresIn = props.expirationDuration.seconds
        val exp = now.plusSeconds(expiresIn)

        val claims = JwtClaimsSet.builder()
            .issuer(props.issuer)
            .issuedAt(now)
            .expiresAt(exp)
            .subject(subject)
            .claim(AUTHORITIES_KEY, roles)
            .build()

        val jwsHeader = org.springframework.security.oauth2.jwt.JwsHeader.with(SignatureAlgorithm.RS256)
            .keyId(signingKey.keyID)
            .build()

        val jws = jwtEncoder
            .encode(JwtEncoderParameters.from(jwsHeader, claims))
            .tokenValue

        val jweHeader = JWEHeader.Builder(JWEAlgorithm.RSA_OAEP_256, EncryptionMethod.A128GCM)
            .contentType("JWT")
            .keyID(encryptionKey.keyID)
            .build()

        val jweObject = JWEObject(jweHeader, Payload(jws))
        jweObject.encrypt(RSAEncrypter(encryptionKey.toRSAPublicKey()))
        val token = jweObject.serialize()

        return TokenDTO(token, "Bearer", expiresIn)
    }
}

KeyUtils

Java

package io.github.susimsek.springbootgraphqljwedemo.security;

import com.nimbusds.jose.JWEAlgorithm;
import com.nimbusds.jose.JWSAlgorithm;
import com.nimbusds.jose.jwk.KeyUse;
import com.nimbusds.jose.jwk.RSAKey;
import lombok.experimental.UtilityClass;

import java.security.KeyFactory;
import java.security.interfaces.RSAPrivateKey;
import java.security.interfaces.RSAPublicKey;
import java.security.spec.PKCS8EncodedKeySpec;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;

@UtilityClass
public class KeyUtils {
    public RSAKey buildRsaKey(
            String pubPem,
            String privPem,
            String kid,
            boolean forSign
    ) throws Exception {
        String pubContent = pubPem
            .replace("-----BEGIN PUBLIC KEY-----", "")
            .replace("-----END PUBLIC KEY-----", "")
            .replaceAll("\\s", "");
        String privContent = privPem
            .replace("-----BEGIN PRIVATE KEY-----", "")
            .replace("-----END PRIVATE KEY-----", "")
            .replaceAll("\\s", "");

        byte[] decodedPub = Base64.getDecoder().decode(pubContent);
        byte[] decodedPriv = Base64.getDecoder().decode(privContent);

        KeyFactory kf = KeyFactory.getInstance("RSA");
        RSAPublicKey publicKey = (RSAPublicKey) kf.generatePublic(new X509EncodedKeySpec(decodedPub));
        RSAPrivateKey privateKey = (RSAPrivateKey) kf.generatePrivate(new PKCS8EncodedKeySpec(decodedPriv));

        RSAKey.Builder builder = new RSAKey.Builder(publicKey)
            .privateKey(privateKey)
            .keyID(kid);

        if (forSign) {
            builder
                .algorithm(JWSAlgorithm.RS256)
                .keyUse(KeyUse.SIGNATURE);
        } else {
            builder
                .algorithm(JWEAlgorithm.RSA_OAEP_256)
                .keyUse(KeyUse.ENCRYPTION);
        }

        return builder.build();
    }
}

Kotlin

package io.github.susimsek.springbootgraphqljwedemo.security

import com.nimbusds.jose.JWEAlgorithm
import com.nimbusds.jose.JWSAlgorithm
import com.nimbusds.jose.jwk.KeyUse
import com.nimbusds.jose.jwk.RSAKey
import java.security.KeyFactory
import java.security.interfaces.RSAPrivateKey
import java.security.interfaces.RSAPublicKey
import java.security.spec.PKCS8EncodedKeySpec
import java.security.spec.X509EncodedKeySpec
import java.util.Base64

object KeyUtils {
    @JvmStatic
    @Throws(Exception::class)
    fun buildRsaKey(
        pubPem: String,
        privPem: String,
        kid: String,
        forSign: Boolean
    ): RSAKey {
        val pubContent = pubPem
            .replace("-----BEGIN PUBLIC KEY-----", "")
            .replace("-----END PUBLIC KEY-----", "")
            .replace(Regex("\\s"), "")
        val privContent = privPem
            .replace("-----BEGIN PRIVATE KEY-----", "")
            .replace("-----END PRIVATE KEY-----", "")
            .replace(Regex("\\s"), "")

        val decodedPub = Base64.getDecoder().decode(pubContent)
        val decodedPriv = Base64.getDecoder().decode(privContent)

        val kf = KeyFactory.getInstance("RSA")
        val publicKey = kf.generatePublic(X509EncodedKeySpec(decodedPub)) as RSAPublicKey
        val privateKey = kf.generatePrivate(PKCS8EncodedKeySpec(decodedPriv)) as RSAPrivateKey

        val builder = RSAKey.Builder(publicKey)
            .privateKey(privateKey)
            .keyID(kid)

        if (forSign) {
            builder
                .algorithm(JWSAlgorithm.RS256)
                .keyUse(KeyUse.SIGNATURE)
        } else {
            builder
                .algorithm(JWEAlgorithm.RSA_OAEP_256)
                .keyUse(KeyUse.ENCRYPTION)
        }

        return builder.build()
    }
}

SecurityUtils

Java

package io.github.susimsek.springbootgraphqljwedemo.security;

import lombok.experimental.UtilityClass;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.oauth2.jwt.Jwt;

import java.util.Optional;

@UtilityClass
public class SecurityUtils {

    public static final String AUTHORITIES_KEY = "auth";

    public Optional<String> getCurrentUserLogin() {
        var ctx = SecurityContextHolder.getContext();
        return Optional.ofNullable(extractPrincipal(ctx.getAuthentication()));
    }

    private String extractPrincipal(Authentication authentication) {
        if (authentication == null) {
            return null;
        }
        Object principal = authentication.getPrincipal();
        if (principal instanceof Jwt jwt) {
            return jwt.getSubject();
        }
        if (principal instanceof UserDetails ud) {
            return ud.getUsername();
        }
        if (principal instanceof String username) {
            return username;
        }
        return null;
    }
}

Kotlin

package io.github.susimsek.springbootgraphqljwedemo.security

import org.springframework.security.core.Authentication
import org.springframework.security.core.context.SecurityContextHolder
import org.springframework.security.core.userdetails.UserDetails
import org.springframework.security.oauth2.jwt.Jwt
import java.util.Optional

object SecurityUtils {
  const val AUTHORITIES_KEY = "auth"

  fun getCurrentUserLogin(): Optional<String> {
    val authentication: Authentication? = SecurityContextHolder.getContext().authentication
    return Optional.ofNullable(extractPrincipal(authentication))
  }

  private fun extractPrincipal(authentication: Authentication?): String? {
    return when (val principal = authentication?.principal) {
      is Jwt -> principal.subject
      is UserDetails -> principal.username
      is String -> principal
      else -> null
    }
  }
}

DomainUserDetailsService

Java

package io.github.susimsek.springbootgraphqljwedemo.security;

import io.github.susimsek.springbootgraphqljwedemo.entity.User;
import io.github.susimsek.springbootgraphqljwedemo.repository.UserRepository;
import lombok.RequiredArgsConstructor;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.core.userdetails.UsernameNotFoundException;

import java.util.List;
import java.util.stream.Collectors;

@RequiredArgsConstructor
public class DomainUserDetailsService implements UserDetailsService {

  private final UserRepository userRepository;

  @Override
  public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {
    User user = userRepository.findOneWithAuthoritiesByUsername(username)
      .orElseThrow(() -> new UsernameNotFoundException("User not found with username: " + username));

    List<GrantedAuthority> authorities = user.getAuthorities().stream()
      .map(mapping -> mapping.getAuthority().getName())
      .map(SimpleGrantedAuthority::new)
      .collect(Collectors.toList());

    return new org.springframework.security.core.userdetails.User(
      user.getUsername(),
      user.getPassword(),
      user.isEnabled(),  // enabled
      true,              // accountNonExpired
      true,              // credentialsNonExpired
      true,              // accountNonLocked
      authorities
    );
  }
}

Kotlin

package io.github.susimsek.springbootgraphqljwedemo.security

import io.github.susimsek.springbootgraphqljwedemo.repository.UserRepository
import org.springframework.security.core.GrantedAuthority
import org.springframework.security.core.authority.SimpleGrantedAuthority
import org.springframework.security.core.userdetails.UserDetails
import org.springframework.security.core.userdetails.UserDetailsService
import org.springframework.security.core.userdetails.UsernameNotFoundException
import java.util.stream.Collectors

class DomainUserDetailsService(
  private val userRepository: UserRepository
) : UserDetailsService {
  override fun loadUserByUsername(username: String): UserDetails {
    val user = userRepository.findOneWithAuthoritiesByUsername(username)
      .orElseThrow { UsernameNotFoundException("User not found with username: $username") }

    val authorities: List<GrantedAuthority> = user.authorities.stream()
      .map { SimpleGrantedAuthority(it.authority.name) }
      .collect(Collectors.toList())

    return org.springframework.security.core.userdetails.User(
      user.username,
      user.password,
      user.enabled,
      true,
      true,
      true,
      authorities
    )
  }
}

SpringSecurityAuditorAware

Java

package io.github.susimsek.springbootgraphqljwedemo.security;

import org.springframework.data.domain.AuditorAware;
import org.springframework.lang.NonNull;
import org.springframework.stereotype.Component;

import java.util.Optional;

@Component
public class SpringSecurityAuditorAware implements AuditorAware<String> {

  @Override
  @NonNull
  public Optional<String> getCurrentAuditor() {
    return Optional.of(SecurityUtils.getCurrentUserLogin().orElse("system"));
  }
}

Kotlin

package io.github.susimsek.springbootgraphqljwedemo.security

import org.springframework.data.domain.AuditorAware
import org.springframework.lang.NonNull
import org.springframework.stereotype.Component

@Component
class SpringSecurityAuditorAware : AuditorAware<String> {
    @NonNull
    override fun getCurrentAuditor(): Optional<String> =
        Optional.of(SecurityUtils.getCurrentUserLogin().orElse("system"))
}

GraphQlTokenCookieInterceptor

Java

package io.github.susimsek.springbootjweauthjpademo.security;

import graphql.GraphQLContext;
import io.github.susimsek.springbootjweauthjpademo.dto.TokenDTO;
import org.springframework.graphql.server.WebGraphQlInterceptor;
import org.springframework.graphql.server.WebGraphQlRequest;
import org.springframework.graphql.server.WebGraphQlResponse;
import org.springframework.http.HttpHeaders;
import org.springframework.http.ResponseCookie;
import org.springframework.lang.NonNull;
import org.springframework.stereotype.Component;
import reactor.core.publisher.Mono;

@Component
public class GraphQlTokenCookieInterceptor implements WebGraphQlInterceptor {

  @Override
  @NonNull
  public Mono<WebGraphQlResponse> intercept(@NonNull WebGraphQlRequest request, Chain chain) {
    return chain.next(request)
      .doOnNext(response -> {
        GraphQLContext ctx = response.getExecutionInput().getGraphQLContext();

        if (Boolean.TRUE.equals(ctx.get("clearAccessToken"))) {
          ResponseCookie expired = CookieUtils.removeAccessTokenCookie();
          response.getResponseHeaders().add(HttpHeaders.SET_COOKIE, expired.toString());
          return;
        }

        TokenDTO tokenDto = ctx.get("accessToken");
        if (tokenDto != null) {
          ResponseCookie cookie = CookieUtils.createAccessTokenCookie(tokenDto);
          response.getResponseHeaders()
            .add(HttpHeaders.SET_COOKIE, cookie.toString());
        }
      });
  }
}

Kotlin

package io.github.susimsek.springbootjweauthjpademo.security

import graphql.GraphQLContext
import io.github.susimsek.springbootjweauthjpademo.dto.TokenDTO
import org.springframework.graphql.server.WebGraphQlInterceptor
import org.springframework.graphql.server.WebGraphQlRequest
import org.springframework.graphql.server.WebGraphQlResponse
import org.springframework.http.HttpHeaders
import org.springframework.http.ResponseCookie
import org.springframework.stereotype.Component
import reactor.core.publisher.Mono

@Component
class GraphQlTokenCookieInterceptor : WebGraphQlInterceptor {

  override fun intercept(
    request: WebGraphQlRequest,
    chain: WebGraphQlInterceptor.Chain
  ): Mono<WebGraphQlResponse> {
    return chain.next(request)
      .doOnNext { response ->
        val ctx: GraphQLContext = response.executionInput.graphQLContext

        if (ctx.get<Boolean>("clearAccessToken") == true) {
          val expired: ResponseCookie = CookieUtils.removeAccessTokenCookie()
          response.responseHeaders.add(HttpHeaders.SET_COOKIE, expired.toString())
          return@doOnNext
        }

        ctx.get<TokenDTO>("accessToken")?.let { tokenDto ->
          val cookie: ResponseCookie = CookieUtils.createAccessTokenCookie(tokenDto)
          response.responseHeaders.add(HttpHeaders.SET_COOKIE, cookie.toString())
        }
      }
  }
}

CookieAuthenticationWebSocketInterceptor

Java

package io.github.susimsek.springbootgraphqljwedemo.security;

import io.github.susimsek.springbootgraphqljwedemo.security.CookieUtils;
import lombok.RequiredArgsConstructor;
import org.springframework.graphql.server.WebGraphQlInterceptor;
import org.springframework.graphql.server.WebGraphQlRequest;
import org.springframework.graphql.server.WebGraphQlResponse;
import org.springframework.graphql.server.WebSocketGraphQlInterceptor;
import org.springframework.graphql.server.WebSocketGraphQlRequest;
import org.springframework.graphql.server.WebSocketSessionInfo;
import org.springframework.graphql.server.support.AuthenticationExtractor;
import org.springframework.lang.NonNull;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContext;
import org.springframework.security.core.context.SecurityContextImpl;
import org.springframework.security.oauth2.server.resource.authentication.BearerTokenAuthenticationToken;
import reactor.core.publisher.Mono;
import reactor.util.context.Context;
import reactor.util.context.ContextView;

import java.util.Map;

@RequiredArgsConstructor
public class CookieAuthenticationWebSocketInterceptor implements WebSocketGraphQlInterceptor {

  private final String authenticationAttribute = this.getClass().getName() + ".AUTHENTICATION";
  private final AuthenticationExtractor authExtractor;
  private final AuthenticationManager authenticationManager;

  @Override
  @NonNull
  public Mono<Object> handleConnectionInitialization(@NonNull WebSocketSessionInfo info,
                                                     @NonNull Map<String, Object> payload) {

    Mono<Authentication> headerAuth = authExtractor.getAuthentication(payload);

    Mono<Authentication> cookieAuth = Mono.defer(() -> {
      String token = CookieUtils.resolveToken(info.getHeaders());
      return token != null
        ? Mono.just(new BearerTokenAuthenticationToken(token))
        : Mono.empty();
    });

    return headerAuth
      .switchIfEmpty(cookieAuth)
      .flatMap(this::authenticate)
      .doOnNext(auth -> {
        SecurityContext securityContext = new SecurityContextImpl(auth);
        info.getAttributes().put(this.authenticationAttribute, securityContext);
      })
      .then(Mono.empty());
  }

  @Override
  @NonNull
  public Mono<WebGraphQlResponse> intercept(@NonNull WebGraphQlRequest request,
                                            @NonNull WebGraphQlInterceptor.Chain chain) {
    if (request instanceof WebSocketGraphQlRequest webSocketRequest) {
      Map<String, Object> attributes = webSocketRequest.getSessionInfo().getAttributes();
      SecurityContext securityContext = (SecurityContext) attributes.get(this.authenticationAttribute);
      ContextView contextView = this.getContextToWrite(securityContext);
      return chain.next(request).contextWrite(contextView);
    } else {
      return chain.next(request);
    }
  }

  protected Mono<Authentication> authenticate(Authentication authentication) {
    return Mono.just(this.authenticationManager.authenticate(authentication));
  }

  protected ContextView getContextToWrite(SecurityContext securityContext) {
    return Context.of(SecurityContext.class.getName(), securityContext);
  }
}

Kotlin

package io.github.susimsek.springbootgraphqljwedemo.security

import io.github.susimsek.springbootgraphqljwedemo.security.CookieUtils
import org.springframework.graphql.server.WebGraphQlInterceptor
import org.springframework.graphql.server.WebGraphQlRequest
import org.springframework.graphql.server.WebGraphQlResponse
import org.springframework.graphql.server.WebSocketGraphQlInterceptor
import org.springframework.graphql.server.WebSocketGraphQlRequest
import org.springframework.graphql.server.WebSocketSessionInfo
import org.springframework.graphql.server.support.AuthenticationExtractor
import org.springframework.lang.NonNull
import org.springframework.security.authentication.AuthenticationManager
import org.springframework.security.core.Authentication
import org.springframework.security.core.context.SecurityContext
import org.springframework.security.core.context.SecurityContextImpl
import org.springframework.security.oauth2.server.resource.authentication.BearerTokenAuthenticationToken
import reactor.core.publisher.Mono
import reactor.util.context.Context
import reactor.util.context.ContextView

class CookieAuthenticationWebSocketInterceptor(
  private val authExtractor: AuthenticationExtractor,
  private val authenticationManager: AuthenticationManager
) : WebSocketGraphQlInterceptor {

  private val authenticationAttribute: String = "${this::class.java.name}.AUTHENTICATION"

  @NonNull
  override fun handleConnectionInitialization(
    @NonNull info: WebSocketSessionInfo,
    @NonNull payload: Map<String, Any>
  ): Mono<Any> {
    val headerAuth: Mono<Authentication> = authExtractor.getAuthentication(payload)

    val cookieAuth: Mono<Authentication> = Mono.defer {
      val token = CookieUtils.resolveToken(info.headers)
      if (token != null) {
        Mono.just(BearerTokenAuthenticationToken(token))
      } else {
        Mono.empty()
      }
    }

    return headerAuth
      .switchIfEmpty(cookieAuth)
      .flatMap { authenticate(it) }
      .doOnNext { auth ->
        val securityContext = SecurityContextImpl(auth)
        info.attributes[authenticationAttribute] = securityContext
      }
      .then(Mono.empty())
  }

  @NonNull
  override fun intercept(
    @NonNull request: WebGraphQlRequest,
    @NonNull chain: WebGraphQlInterceptor.Chain
  ): Mono<WebGraphQlResponse> {
    return if (request is WebSocketGraphQlRequest) {
      val attributes = request.sessionInfo.attributes
      val securityContext = attributes[authenticationAttribute] as SecurityContext
      val contextView: ContextView = getContextToWrite(securityContext)
      chain.next(request).contextWrite(contextView)
    } else {
      chain.next(request)
    }
  }

  protected fun authenticate(authentication: Authentication): Mono<Authentication> =
    Mono.just(authenticationManager.authenticate(authentication))

  protected fun getContextToWrite(securityContext: SecurityContext): ContextView =
    Context.of(SecurityContext::class.java.name, securityContext)
}

🛠️ Step 6: Authentication & Protected Endpoints

In this section, we define the GraphQL controllers and DTOs necessary for:

• AuthController: Authenticates users, issues JWE tokens via a GraphQL mutation, and places accessToken or clearAccessToken flags into the GraphQLContext.
• HelloController: Expose protected GraphQL queries, subscriptions and mutations for authenticated users and admin-only operations.
• LoginInput: GraphQL input type for login (username/password).
• GreetInput & GreetDTO: GraphQL mutation input and response for a greeting operation.
• TokenDTO: Model the JWE token response including token, type, and expiration.

These components complete the stateless authentication flow in a GraphQL API using JWE tokens and a JPA-backed user store.

AuthController

Java

package io.github.susimsek.springbootjweauthjpademo.controller;

import graphql.GraphQLContext;
import io.github.susimsek.springbootjweauthjpademo.dto.LoginInput;
import io.github.susimsek.springbootjweauthjpademo.dto.TokenDTO;
import io.github.susimsek.springbootjweauthjpademo.security.JweUtil;
import lombok.RequiredArgsConstructor;
import org.springframework.graphql.data.method.annotation.Argument;
import org.springframework.graphql.data.method.annotation.MutationMapping;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.stereotype.Controller;

@Controller
@RequiredArgsConstructor
public class AuthController {

  private final AuthenticationManager authenticationManager;
  private final JweUtil jweUtil;

  @MutationMapping
  public TokenDTO login(@Argument LoginInput input,
                        GraphQLContext context) {
    // Authenticate user
    Authentication auth = authenticationManager.authenticate(
      new UsernamePasswordAuthenticationToken(input.username(), input.password())
    );
    SecurityContextHolder.getContext().setAuthentication(auth);

    // Generate JWE token
    TokenDTO tokenDto = jweUtil.generateToken(auth);

    // Store token in GraphQLContext for the interceptor to set cookie
    context.put("accessToken", tokenDto);

    return tokenDto;
  }

  @PreAuthorize("isAuthenticated()")
  @MutationMapping
  public Boolean logout(GraphQLContext context) {
    // Signal the interceptor to clear the cookie
    context.put("clearAccessToken", Boolean.TRUE);
    return true;
  }
}

Kotlin

package io.github.susimsek.springbootjweauthjpademo.controller

import graphql.GraphQLContext
import io.github.susimsek.springbootjweauthjpademo.dto.LoginInput
import io.github.susimsek.springbootjweauthjpademo.dto.TokenDTO
import io.github.susimsek.springbootjweauthjpademo.security.JweUtil
import org.springframework.graphql.data.method.annotation.Argument
import org.springframework.graphql.data.method.annotation.MutationMapping
import org.springframework.security.access.prepost.PreAuthorize
import org.springframework.security.authentication.AuthenticationManager
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken
import org.springframework.security.core.context.SecurityContextHolder
import org.springframework.stereotype.Controller

@Controller
class AuthController(
  private val authenticationManager: AuthenticationManager,
  private val jweUtil: JweUtil
) {

  @MutationMapping
  fun login(
    @Argument input: LoginInput,
    context: GraphQLContext
  ): TokenDTO {
    // Authenticate user
    val auth = authenticationManager.authenticate(
      UsernamePasswordAuthenticationToken(input.username, input.password)
    )
    SecurityContextHolder.getContext().authentication = auth

    // Generate JWE token
    val tokenDto = jweUtil.generateToken(auth)

    // Store token in GraphQLContext for the interceptor to set cookie
    context.put("accessToken", tokenDto)

    return tokenDto
  }

  @PreAuthorize("isAuthenticated()")
  @MutationMapping
  fun logout(context: GraphQLContext): Boolean {
    // Signal the interceptor to clear the cookie
    context.put("clearAccessToken", true)
    return true
  }
}

HelloController

Java

package io.github.susimsek.springbootgraphqljwedemo.controller;

import io.github.susimsek.springbootgraphqljwedemo.dto.GreetDTO;
import io.github.susimsek.springbootgraphqljwedemo.dto.GreetInput;
import lombok.RequiredArgsConstructor;
import org.springframework.graphql.data.method.annotation.Argument;
import org.springframework.graphql.data.method.annotation.MutationMapping;
import org.springframework.graphql.data.method.annotation.QueryMapping;
import org.springframework.graphql.data.method.annotation.SubscriptionMapping;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.jwt.Jwt;
import org.springframework.stereotype.Controller;
import reactor.core.publisher.Flux;

import java.time.Duration;
import java.time.Instant;

import static io.github.susimsek.springbootgraphqljwedemo.security.SecurityUtils.AUTHORITIES_KEY;

@Controller
@RequiredArgsConstructor
@PreAuthorize("isAuthenticated()")
public class HelloController {

  @QueryMapping
  public String helloAll(@AuthenticationPrincipal Jwt jwt) {
    var roles = jwt.getClaimAsStringList(AUTHORITIES_KEY);
    return "Hello, " + jwt.getSubject() + "! Your roles: " + roles;
  }

  @PreAuthorize("hasAuthority('ROLE_ADMIN')")
  @QueryMapping
  public String helloAdmin(@AuthenticationPrincipal Jwt jwt) {
    return "Hello Admin, " + jwt.getSubject() + "!";
  }

  @MutationMapping
  public GreetDTO greet(
    @Argument GreetInput input,
    @AuthenticationPrincipal Jwt jwt
  ) {
    String msg = "Hello " + jwt.getSubject() + ", you said: " + input.getMessage();
    return new GreetDTO(msg, Instant.now());
  }

  @SubscriptionMapping("greetStream")
  public Flux<GreetDTO> greetStream(
    @Argument GreetInput input,
    @AuthenticationPrincipal Jwt jwt
  ) {
    return Flux.interval(Duration.ofSeconds(1))
      .map(i -> {
        String msg = "Hello " + jwt.getSubject()
          + ", you said: " + input.getMessage()
          + " (event " + (i + 1) + ")";
        return new GreetDTO(msg, Instant.now());
      });
  }

  @PreAuthorize("hasAuthority('ROLE_ADMIN')")
  @SubscriptionMapping("greetStreamAdmin")
  public Flux<GreetDTO> greetStreamAdmin(
    @Argument GreetInput input,
    @AuthenticationPrincipal Jwt jwt
  ) {
    return Flux.interval(Duration.ofSeconds(2))
      .map(i -> {
        String msg = "Hello Admin " + jwt.getSubject()
          + ", you said: " + input.getMessage()
          + " (admin event " + (i + 1) + ")";
        return new GreetDTO(msg, Instant.now());
      });
  }
}

Kotlin

LoginInput

Java

package io.github.susimsek.springbootgraphqljwedemo.dto;

public record LoginInput(
  String username,
  String password
) {}

Kotlin

package io.github.susimsek.springbootgraphqljwedemo.dto

data class LoginInput(
  val username: String,
  val password: String
)

GreetInput

Java

package io.github.susimsek.springbootgraphqljwedemo.dto;

public record GreetInput(
  String message
) {}

Kotlin

package io.github.susimsek.springbootgraphqljwedemo.dto

data class GreetInput(
  val message: String
)

GreetDTO

Java

package io.github.susimsek.springbootgraphqljwedemo.dto;

import java.time.Instant;

public record GreetDTO(
  String greeting,
  Instant timestamp
) {}

Kotlin

package io.github.susimsek.springbootgraphqljwedemo.dto

import java.time.Instant

data class GreetDTO(
  val greeting: String,
  val timestamp: Instant
)

TokenDTO

Java

package io.github.susimsek.springbootgraphqljwedemo.dto;

public record TokenDTO(
  String accessToken,
  String tokenType,
  long accessTokenExpiresIn
) {}

Kotlin

package io.github.susimsek.springbootgraphqljwedemo.dto

data class TokenDTO(
  val accessToken: String,
  val tokenType: String,
  val accessTokenExpiresIn: Long
)

▶️ Run the App

./mvnw spring-boot:run
# or
gradle bootRun

If you have GraalVM 22.3+ installed, you can compile a native image with the native profile:

./mvnw native:compile -Pnative

After successful native-image compilation, the executable will be generated under target/ (e.g., target/spring-boot-graphql-jwe-auth-demo). Run it directly:

./target/spring-boot-graphql-jwe-auth-demo

Optionally, compress the native executable using UPX for a smaller file size (if UPX is installed):

upx --ultra-brute --lzma target/spring-boot-graphql-jwe-auth-demo

🧪 Test GraphQL Endpoints

In this section, we clarify Test GraphQL Endpoints and summarize the key points you will apply in implementation.

Admin Flow

Login as admin and capture the JWE token from the Set-Cookie header:

curl -i -X POST http://localhost:8080/graphql \
  -H "Content-Type: application/json" \
  -d '{ "query": "mutation { login(input: { username: \"admin\", password: \"adminpass\" }) { accessToken tokenType accessTokenExpiresIn } }" }'

• Set-Cookie header contains accessToken=<jwe-token>
• Response body:

{
  "data": {
    "login": {
      "accessToken": "<jwe-token>",
      "tokenType": "Bearer",
      "accessTokenExpiresIn": 3600
    }
  }
}

Use cookie to access hello endpoint:

curl -b "accessToken=<jwe-token>" \
  -H "Content-Type: application/json" \
  -d '{ "query": "{ helloAll }" }' \
  http://localhost:8080/graphql

Use Authorization header instead:

curl -H "Authorization: Bearer <jwe-token>" \
  -H "Content-Type: application/json" \
  -d '{ "query": "{ helloAll }" }' \
  http://localhost:8080/graphql

Call the admin-restricted helloAdmin query:

curl -H "Authorization: Bearer <jwe-token>" \
  -H "Content-Type: application/json" \
  -d '{ "query": "{ helloAdmin }" }' \
  http://localhost:8080/graphql

Execute the logout mutation to clear the session cookie:

curl -H "Authorization: Bearer <jwe-token>" \
  -H "Content-Type: application/json" \
  -d '{ "query": "mutation { logout }" }' \
  http://localhost:8080/graphql

User Flow

Login as user and capture JWE token from cookie:

curl -i -X POST http://localhost:8080/graphql \
  -H "Content-Type: application/json" \
  -d '{ "query": "mutation { login(input: { username: \"user\", password: \"userpass\" }) { accessToken tokenType accessTokenExpiresIn } }" }'

• Set-Cookie header contains accessToken=<jwe-token>

Use cookie to call helloAll:

curl -b "accessToken=<jwe-token>" \
  -H "Content-Type: application/json" \
  -d '{ "query": "{ helloAll }" }' \
  http://localhost:8080/graphql

Use Authorization header:

curl -H "Authorization: Bearer <jwe-token>" \
  -H "Content-Type: application/json" \
  -d '{ "query": "{ helloAll }" }' \
  http://localhost:8080/graphql

Attempt the helloAdmin query (should return errors with 403):

curl -H "Authorization: Bearer <jwe-token>" \
  -H "Content-Type: application/json" \
  -d '{ "query": "{ helloAdmin }" }' \
  http://localhost:8080/graphql

Subscription Test via GraphiQL

Test subscriptions directly in the GraphiQL UI at http://localhost:8080/graphiql:

1. Token Retrieval in GraphiQL

2. In the Query pane, enter:

   mutation Login($in: LoginInput!) {
     login(input: $in) {
       accessToken
     }
   }
   

3. Switch to the Variables pane and add:

   {
     "in": { "username": "admin", "password": "adminpass" }
   }
   

4. Click ▶️ to execute and copy the returned accessToken from the response.

5. Configure Headers

6. Click the Headers tab in the sidebar.

7. Add:

   {
     "Authorization": "Bearer <accessToken>"
   }
   

8. Subscribe as User

9. Switch to the Subscriptions pane.

10. Enter:

    subscription UserSubscribe($in: GreetInput!) {
      greetStream(input: $in) {
        greeting
        timestamp
      }
    }
    

11. In Variables, set:

    {
      "in": { "message": "Hello via GraphiQL!" }
    }
    

12. Click ▶️ to start streaming messages from greetStream.

13. Subscribe as Admin

14. In the same Subscriptions pane, enter:

    subscription AdminSubscribe($in: GreetInput!) {
      greetStreamAdmin(input: $in) {
        greeting
        timestamp
      }
    }
    

15. Use the same Variables panel.

16. Click ▶️. Only tokens with ROLE_ADMIN receive data; others see an authorization error.

🏁 Conclusion

You now have a practical Spring Boot GraphQL JWE Authentication implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why Use JWE + JPA Authentication?

In this section, we clarify Why Use JWE + JPA Authentication? and summarize the key points you will apply in implementation.

• Stateless Security: Tokens are self-contained and require no server-side storage.
• Integrity: Signed tokens ensure tamper evidence.
• Confidentiality: Encrypted JWTs hide sensitive claims.
• User Management: Persist and manage users and roles via familiar JPA repositories.
• Standards-based: Leverage JOSE, Spring Security, and Spring Data JPA.
• Scalable: Scale horizontally without session replication or sticky sessions.

📋 Prerequisites

In this section, we clarify Prerequisites and summarize the key points you will apply in implementation.

• ☕ Java Development Kit (JDK) 17 or higher
• 📦 Spring Boot 3.2+
• 🔤 IDE (IntelliJ IDEA, Eclipse)
• 🛢️ PostgreSQL (or H2 for dev)

🛠️ Step 1: Add Dependencies

Include these in your pom.xml or build.gradle file.

Maven:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.security</groupId>
  <artifactId>spring-security-oauth2-resource-server</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
  <groupId>org.liquibase</groupId>
  <artifactId>liquibase-core</artifactId>
</dependency>
<dependency>
  <groupId>org.projectlombok</groupId>
  <artifactId>lombok</artifactId>
  <optional>true</optional>
</dependency>
<dependency>
  <groupId>com.h2database</groupId>
  <artifactId>h2</artifactId>
  <scope>runtime</scope>
</dependency>

Gradle:

implementation 'org.springframework.boot:spring-boot-starter-web'
implementation 'org.springframework.security:spring-security-oauth2-resource-server'
implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
implementation 'org.liquibase:liquibase-core'
compileOnly 'org.projectlombok:lombok'
runtimeOnly 'com.h2database:h2'

🛠️ Step 2: Configuration Files

In this section, we define all of the application- and database-level configuration files required to wire up our Spring Boot app with H2/PostgreSQL, JPA, Liquibase changelogs, initial data loads, and JWE key properties.

• application.yml Holds Spring datasource, H2 console, JPA/Hibernate, Liquibase changelog path, and all JWT/JWE key, issuer, and expiration settings.

• db/master.xml The Liquibase master changelog, with includes and DBMS-specific properties for H2 and PostgreSQL.

• db/changelog/changelog-user.xml Your core schema changelog defining user_identity, authority, and user_authority_mapping tables, indexes, FKs, and initial <loadData> steps.

• db/data/user.csv Initial user records (UUID, username, bcrypt-hashed password, email, enabled flag, timestamps, auditor).

• db/data/authority.csv Initial authority records (UUID, name, description, timestamps, auditor).

• db/data/user_authority_mapping.csv Initial mapping of users ↔ authorities (composite PK, timestamps, auditor).

application.yml

spring:
  datasource:
    url: jdbc:h2:mem:testdb;MODE=PostgreSQL;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE
    driver-class-name: org.h2.Driver
    username: sa
    password: password
  h2:
    console:
      enabled: true
  jpa:
    open-in-view: false
    hibernate:
      ddl-auto: none
    show-sql: true
    properties:
      hibernate.format_sql: true
  liquibase:
    change-log: classpath:db/master.xml
security:
  admin:
    username: admin
    password: adminpass
  user:
    username: user
    password: userpass
  jwt:
    issuer: demo-issuer
    expiration-duration: 3600s
    signing:
      key-id: signing-key
      public-key: |-
        -----BEGIN PUBLIC KEY-----
        MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAjZEcz5itWkDGOSqZdB5P
        JE0ccOCckskp0hN3kQbT1qnv+9/k66jlWgVi4HSTppwdNF/Ylu5u541Qj+Okyg+u
        8o2PvKo5CfgvTDsFLTrZHUXU6hCSGatLAQoeN6lT8wzov2r4DFecXrIqcO6SvMB5
        ecPqsfiTi4trsNKgJ4cWS6gILH62ISd1ipUadfpnUzDMO1OulV0CJNV6bcBk7Es9
        RW6AHfg9j8osSanpwvRM4MJkB0SRxYUnrN9faGpkBZISZJ8TShhaTHEGfSNgKe5y
        8iu+AMGGZu8DYczVmqS3Ske1fq6y5HEGCma7Mo019GmwKeHBo1obuET6cZRygj4y
        twIDAQAB
        -----END PUBLIC KEY-----
      private-key: |-
        -----BEGIN PRIVATE KEY-----
        MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQCNkRzPmK1aQMY5
        Kpl0Hk8kTRxw4JySySnSE3eRBtPWqe/73+TrqOVaBWLgdJOmnB00X9iW7m7njVCP
        46TKD67yjY+8qjkJ+C9MOwUtOtkdRdTqEJIZq0sBCh43qVPzDOi/avgMV5xesipw
        7pK8wHl5w+qx+JOLi2uw0qAnhxZLqAgsfrYhJ3WKlRp1+mdTMMw7U66VXQIk1Xpt
        wGTsSz1FboAd+D2PyixJqenC9EzgwmQHRJHFhSes319oamQFkhJknxNKGFpMcQZ9
        I2Ap7nLyK74AwYZm7wNhzNWapLdKR7V+rrLkcQYKZrsyjTX0abAp4cGjWhu4RPpx
        lHKCPjK3AgMBAAECggEABMo/sNCIMREXA/EqjxDFecN4LmOTOK5A0YBiH9Cc01sd
        qSaavtSQqhqbjV+0bUNEA7UohXbc3s3bx3qa5VFhiIh8sBQMaQdyRkCK/MxMc16d
        BSx5XQ/8MjVO73A1zHgH2g47BWPjgRrDL94KrgNPOO0FoG76QxL9GlcOHzhFa1rf
        xbb2auLBtflKy+5TZNnB/sbFC9ISpWywzfblD2Fsvxupl0vNWtA0Y2rPbKMZRnY+
        V6NC38yxW3HHAdWQRYLGOitM59I0HBgnjQKzTBNIsjPnJA2BSZvMBtQ1e3RQV0qE
        8VVoktZ8A0KDUxqdKWYlGYAY5hIw1y3UUsPRUbS3fQKBgQDAZehu+Kb5Sw+h00Qu
        vViNHDvi0PwmhQrHVpgjrppCnWsTk6FJFm+EBLY+87usXuRCnfZ1semb6P+yjLh2
        bJ9IXIrFAztcyE+7eZfn0H7mHA7E2ICKTjNdKbjy8kHViHpgdXREnAOrFTTk/BqW
        dq+weG2OuxYczWsY4XliWaVyiwKBgQC8XYExpSmoyI37o+jr9405k30tbGUw4X+/
        xYOvSUuafI8IOSLfKTpsvkMN3hxpJO6apIRAjOALbotKUA5FrHQPenuBWOr3mBJT
        euLiaWphqU8YN5dbNd+JhC/Jh5DLhY5FpB2Fv2MKSoF7+onpjDy9pEU5aReeBB0v
        ekUw4nWiBQKBgHxyrnjxP1frFG5xMB4nfZqw04+v7BmiXsl3mqsh6kgCeNtN17pl
        17YGMjfgAdnJ+02XzW5tqRSfDp3YZgy7z//HVD+BCqnGK8SxLu/ULfD73xW2kNZl
        JNYzAZ2r06eiQr4X2x/x5nGIIxGmfDAtDxFPpFX5b6ErwgVy+sgCAoFnAoGAWSpu
        EMEdQk+FnnwNsz2g9YNSuyDXmdb08SOfXWd1yXBzCLJ7RmYuyPEbrsHYcxFPfZap
        ICFPoTm35/qTdvnWiskxE56yw3eSHUBLjF/YQtixn0YZeMy8v0z6jgyFR0I2gdLZ
        QsnBKUrxlm2XwR1oV2Eef7m2u085PZNEk4pvor0CgYA6n060r48/CgRVslAeGder
        fZ3n+2ru8q2UVB38evepjLifn5+tKdFzZ7/NckXMC0NOVzm74qG46VFLMw5TtyT4
        /hRvGSYxA6dMjXy+tcrAns9Isrz2PnYFntlbhU6hw0um809tFunbvITfyeOjAsDW
        stC4thnhzXXT1Y3RfFtYEg==
        -----END PRIVATE KEY-----
    encryption:
      key-id: encryption-key
      public-key: |-
        -----BEGIN PUBLIC KEY-----
        MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtU7Vu4tML8qg9BISaUH0
        BTU0+qkHJS3TUl3R0hEPttZJGf8EgT7bpWqRjdhMC2SYt2ifNF82EgMo/eva1rLn
        wYtCsxjJ7oB4U2m16/JKHtphmMUGhSLgbp+Y8pGAQ+P6u4HLlI0qbL92Syb6QCTr
        nYIlzZ2uUAvUQg/SbuAvdS4kdauZtpMNbhryusMVvILVBC5yUhfLJAkjbU3qWo/n
        2NKPr4kjwwFh6FaAf0HLsXCFmJbPPok6WMZeDqPORPZCt5gU2t04fS7s/2SSbhQ/
        i+7yyT4pl44cUlNLLN3Qo73sai5H90q7Dvmk3M5/YMJB0Ueyb705LHyOO5xA618s
        qQIDAQAB
        -----END PUBLIC KEY-----
      private-key: |-
        -----BEGIN PRIVATE KEY-----
        MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC1TtW7i0wvyqD0
        EhJpQfQFNTT6qQclLdNSXdHSEQ+21kkZ/wSBPtulapGN2EwLZJi3aJ80XzYSAyj9
        69rWsufBi0KzGMnugHhTabXr8koe2mGYxQaFIuBun5jykYBD4/q7gcuUjSpsv3ZL
        JvpAJOudgiXNna5QC9RCD9Ju4C91LiR1q5m2kw1uGvK6wxW8gtUELnJSF8skCSNt
        Tepaj+fY0o+viSPDAWHoVoB/QcuxcIWYls8+iTpYxl4Oo85E9kK3mBTa3Th9Luz/
        ZJJuFD+L7vLJPimXjhxSU0ss3dCjvexqLkf3SrsO+aTczn9gwkHRR7JvvTksfI47
        nEDrXyypAgMBAAECggEAREnJHrY8n9OGA+e6n4KD0mJT7gUz98Dm0yMbIC/k50yW
        hAAVRkjSmd8lq3NIURI2ov342NTznJ0sF1d6OVtxBujY2nP/uqEQsPoj1xaO7Ef8
        cnnjFsooFgJurQ44bVm02mLstqrky8jhWTT5FKfTRqP6cRNu0B9kdu1WqQQvW8a/
        C8xD8XUFzzJFQsEstJ076NjlZNH3EeqFiLxyVdV7tPEJRnOe2V2BAAgda3ByA6Jc
        Nd4xYHTVr5rZ+KES9gaAgb86+S7hNigsxz5Gp58NimLEyz1Qd+d9QCgPRgKOV5Uq
        0ci6c28ZrxW9wa/2CGCpoow1V7hRy1fZ24g2Tz91cQKBgQDbSdP/FQYuem0pUf8u
        mA/niEC8Jz30FW3ix5aqbQ8YRudK48Xy8F7AWnlS0wT2k/Xaeppn9YSPK4HlsNk2
        1gnpNfzdqXpJQtuxcPPeFNzUdXzBrsLXYqtlhOX/afrzqMhp73gkqoxXtqwD7BqN
        VfMcVXsWrEZQrRPBn/RUnnLdJwKBgQDTqUGupm93UlhoPgLXHGF/seQwPPHcU6lS
        SS9l512Ie21B+vZecgO4r77BXJwbY4rZVA5/m+wrsNmsT2f8yfdbs84cBDDWiKy5
        t2Um8zrus+BCIffxc9Fck9/htK33jLLcYwdSAm3a9pJxR9f/kAdredSTGBNJ3W/2
        rfh3cdNprwKBgDi7WfBFRSsjGzi0cPth9cNlubGzyVBrdtlT34PJ4Tzboxz53o1i
        aHEFNxwZYdBVKSbTzzyUBS5xCBMfdKK+LyQ5hmjmXq+zb1jxqvXKmfMRTixhhSDp
        8wO5pTM1/Omqwea+QGvj/5j1tnzxSVFFajbrWoPcH/jhPho6wqBducPDAoGBALOJ
        MEOavZXy7TaO0w3v7uvH0wzvxR/kfw1jMqc3l2j7ePOskmoOQAXaXO3bRjcdOlua
        Jyoq8islOZ4lRMlx7zWD0OKG035GNGzbmRtu2aA8R48RDSVr3jyu2gqznZULbXPv
        M/hmQxSmbhVUoW0PmJubnaqfk0zmXeBaNRXsIS3VAoGBALdsAtqR23PVeL6sYj2l
        dRNTDXpfvjFqJ5NThRO/4mT0CrPHQVj+Mz2bTc/Dxiwi8s8m3L+g23i3hodh/QMb
        Iz+UbcJZBGAKsFbPKGOtj6Bi07y/L11mcuNJzOWe61/JbVmJss0s+N/v3XucK/Ge
        CUaGOccsMO221v6JoBh9J3Hz
        -----END PRIVATE KEY-----

master.xml

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
  xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="
      http://www.liquibase.org/xml/ns/dbchangelog
      http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.9.xsd">

  <!-- H2 defaults -->
  <property name="now" value="now()" dbms="h2"/>
  <property name="floatType" value="float4" dbms="h2"/>
  <property name="uuidType" value="uuid" dbms="h2"/>
  <property name="datetimeType" value="datetime(6)" dbms="h2"/>
  <property name="binaryType" value="LONGVARBINARY" dbms="h2"/>
  <property name="clobType" value="longvarchar" dbms="h2"/>
  <property name="blobType" value="blob" dbms="h2"/>

  <!-- PostgreSQL overrides -->
  <property name="now" value="current_timestamp" dbms="postgresql"/>
  <property name="floatType" value="float4" dbms="postgresql"/>
  <property name="uuidType" value="uuid" dbms="postgresql"/>
  <property name="datetimeType" value="datetime" dbms="postgresql"/>
  <property name="binaryType" value="BYTEA" dbms="postgresql"/>
  <property name="clobType" value="clob" dbms="postgresql"/>
  <property name="blobType" value="blob" dbms="postgresql"/>

  <!-- include the core auth changelog -->
  <include file="classpath:db/changelog/changelog-user.xml"/>

</databaseChangeLog>

changelog-user.xml

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
  xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="
      http://www.liquibase.org/xml/ns/dbchangelog
      http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.9.xsd">

  <changeSet id="20250510-1" author="susimsek">
    <createTable tableName="user_identity">
      <column name="id" type="varchar(36)">
        <constraints primaryKey="true" primaryKeyName="pk_user_identity" nullable="false"/>
      </column>
      <column name="username" type="varchar(50)">
        <constraints nullable="false" unique="true"/>
      </column>
      <column name="password" type="varchar(100)">
        <constraints nullable="false"/>
      </column>
      <column name="email" type="varchar(100)">
        <constraints nullable="false" unique="true"/>
      </column>
      <column name="first_name" type="varchar(50)"/>
      <column name="last_name" type="varchar(50)"/>
      <column name="enabled" type="boolean">
        <constraints nullable="false"/>
      </column>
      <column name="created_at" type="datetime">
        <constraints nullable="false"/>
      </column>
      <column name="created_by" type="varchar(50)">
        <constraints nullable="false"/>
      </column>
      <column name="updated_at" type="datetime"/>
      <column name="updated_by" type="varchar(50)"/>
    </createTable>

    <createIndex indexName="idx_user_identity_username" tableName="user_identity">
      <column name="username"/>
    </createIndex>
    <createIndex indexName="idx_user_identity_email" tableName="user_identity">
      <column name="email"/>
    </createIndex>
  </changeSet>

  <changeSet id="20250510-2" author="susimsek">
    <createTable tableName="authority">
      <column name="id" type="varchar(36)">
        <constraints primaryKey="true" primaryKeyName="pk_authority" nullable="false"/>
      </column>
      <column name="name" type="varchar(50)">
        <constraints nullable="false" unique="true"/>
      </column>
      <column name="description" type="varchar(255)"/>
      <column name="created_at" type="datetime">
        <constraints nullable="false"/>
      </column>
      <column name="created_by" type="varchar(50)">
        <constraints nullable="false"/>
      </column>
      <column name="updated_at" type="datetime"/>
      <column name="updated_by" type="varchar(50)"/>
    </createTable>

    <createIndex indexName="idx_authority_name" tableName="authority">
      <column name="name"/>
    </createIndex>
  </changeSet>

  <changeSet id="20250510-3" author="susimsek">
    <createTable tableName="user_authority_mapping">
      <column name="user_id" type="varchar(36)">
        <constraints nullable="false"/>
      </column>
      <column name="authority_id" type="varchar(36)">
        <constraints nullable="false"/>
      </column>
      <column name="created_at" type="datetime">
        <constraints nullable="false"/>
      </column>
      <column name="created_by" type="varchar(50)">
        <constraints nullable="false"/>
      </column>
      <column name="updated_at" type="datetime"/>
      <column name="updated_by" type="varchar(50)"/>
    </createTable>

    <addPrimaryKey
      tableName="user_authority_mapping"
      columnNames="user_id, authority_id"
      constraintName="pk_user_authority_mapping"/>
  </changeSet>

  <changeSet id="20250510-4" author="susimsek">
    <addForeignKeyConstraint
      baseTableName="user_authority_mapping"
      baseColumnNames="user_id"
      constraintName="fk_user_authority_user"
      referencedTableName="user_identity"
      referencedColumnNames="id"/>
  </changeSet>

  <changeSet id="20250510-5" author="susimsek">
    <addForeignKeyConstraint
      baseTableName="user_authority_mapping"
      baseColumnNames="authority_id"
      constraintName="fk_user_authority_authority"
      referencedTableName="authority"
      referencedColumnNames="id"/>
  </changeSet>

  <changeSet id="20250510-1-data" author="susimsek">
    <loadData
      file="db/data/user.csv"
      separator=";"
      tableName="user_identity">
      <column name="id" type="string"/>
      <column name="username" type="string"/>
      <column name="password" type="string"/>
      <column name="email" type="string"/>
      <column name="first_name" type="string"/>
      <column name="last_name" type="string"/>
      <column name="enabled" type="boolean"/>
      <column name="created_at" type="datetime"/>
      <column name="created_by" type="string"/>
      <column name="updated_at" type="datetime"/>
      <column name="updated_by" type="string"/>
    </loadData>
  </changeSet>

  <changeSet id="20250510-2-data" author="susimsek">
    <loadData
      file="db/data/authority.csv"
      separator=";"
      tableName="authority">
      <column name="id" type="string"/>
      <column name="name" type="string"/>
      <column name="description" type="string"/>
      <column name="created_at" type="datetime"/>
      <column name="created_by" type="string"/>
      <column name="updated_at" type="datetime"/>
      <column name="updated_by" type="string"/>
    </loadData>
  </changeSet>

  <changeSet id="20250510-3-data" author="susimsek">
    <loadData
      file="db/data/user_authority_mapping.csv"
      separator=";"
      tableName="user_authority_mapping">
      <column name="user_id" type="string"/>
      <column name="authority_id" type="string"/>
      <column name="created_at" type="datetime"/>
      <column name="created_by" type="string"/>
      <column name="updated_at" type="datetime"/>
      <column name="updated_by" type="string"/>
    </loadData>
  </changeSet>

</databaseChangeLog>

user.csv

id;username;password;email;first_name;last_name;enabled;created_at;created_by;updated_at;updated_by
a1b2c3d4-e5f6-7890-abcd-ef1234567890;admin;$2a$10$sva6wl8pmGKJE6NIWrxwcuJK1Jaa2I/LOI43iHVpbR4YB8KjGViiK;admin@example.com;Admin;User;true;2025-05-10 12:00:00;system;2025-05-10 12:00:00;system
09876543-21fe-dcba-0987-654321fedcba;user;$2a$10$5Py4PyteLuXEqnGpSigzfu0V55C7Hi7zX18lmh.J8Bpmft.h23voG;user@example.com;Normal;User;true;2025-05-10 12:00:00;system;2025-05-10 12:00:00;system

authority.csv

id;name;description;created_at;created_by;updated_at;updated_by
f47ac10b-58cc-4372-a567-0e02b2c3d479;ROLE_ADMIN;Administrator role;2025-05-10 12:00:00;system;2025-05-10 12:00:00;system
9c858901-8a57-4791-81fe-4c455b099bc9;ROLE_USER;User role;2025-05-10 12:00:00;system;2025-05-10 12:00:00;system

user_authority_mapping.csv

user_id;authority_id;created_at;created_by;updated_at;updated_by
a1b2c3d4-e5f6-7890-abcd-ef1234567890;9c858901-8a57-4791-81fe-4c455b099bc9;2025-05-10 12:00:00;system;2025-05-10 12:00:00;system
a1b2c3d4-e5f6-7890-abcd-ef1234567890;f47ac10b-58cc-4372-a567-0e02b2c3d479;2025-05-10 12:00:00;system;2025-05-10 12:00:00;system
09876543-21fe-dcba-0987-654321fedcba;9c858901-8a57-4791-81fe-4c455b099bc9;2025-05-10 12:00:00;system;2025-05-10 12:00:00;system

🛠️ Step 3: Security & Database Configuration

In this section, we define the beans and properties RSA keys, HTTP security filters, and JPA repository/auditing setup for JWE‑based authentication:

• JwtProperties: Configures JWT issuer, expiration, and signing/encryption key pairs.
• SecurityJwtConfig: Builds RSA JWKs, JWT encoder/decoder, authentication converter, and token resolver.
• SecurityConfig: Integrates DomainUserDetailsService, configures authentication manager, password encoder, and stateless security filter chain with JWE support.
• DatabaseConfig: Enables JPA repositories, auditing, and transaction management.

SecurityJwtConfig

Java

package io.github.susimsek.springbootjweauthjpademo.config;

import com.nimbusds.jose.EncryptionMethod;
import com.nimbusds.jose.JWEAlgorithm;
import com.nimbusds.jose.JWSAlgorithm;
import com.nimbusds.jose.jwk.JWKSet;
import com.nimbusds.jose.jwk.RSAKey;
import com.nimbusds.jose.jwk.source.JWKSource;
import com.nimbusds.jose.proc.JWEDecryptionKeySelector;
import com.nimbusds.jose.proc.JWSVerificationKeySelector;
import com.nimbusds.jose.proc.SecurityContext;
import com.nimbusds.jwt.proc.DefaultJWTProcessor;
import io.github.susimsek.springbootjweauthjpademo.security.CookieBearerTokenResolver;
import io.github.susimsek.springbootjweauthjpademo.security.KeyUtils;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.oauth2.jwt.JwtDecoder;
import org.springframework.security.oauth2.jwt.JwtEncoder;
import org.springframework.security.oauth2.jwt.NimbusJwtDecoder;
import org.springframework.security.oauth2.jwt.NimbusJwtEncoder;
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter;
import org.springframework.security.oauth2.server.resource.authentication.JwtGrantedAuthoritiesConverter;
import org.springframework.security.oauth2.server.resource.web.BearerTokenResolver;

import java.util.List;

import static io.github.susimsek.springbootjweauthjpademo.security.SecurityUtils.AUTHORITIES_KEY;

@Configuration
public class SecurityJwtConfig {

    private final JwtProperties props;
    public SecurityJwtConfig(JwtProperties props) { this.props = props; }

    @Bean
    public RSAKey signingKey() throws Exception {
        return KeyUtils.buildRsaKey(
            props.getSigning().getPublicKey(),
            props.getSigning().getPrivateKey(),
            props.getSigning().getKeyId(),
            true
        );
    }

    @Bean
    public RSAKey encryptionKey() throws Exception {
        return KeyUtils.buildRsaKey(
            props.getEncryption().getPublicKey(),
            props.getEncryption().getPrivateKey(),
            props.getEncryption().getKeyId(),
            false
        );
    }

    @Bean
    public JWKSource<SecurityContext> jwkSource(RSAKey signingKey, RSAKey encryptionKey) {
        JWKSet jwkSet = new JWKSet(List.of(
            signingKey,
            encryptionKey
        ));
        return (jwkSelector, context) -> jwkSelector.select(jwkSet);
    }

    @Bean
    public JwtDecoder jwtDecoder(JWKSource<SecurityContext> jwkSource) {
        DefaultJWTProcessor<SecurityContext> jwtProcessor = new DefaultJWTProcessor<>();
        JWEDecryptionKeySelector<SecurityContext> jweKeySelector =
            new JWEDecryptionKeySelector<>(
                JWEAlgorithm.RSA_OAEP_256,
                EncryptionMethod.A128GCM,
                jwkSource
            );
        jwtProcessor.setJWEKeySelector(jweKeySelector);

        JWSVerificationKeySelector<SecurityContext> jwsKeySelector =
            new JWSVerificationKeySelector<>(
                JWSAlgorithm.RS256,
                jwkSource
            );
        jwtProcessor.setJWSKeySelector(jwsKeySelector);
        jwtProcessor.setJWTClaimsSetVerifier((claims, context) -> {});

        return new NimbusJwtDecoder(jwtProcessor);
    }

    @Bean
    public JwtEncoder jwtEncoder(JWKSource<SecurityContext> jwkSource) {
        return new NimbusJwtEncoder(jwkSource);
    }

    @Bean
    public JwtAuthenticationConverter jwtAuthenticationConverter() {
        JwtGrantedAuthoritiesConverter converter = new JwtGrantedAuthoritiesConverter();
        converter.setAuthorityPrefix("");
        converter.setAuthoritiesClaimName(AUTHORITIES_KEY);

        JwtAuthenticationConverter authConverter = new JwtAuthenticationConverter();
        authConverter.setJwtGrantedAuthoritiesConverter(converter);
        return authConverter;
    }

    @Bean
    public BearerTokenResolver bearerTokenResolver() {
        CookieBearerTokenResolver resolver = new CookieBearerTokenResolver();
        resolver.setAllowUriQueryParameter(false);
        resolver.setAllowFormEncodedBodyParameter(false);
        resolver.setAllowCookie(true);
        return resolver;
    }
}

Kotlin

package io.github.susimsek.springbootjweauthjpademo.config

import com.nimbusds.jose.EncryptionMethod
import com.nimbusds.jose.JWEAlgorithm
import com.nimbusds.jose.JWSAlgorithm
import com.nimbusds.jose.jwk.JWKSet
import com.nimbusds.jose.jwk.RSAKey
import com.nimbusds.jose.jwk.source.JWKSource
import com.nimbusds.jose.proc.JWEDecryptionKeySelector
import com.nimbusds.jose.proc.JWSVerificationKeySelector
import com.nimbusds.jose.proc.SecurityContext
import com.nimbusds.jwt.proc.DefaultJWTProcessor
import io.github.susimsek.springbootjweauthjpademo.security.CookieBearerTokenResolver
import io.github.susimsek.springbootjweauthjpademo.security.KeyUtils
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.security.oauth2.jwt.JwtDecoder
import org.springframework.security.oauth2.jwt.JwtEncoder
import org.springframework.security.oauth2.jwt.NimbusJwtDecoder
import org.springframework.security.oauth2.jwt.NimbusJwtEncoder
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter
import org.springframework.security.oauth2.server.resource.authentication.JwtGrantedAuthoritiesConverter
import org.springframework.security.oauth2.server.resource.web.BearerTokenResolver

@Configuration
class SecurityJwtConfig(private val props: JwtProperties) {

    @Bean
    @Throws(Exception::class)
    fun signingKey(): RSAKey =
        KeyUtils.buildRsaKey(
            props.signing.publicKey,
            props.signing.privateKey,
            props.signing.keyId,
            true
        )

    @Bean
    @Throws(Exception::class)
    fun encryptionKey(): RSAKey =
        KeyUtils.buildRsaKey(
            props.encryption.publicKey,
            props.encryption.privateKey,
            props.encryption.keyId,
            false
        )

    @Bean
    fun jwkSource(signingKey: RSAKey, encryptionKey: RSAKey): JWKSource<SecurityContext> {
        val jwkSet = JWKSet(listOf(signingKey, encryptionKey))
        return JWKSource { jwkSelector, context -> jwkSelector.select(jwkSet) }
    }

    @Bean
    fun jwtDecoder(jwkSource: JWKSource<SecurityContext>): JwtDecoder {
        val jwtProcessor = DefaultJWTProcessor<SecurityContext>()
        val jweKeySelector = JWEDecryptionKeySelector(
            JWEAlgorithm.RSA_OAEP_256,
            EncryptionMethod.A128GCM,
            jwkSource
        )
        jwtProcessor.jweKeySelector = jweKeySelector
        val jwsKeySelector = JWSVerificationKeySelector(
            JWSAlgorithm.RS256,
            jwkSource
        )
        jwtProcessor.jwsKeySelector = jwsKeySelector
        jwtProcessor.jwtClaimsSetVerifier = { _, _ -> }
        return NimbusJwtDecoder(jwtProcessor)
    }

    @Bean
    fun jwtEncoder(jwkSource: JWKSource<SecurityContext>): JwtEncoder =
        NimbusJwtEncoder(jwkSource)

    @Bean
    fun jwtAuthenticationConverter(): JwtAuthenticationConverter {
        val converter = JwtGrantedAuthoritiesConverter().apply {
            setAuthorityPrefix("")
            setAuthoritiesClaimName(AUTHORITIES_KEY)
        }
        return JwtAuthenticationConverter().apply {
            setJwtGrantedAuthoritiesConverter(converter)
        }
    }

    @Bean
    fun bearerTokenResolver(): BearerTokenResolver =
        CookieBearerTokenResolver().apply {
            setAllowUriQueryParameter(false)
            setAllowFormEncodedBodyParameter(false)
            setAllowCookie(true)
        }
}

SecurityConfig

Java

package io.github.susimsek.springbootjweauthjpademo.config;

import io.github.susimsek.springbootjweauthjpademo.repository.UserRepository;
import io.github.susimsek.springbootjweauthjpademo.security.AuthoritiesConstants;
import io.github.susimsek.springbootjweauthjpademo.security.DomainUserDetailsService;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.ProviderManager;
import org.springframework.security.authentication.dao.DaoAuthenticationProvider;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.servlet.util.matcher.MvcRequestMatcher;
import org.springframework.web.servlet.handler.HandlerMappingIntrospector;

import static org.springframework.security.config.Customizer.withDefaults;

@Configuration
@EnableMethodSecurity(securedEnabled = true)
public class SecurityConfig {

  @Bean
  public SecurityFilterChain securityFilterChain(HttpSecurity http,
                                                 MvcRequestMatcher.Builder mvc) throws Exception {
    http
      .cors(withDefaults())
      .csrf(AbstractHttpConfigurer::disable)
      .authorizeHttpRequests(authz -> authz
        .requestMatchers(
          mvc.pattern("/webjars/**"),
          mvc.pattern("/css/**"),
          mvc.pattern("/js/**")
        ).permitAll()
        .requestMatchers(
          mvc.pattern("/*.ico"),
          mvc.pattern("/*.png"),
          mvc.pattern("/*.svg"),
          mvc.pattern("/*.webapp")
        ).permitAll()
        .requestMatchers("/actuator/**").permitAll()
        .requestMatchers(
          "/v3/api-docs/**",
          "/swagger-ui.html",
          "/swagger-ui/**"
        ).permitAll()
        .requestMatchers(mvc.pattern("/api/auth/login")).permitAll()
        .requestMatchers(mvc.pattern("/api/hello/admin")).hasAuthority(AuthoritiesConstants.ADMIN)
        .anyRequest().authenticated()
      )
      .sessionManagement(session ->
        session.sessionCreationPolicy(SessionCreationPolicy.STATELESS)
      )
      .oauth2ResourceServer(oauth2 -> oauth2.jwt(withDefaults()));

    return http.build();
  }

  @Bean
  public UserDetailsService userDetailsService(UserRepository userRepository) {
    return new DomainUserDetailsService(userRepository);
  }

  @Bean
  public PasswordEncoder passwordEncoder() {
    return new BCryptPasswordEncoder();
  }

  @Bean
  public AuthenticationManager authenticationManager(
    UserDetailsService userDetailsService,
    PasswordEncoder passwordEncoder) {
    DaoAuthenticationProvider authenticationProvider = new DaoAuthenticationProvider();
    authenticationProvider.setUserDetailsService(userDetailsService);
    authenticationProvider.setPasswordEncoder(passwordEncoder);

    return new ProviderManager(authenticationProvider);
  }

  @Bean
  public MvcRequestMatcher.Builder mvc(HandlerMappingIntrospector introspector) {
    return new MvcRequestMatcher.Builder(introspector);
  }
}

Kotlin

package io.github.susimsek.springbootjweauthjpademo.config

import io.github.susimsek.springbootjweauthjpademo.repository.UserRepository
import io.github.susimsek.springbootjweauthjpademo.security.AuthoritiesConstants
import io.github.susimsek.springbootjweauthjpademo.security.DomainUserDetailsService
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.security.authentication.AuthenticationManager
import org.springframework.security.authentication.ProviderManager
import org.springframework.security.authentication.dao.DaoAuthenticationProvider
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity
import org.springframework.security.config.annotation.web.builders.HttpSecurity
import org.springframework.security.config.configurers.AbstractHttpConfigurer
import org.springframework.security.config.http.SessionCreationPolicy
import org.springframework.security.core.userdetails.UserDetailsService
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder
import org.springframework.security.crypto.password.PasswordEncoder
import org.springframework.security.web.SecurityFilterChain
import org.springframework.security.web.servlet.util.matcher.MvcRequestMatcher
import org.springframework.web.servlet.handler.HandlerMappingIntrospector

@Configuration
@EnableMethodSecurity(securedEnabled = true)
class SecurityConfig {

  @Bean
  @Throws(Exception::class)
  fun securityFilterChain(http: HttpSecurity,
                          mvc: MvcRequestMatcher.Builder): SecurityFilterChain {
    http
      .cors(withDefaults())
      .csrf { it.disable() }
      .authorizeHttpRequests { authz ->
        authz
          .requestMatchers(
            mvc.pattern("/webjars/**"),
            mvc.pattern("/css/**"),
            mvc.pattern("/js/**")
          ).permitAll()
          .requestMatchers(
            mvc.pattern("/*.ico"),
            mvc.pattern("/*.png"),
            mvc.pattern("/*.svg"),
            mvc.pattern("/*.webapp")
          ).permitAll()
          .requestMatchers("/actuator/**").permitAll()
          .requestMatchers(
            "/v3/api-docs/**",
            "/swagger-ui.html",
            "/swagger-ui/**"
          ).permitAll()
          .requestMatchers(mvc.pattern("/api/auth/login")).permitAll()
          .requestMatchers(mvc.pattern("/api/hello/admin")).hasAuthority(AuthoritiesConstants.ADMIN)
          .anyRequest().authenticated()
      }
      .sessionManagement { it.sessionCreationPolicy(SessionCreationPolicy.STATELESS) }
      .oauth2ResourceServer { it.jwt(withDefaults()) }

    return http.build()
  }

  @Bean
  fun userDetailsService(userRepository: UserRepository): UserDetailsService =
    DomainUserDetailsService(userRepository)

  @Bean
  fun passwordEncoder(): PasswordEncoder = BCryptPasswordEncoder()

  @Bean
  fun authenticationManager(
    userDetailsService: UserDetailsService,
    passwordEncoder: PasswordEncoder
  ): AuthenticationManager {
    val provider = DaoAuthenticationProvider().apply {
      setUserDetailsService(userDetailsService)
      setPasswordEncoder(passwordEncoder)
    }
    return ProviderManager(provider)
  }

  @Bean
  fun mvc(introspector: HandlerMappingIntrospector): MvcRequestMatcher.Builder =
    MvcRequestMatcher.Builder(introspector)
}

JwtProperties

Java

package io.github.susimsek.springbootjweauthjpademo.config;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;

import java.time.Duration;

@Configuration
@ConfigurationProperties(prefix = "security.jwt")
@Data
public class JwtProperties {

    @Data
    public static class Pair {
        private String publicKey;
        private String privateKey;
        private String keyId;
    }

    private Pair signing;
    private Pair encryption;
    private String issuer;
    private Duration expirationDuration;
}

Kotlin

package io.github.susimsek.springbootjweauthjpademo.config

import org.springframework.boot.context.properties.ConfigurationProperties
import org.springframework.context.annotation.Configuration
import java.time.Duration

@Configuration
@ConfigurationProperties(prefix = "security.jwt")
class JwtProperties {

  class Pair {
    lateinit var publicKey: String
    lateinit var privateKey: String
    lateinit var keyId: String
  }

  lateinit var signing: Pair
  lateinit var encryption: Pair
  lateinit var issuer: String
  lateinit var expirationDuration: Duration
}

DatabaseConfig

Java

package io.github.susimsek.springbootjweauthjpademo.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.data.jpa.repository.config.EnableJpaAuditing;
import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
import org.springframework.transaction.annotation.EnableTransactionManagement;

@Configuration
@EnableJpaRepositories("io.github.susimsek.springbootjweauthjpademo.repository")
@EnableJpaAuditing(auditorAwareRef = "springSecurityAuditorAware")
@EnableTransactionManagement
public class DatabaseConfig {

}

Kotlin

package io.github.susimsek.springbootjweauthjpademo.config

import org.springframework.context.annotation.Configuration
import org.springframework.data.jpa.repository.config.EnableJpaAuditing
import org.springframework.data.jpa.repository.config.EnableJpaRepositories
import org.springframework.transaction.annotation.EnableTransactionManagement

@Configuration
@EnableJpaRepositories("io.github.susimsek.springbootjweauthjpademo.repository")
@EnableJpaAuditing(auditorAwareRef = "springSecurityAuditorAware")
@EnableTransactionManagement
class DatabaseConfig

🛠️ Step 4: JPA Integration

In this section, we define the JPA entities representing users, authorities, and their mappings, along with the Spring Data repository for loading users with their authorities.

• BaseEntity: Abstract superclass providing audit fields (createdAt, createdBy, updatedAt, updatedBy).
• Authority: authority table entity storing role data.
• User: user_identity table entity storing user credentials and profile.
• UserAuthorityMapping: user_authority_mapping join table entity linking users and authorities.
• UserAuthorityMappingId: Composite key class for UserAuthorityMapping.
• UserRepository: Spring Data JPA repository for User with an entity graph to load authorities.

BaseEntity

Java

package io.github.susimsek.springbootjweauthjpademo.entity;

import jakarta.persistence.Column;
import jakarta.persistence.EntityListeners;
import jakarta.persistence.MappedSuperclass;
import lombok.Getter;
import lombok.Setter;
import org.springframework.data.annotation.CreatedBy;
import org.springframework.data.annotation.CreatedDate;
import org.springframework.data.annotation.LastModifiedBy;
import org.springframework.data.annotation.LastModifiedDate;
import org.springframework.data.jpa.domain.support.AuditingEntityListener;

import java.time.Instant;

@MappedSuperclass
@EntityListeners(AuditingEntityListener.class)
@Getter
@Setter
public abstract class BaseEntity {

  @CreatedDate
  @Column(name = "created_at", nullable = false, updatable = false)
  private Instant createdAt;

  @CreatedBy
  @Column(name = "created_by", nullable = false, updatable = false, length = 50)
  private String createdBy;

  @LastModifiedDate
  @Column(name = "updated_at")
  private Instant updatedAt;

  @LastModifiedBy
  @Column(name = "updated_by", length = 50)
  private String updatedBy;
}

Kotlin

package io.github.susimsek.springbootjweauthjpademo.entity

import jakarta.persistence.Column
import jakarta.persistence.EntityListeners
import jakarta.persistence.MappedSuperclass
import org.springframework.data.annotation.CreatedBy
import org.springframework.data.annotation.CreatedDate
import org.springframework.data.annotation.LastModifiedBy
import org.springframework.data.annotation.LastModifiedDate
import org.springframework.data.jpa.domain.support.AuditingEntityListener
import java.time.Instant

@MappedSuperclass
@EntityListeners(AuditingEntityListener::class)
abstract class BaseEntity {

  @CreatedDate
  @Column(name = "created_at", nullable = false, updatable = false)
  lateinit var createdAt: Instant

  @CreatedBy
  @Column(name = "created_by", nullable = false, updatable = false, length = 50)
  lateinit var createdBy: String

  @LastModifiedDate
  @Column(name = "updated_at")
  var updatedAt: Instant? = null

  @LastModifiedBy
  @Column(name = "updated_by", length = 50)
  var updatedBy: String? = null
}

Authority

Java

package io.github.susimsek.springbootjweauthjpademo.entity;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.persistence.Table;
import lombok.AllArgsConstructor;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;
import org.hibernate.proxy.HibernateProxy;

import java.util.Objects;

@Entity
@Table(name = "authority")
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class Authority extends BaseEntity {

  @Id
  @Column(length = 36, nullable = false)
  private String id;

  @Column(length = 50, nullable = false, unique = true)
  private String name;

  @Column(length = 255)
  private String description;

  @Override
  public final boolean equals(Object obj) {
    if (this == obj) {
      return true;
    }
    if (!(obj instanceof Authority other)) {
      return false;
    }
    Class<?> objClass = obj instanceof HibernateProxy proxy
      ? proxy.getHibernateLazyInitializer().getPersistentClass()
      : obj.getClass();
    Class<?> thisClass = this instanceof HibernateProxy proxy
      ? proxy.getHibernateLazyInitializer().getPersistentClass()
      : this.getClass();
    if (!thisClass.equals(objClass)) {
      return false;
    }
    return id != null && Objects.equals(id, other.id);
  }

  @Override
  public final int hashCode() {
    return this instanceof HibernateProxy proxy
      ? proxy.getHibernateLazyInitializer().getPersistentClass().hashCode()
      : getClass().hashCode();
  }
}

Kotlin

package io.github.susimsek.springbootjweauthjpademo.entity

import jakarta.persistence.Column
import jakarta.persistence.Entity
import jakarta.persistence.Id
import jakarta.persistence.Table
import org.hibernate.proxy.HibernateProxy
import java.util.Objects

@Entity
@Table(name = "authority")
class Authority(
  @Id
  @Column(length = 36, nullable = false)
  var id: String,

  @Column(length = 50, nullable = false, unique = true)
  var name: String,

  @Column(length = 255)
  var description: String?
) : BaseEntity() {

  override fun equals(other: Any?): Boolean {
    if (this === other) return true
    if (other !is Authority) return false
    val objClass = (other as? HibernateProxy)?.hibernateLazyInitializer?.persistentClass ?: other::class.java
    val thisClass = (this as? HibernateProxy)?.hibernateLazyInitializer?.persistentClass ?: this::class.java
    if (thisClass != objClass) return false
    return id == other.id
  }

  override fun hashCode(): Int {
    return (this as? HibernateProxy)?.hibernateLazyInitializer?.persistentClass?.hashCode()
      ?: javaClass.hashCode()
  }
}

User

Java

package io.github.susimsek.springbootjweauthjpademo.entity;

import jakarta.persistence.CascadeType;
import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.FetchType;
import jakarta.persistence.Id;
import jakarta.persistence.NamedAttributeNode;
import jakarta.persistence.NamedEntityGraph;
import jakarta.persistence.NamedSubgraph;
import jakarta.persistence.OneToMany;
import jakarta.persistence.Table;
import lombok.AllArgsConstructor;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;
import org.hibernate.proxy.HibernateProxy;

import java.util.HashSet;
import java.util.Objects;
import java.util.Set;

@Entity
@Table(name = "user_identity")
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@NamedEntityGraph(
  name = "User.withAuthorities",
  attributeNodes = @NamedAttributeNode(value = "authorities", subgraph = "auth-subgraph"),
  subgraphs = @NamedSubgraph(
    name = "auth-subgraph",
    attributeNodes = @NamedAttributeNode("authority")
  )
)
public class User extends BaseEntity {

  @Id
  @Column(name = "id", length = 36, nullable = false, updatable = false)
  private String id;

  @Column(name = "username", length = 50, nullable = false, unique = true)
  private String username;

  @Column(name = "password", length = 100, nullable = false)
  private String password;

  @Column(name = "email", length = 100, nullable = false, unique = true)
  private String email;

  @Column(name = "first_name", length = 50)
  private String firstName;

  @Column(name = "last_name", length = 50)
  private String lastName;

  @Column(name = "enabled", nullable = false)
  private boolean enabled;

  @OneToMany(mappedBy = "user", fetch = FetchType.LAZY,
    cascade = CascadeType.ALL, orphanRemoval = true)
  private Set<UserAuthorityMapping> authorities = new HashSet<>();

  @Override
  public final boolean equals(Object obj) {
    if (this == obj) return true;
    if (!(obj instanceof User other)) return false;
    Class<?> objClass = (obj instanceof HibernateProxy hp
      ? hp.getHibernateLazyInitializer().getPersistentClass()
      : obj.getClass());
    Class<?> thisClass = (this instanceof HibernateProxy hp
      ? hp.getHibernateLazyInitializer().getPersistentClass()
      : this.getClass());
    if (!thisClass.equals(objClass)) return false;
    return id != null && id.equals(other.id);
  }

  @Override
  public final int hashCode() {
    return (this instanceof HibernateProxy hp
      ? hp.getHibernateLazyInitializer().getPersistentClass().hashCode()
      : getClass().hashCode());
  }
}

Kotlin

package io.github.susimsek.springbootjweauthjpademo.entity

import jakarta.persistence.CascadeType
import jakarta.persistence.Column
import jakarta.persistence.Entity
import jakarta.persistence.FetchType
import jakarta.persistence.Id
import jakarta.persistence.NamedAttributeNode
import jakarta.persistence.NamedEntityGraph
import jakarta.persistence.NamedSubgraph
import jakarta.persistence.OneToMany
import jakarta.persistence.Table
import org.hibernate.proxy.HibernateProxy
import java.util.*

@Entity
@Table(name = "user_identity")
@NamedEntityGraph(
  name = "User.withAuthorities",
  attributeNodes = [NamedAttributeNode(value = "authorities", subgraph = "auth-subgraph")],
  subgraphs = [
    NamedSubgraph(
      name = "auth-subgraph",
      attributeNodes = [NamedAttributeNode("authority")]
    )
  ]
)
class User(

  @Id
  @Column(name = "id", length = 36, nullable = false, updatable = false)
  var id: String,

  @Column(name = "username", length = 50, nullable = false, unique = true)
  var username: String,

  @Column(name = "password", length = 100, nullable = false)
  var password: String,

  @Column(name = "email", length = 100, nullable = false, unique = true)
  var email: String,

  @Column(name = "first_name", length = 50)
  var firstName: String? = null,

  @Column(name = "last_name", length = 50)
  var lastName: String? = null,

  @Column(name = "enabled", nullable = false)
  var enabled: Boolean = true

) : BaseEntity() {

  @OneToMany(
    mappedBy = "user",
    fetch = FetchType.LAZY,
    cascade = [CascadeType.ALL],
    orphanRemoval = true
  )
  var authorities: MutableSet<UserAuthorityMapping> = HashSet()

  override fun equals(other: Any?): Boolean {
    if (this === other) return true
    if (other !is User) return false
    val objClass = (other as? HibernateProxy)?.hibernateLazyInitializer?.persistentClass
      ?: other::class.java
    val thisClass = (this as? HibernateProxy)?.hibernateLazyInitializer?.persistentClass
      ?: this::class.java
    if (thisClass != objClass) return false
    return id == other.id
  }

  override fun hashCode(): Int =
    ((this as? HibernateProxy)?.hibernateLazyInitializer?.persistentClass?.hashCode()
      ?: javaClass.hashCode())
}

UserAuthorityMapping

Java

package io.github.susimsek.springbootjweauthjpademo.entity;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.FetchType;
import jakarta.persistence.Id;
import jakarta.persistence.IdClass;
import jakarta.persistence.JoinColumn;
import jakarta.persistence.ManyToOne;
import jakarta.persistence.Table;
import lombok.AllArgsConstructor;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;
import org.hibernate.proxy.HibernateProxy;

import java.util.Objects;

@Entity
@Table(name = "user_authority_mapping")
@IdClass(UserAuthorityMappingId.class)
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class UserAuthorityMapping extends BaseEntity {

  @Id
  @Column(name = "user_id", length = 36, nullable = false)
  private String userId;

  @Id
  @Column(name = "authority_id", length = 36, nullable = false)
  private String authorityId;

  @ManyToOne(fetch = FetchType.LAZY)
  @JoinColumn(name = "user_id", insertable = false, updatable = false)
  private User user;

  @ManyToOne(fetch = FetchType.LAZY)
  @JoinColumn(name = "authority_id", insertable = false, updatable = false)
  private Authority authority;

  @Override
  public final boolean equals(Object obj) {
    if (this == obj) return true;
    if (!(obj instanceof UserAuthorityMapping other)) return false;
    Class<?> objCls = (obj instanceof HibernateProxy hp
      ? hp.getHibernateLazyInitializer().getPersistentClass()
      : obj.getClass());
    Class<?> thisCls = (this instanceof HibernateProxy hp
      ? hp.getHibernateLazyInitializer().getPersistentClass()
      : this.getClass());
    if (!thisCls.equals(objCls)) return false;
    return userId != null && userId.equals(other.userId)
      && authorityId != null && authorityId.equals(other.authorityId);
  }

  @Override
  public final int hashCode() {
    return (this instanceof HibernateProxy hp
      ? hp.getHibernateLazyInitializer().getPersistentClass().hashCode()
      : Objects.hash(userId, authorityId));
  }
}

Kotlin

package io.github.susimsek.springbootjweauthjpademo.entity

import jakarta.persistence.*
import org.hibernate.proxy.HibernateProxy
import java.util.*

@Entity
@Table(name = "user_authority_mapping")
@IdClass(UserAuthorityMappingId::class)
data class UserAuthorityMapping(

  @Id
  @Column(name = "user_id", length = 36, nullable = false)
  var userId: String = "",

  @Id
  @Column(name = "authority_id", length = 36, nullable = false)
  var authorityId: String = "",

  @ManyToOne(fetch = FetchType.LAZY)
  @JoinColumn(name = "user_id", insertable = false, updatable = false)
  var user: User? = null,

  @ManyToOne(fetch = FetchType.LAZY)
  @JoinColumn(name = "authority_id", insertable = false, updatable = false)
  var authority: Authority? = null

) : BaseEntity() {

  override fun equals(other: Any?): Boolean {
    if (this === other) return true
    if (other !is UserAuthorityMapping) return false

    val objCls = (other as? HibernateProxy)?.hibernateLazyInitializer?.persistentClass
      ?: other::class.java
    val thisCls = (this as? HibernateProxy)?.hibernateLazyInitializer?.persistentClass
      ?: this::class.java

    if (thisCls != objCls) return false
    return userId == other.userId && authorityId == other.authorityId
  }

  override fun hashCode(): Int {
    return (this as? HibernateProxy)?.hibernateLazyInitializer?.persistentClass?.hashCode()
      ?: Objects.hash(userId, authorityId)
  }
}

UserAuthorityMappingId

Java

package io.github.susimsek.springbootjweauthjpademo.entity;

import java.io.Serializable;
import java.util.Objects;
import lombok.AllArgsConstructor;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;

@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class UserAuthorityMappingId implements Serializable {

  private String userId;
  private String authorityId;

  @Override
  public boolean equals(Object o) {
    if (this == o) return true;
    if (o == null || getClass() != o.getClass()) return false;
    UserAuthorityMappingId that = (UserAuthorityMappingId) o;
    return Objects.equals(userId, that.userId) &&
      Objects.equals(authorityId, that.authorityId);
  }

  @Override
  public int hashCode() {
    return Objects.hash(userId, authorityId);
  }
}

Kotlin

package io.github.susimsek.springbootjweauthjpademo.entity

import java.io.Serializable
import java.util.Objects

data class UserAuthorityMappingId(
  var userId: String = "",
  var authorityId: String = ""
) : Serializable {

  override fun equals(other: Any?): Boolean {
    if (this === other) return true
    if (other == null || this::class != other::class) return false
    other as UserAuthorityMappingId
    return userId == other.userId && authorityId == other.authorityId
  }

  override fun hashCode(): Int {
    return Objects.hash(userId, authorityId)
  }
}

UserRepository

Java

package io.github.susimsek.springbootjweauthjpademo.repository;

import io.github.susimsek.springbootjweauthjpademo.entity.User;
import org.springframework.data.jpa.repository.EntityGraph;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

import java.util.Optional;

@Repository
public interface UserRepository extends JpaRepository<User, String> {

  @EntityGraph("User.withAuthorities")
  Optional<User> findOneWithAuthoritiesByUsername(String username);
}

Kotlin

package io.github.susimsek.springbootjweauthjpademo.repository

import io.github.susimsek.springbootjweauthjpademo.entity.User
import org.springframework.data.jpa.repository.EntityGraph
import org.springframework.data.jpa.repository.JpaRepository
import org.springframework.stereotype.Repository
import java.util.Optional

@Repository
interface UserRepository : JpaRepository<User, String> {

  @EntityGraph("User.withAuthorities")
  fun findOneWithAuthoritiesByUsername(username: String): Optional<User>
}

🛠️ Step 5: Secure JWE Token Utilities

In this section, we define the core utility classes and constants needed to generate, encrypt, and resolve JSON Web Encryption (JWE) tokens in your Spring Boot application, integrate auditing, and implement a JPA-based user details service:

• AuthoritiesConstants: Centralize role names with the ROLE_ prefix.
• CookieBearerTokenResolver: Resolve bearer tokens from Authorization headers or HTTP cookies.
• CookieUtils: Create HTTP-only, secure cookies for access tokens.
• JweUtil: Sign (JWS) and encrypt (JWE) JWTs using RSA keys and Nimbus.
• KeyUtils: Build RSA JWKs from PEM‐encoded key material.
• SecurityUtils: Extract the current user’s login from the security context.
• SpringSecurityAuditorAware: Implement AuditorAware to provide the current user for auditing.
• DomainUserDetailsService: JPA-based UserDetailsService loading user and authorities for authentication.

These utilities form the foundation for a stateless, JWE‐based authentication flow in Spring Security.

AuthoritiesConstants

Java

package io.github.susimsek.springbootjweauthjpademo.security;

import lombok.AccessLevel;
import lombok.NoArgsConstructor;

@NoArgsConstructor(access = AccessLevel.PRIVATE)
public final class AuthoritiesConstants {
    public static final String ADMIN = "ROLE_ADMIN";
    public static final String USER = "ROLE_USER";
    public static final String ANONYMOUS = "ROLE_ANONYMOUS";
}

Kotlin

package io.github.susimsek.springbootjweauthjpademo.security

object AuthoritiesConstants {
  const val ADMIN = "ROLE_ADMIN"
  const val USER = "ROLE_USER"
  const val ANONYMOUS = "ROLE_ANONYMOUS"
}

CookieBearerTokenResolver

Java

package io.github.susimsek.springbootjweauthjpademo.security;

import jakarta.servlet.http.Cookie;
import jakarta.servlet.http.HttpServletRequest;
import lombok.Setter;
import org.springframework.http.HttpMethod;
import org.springframework.security.oauth2.core.OAuth2AuthenticationException;
import org.springframework.security.oauth2.server.resource.BearerTokenError;
import org.springframework.security.oauth2.server.resource.BearerTokenErrors;
import org.springframework.security.oauth2.server.resource.web.BearerTokenResolver;
import org.springframework.util.StringUtils;

import java.util.regex.Matcher;
import java.util.regex.Pattern;

@Setter
public class CookieBearerTokenResolver implements BearerTokenResolver {
    private static final String ACCESS_TOKEN_PARAMETER_NAME = "access_token";
    private static final Pattern AUTHORIZATION_PATTERN =
        Pattern.compile("^Bearer (?<token>[A-Za-z0-9-._~+/]+=*)$", Pattern.CASE_INSENSITIVE);

    private boolean allowFormEncodedBodyParameter = false;
    private boolean allowUriQueryParameter       = false;
    private boolean allowCookie                  = true;
    private String  bearerTokenHeaderName       = "Authorization";
    private String  cookieName                  = "accessToken";

    @Override
    public String resolve(HttpServletRequest request) {
        String headerToken = resolveFromAuthorizationHeader(request);
        String queryToken  = resolveAccessTokenFromQueryString(request);
        String bodyToken   = resolveAccessTokenFromBody(request);
        String cookieToken = (headerToken == null && queryToken == null && bodyToken == null)
            ? resolveFromCookie(request)
            : null;

        return resolveToken(headerToken, queryToken, bodyToken, cookieToken);
    }

    private String resolveFromAuthorizationHeader(HttpServletRequest request) {
        String authorization = request.getHeader(this.bearerTokenHeaderName);
        if (!StringUtils.hasText(authorization) || !authorization.toLowerCase().startsWith("bearer")) {
            return null;
        }
        Matcher matcher = AUTHORIZATION_PATTERN.matcher(authorization.trim());
        if (!matcher.matches()) {
            BearerTokenError error = BearerTokenErrors.invalidToken("Bearer token is malformed");
            throw new OAuth2AuthenticationException(error);
        }
        return matcher.group("token");
    }

    private String resolveAccessTokenFromQueryString(HttpServletRequest request) {
        if (allowUriQueryParameter && HttpMethod.GET.matches(request.getMethod())) {
            return resolveToken(request.getParameterValues(ACCESS_TOKEN_PARAMETER_NAME));
        }
        return null;
    }

    private String resolveAccessTokenFromBody(HttpServletRequest request) {
        if (allowFormEncodedBodyParameter
            && HttpMethod.POST.matches(request.getMethod())
            && "application/x-www-form-urlencoded".equals(request.getContentType())) {
            return resolveToken(request.getParameterValues(ACCESS_TOKEN_PARAMETER_NAME));
        }
        return null;
    }

    private String resolveFromCookie(HttpServletRequest request) {
        if (!allowCookie || request.getCookies() == null) {
            return null;
        }
        for (Cookie cookie : request.getCookies()) {
            if (cookieName.equals(cookie.getName())) {
                String val = cookie.getValue();
                return StringUtils.hasText(val) ? val : null;
            }
        }
        return null;
    }

    private String resolveToken(String... tokens) {
        String found = null;
        for (String token : tokens) {
            if (token == null) continue;
            if (found != null) {
                BearerTokenError error = BearerTokenErrors.invalidRequest("Found multiple bearer tokens in the request");
                throw new OAuth2AuthenticationException(error);
            }
            found = token;
        }
        if (found != null && found.isBlank()) {
            BearerTokenError error = BearerTokenErrors.invalidRequest("The requested token parameter is an empty string");
            throw new OAuth2AuthenticationException(error);
        }
        return found;
    }

Kotlin

package io.github.susimsek.springbootjweauthjpademo.security

import jakarta.servlet.http.Cookie
import jakarta.servlet.http.HttpServletRequest
import org.springframework.http.HttpMethod
import org.springframework.security.oauth2.core.OAuth2AuthenticationException
import org.springframework.security.oauth2.server.resource.BearerTokenError
import org.springframework.security.oauth2.server.resource.BearerTokenErrors
import org.springframework.security.oauth2.server.resource.web.BearerTokenResolver
import org.springframework.util.StringUtils
import java.util.regex.Pattern

class CookieBearerTokenResolver {
    var allowFormEncodedBodyParameter: Boolean = false
    var allowUriQueryParameter: Boolean = false
    var allowCookie: Boolean = true
    var bearerTokenHeaderName: String = "Authorization"
    var cookieName: String = "accessToken"

    companion object {
        private const val ACCESS_TOKEN_PARAMETER_NAME = "access_token"
        private val AUTHORIZATION_PATTERN =
            Pattern.compile("^Bearer (?<token>[A-Za-z0-9-._~+/]+=*)$", Pattern.CASE_INSENSITIVE)
    }

    fun resolve(request: HttpServletRequest): String? {
        val header = resolveFromAuthorizationHeader(request)
        val query  = if (allowUriQueryParameter && HttpMethod.GET.matches(request.method))
            request.getParameterValues(ACCESS_TOKEN_PARAMETER_NAME)?.let(::resolveToken)
        else null
        val body   = if (allowFormEncodedBodyParameter && HttpMethod.POST.matches(request.method)
            && request.contentType == "application/x-www-form-urlencoded")
            request.getParameterValues(ACCESS_TOKEN_PARAMETER_NAME)?.let(::resolveToken)
        else null
        val cookie = if (header == null && query == null && body == null)
            resolveFromCookie(request)
        else null
      return listOf(header, query, body, cookie).filterNotNull().let {
            if (it.size > 1) throw OAuth2AuthenticationException(BearerTokenErrors.invalidRequest("Found multiple bearer tokens"))
            it.firstOrNull()?: null
        }
    }

    private fun resolveFromAuthorizationHeader(request: HttpServletRequest): String? {
        val auth = request.getHeader(bearerTokenHeaderName) ?: return null
        if (!auth.startsWith("Bearer ", true)) return null
        val matcher = AUTHORIZATION_PATTERN.matcher(auth.trim())
        return if (matcher.matches()) matcher.group("token")
        else throw OAuth2AuthenticationException(BearerTokenErrors.invalidToken("Malformed token"))
    }

    private fun resolveFromCookie(request: HttpServletRequest): String? {
        if (!allowCookie) return null
        return request.cookies?.firstOrNull { it.name == cookieName }?.value?.takeIf { it.isNotBlank() }
    }

    private fun resolveToken(tokens: Array<String>): String? {
        return tokens.filter { it.isNotBlank() }.let {
            when {
                it.isEmpty() -> null
                it.size > 1   -> throw OAuth2AuthenticationException(BearerTokenErrors.invalidRequest("Multiple tokens"))
                else          -> it[0]
            }
        }
    }

CookieUtils

Java

package io.github.susimsek.springbootjweauthjpademo.security;

import io.github.susimsek.springbootjweauthjpademo.dto.TokenDTO;
import lombok.experimental.UtilityClass;
import org.springframework.http.ResponseCookie;

@UtilityClass
public class CookieUtils {

    private static final String COOKIE_NAME = "accessToken";

    public ResponseCookie createAccessTokenCookie(TokenDTO tokenDto) {
        return ResponseCookie.from(COOKIE_NAME, tokenDto.accessToken())
            .httpOnly(true)
            .secure(true)
            .path("/")
            .maxAge(tokenDto.accessTokenExpiresIn())
            .sameSite("Strict")
            .build();
    }
}

Kotlin

package io.github.susimsek.springbootjweauthjpademo.security

import io.github.susimsek.springbootjweauthjpademo.dto.TokenDTO
import org.springframework.http.ResponseCookie

object CookieUtils {

  private const val COOKIE_NAME = "accessToken"

  fun createAccessTokenCookie(tokenDto: TokenDTO): ResponseCookie {
    return ResponseCookie.from(COOKIE_NAME, tokenDto.accessToken())
      .httpOnly(true)
      .secure(true)
      .path("/")
      .maxAge(tokenDto.accessTokenExpiresIn())
      .sameSite("Strict")
      .build()
  }
}

JweUtil

Java

package io.github.susimsek.springbootjweauthjpademo.security;

import com.nimbusds.jose.EncryptionMethod;
import com.nimbusds.jose.JOSEException;
import com.nimbusds.jose.JWEAlgorithm;
import com.nimbusds.jose.JWEHeader;
import com.nimbusds.jose.JWEObject;
import com.nimbusds.jose.Payload;
import com.nimbusds.jose.crypto.RSAEncrypter;
import com.nimbusds.jose.jwk.RSAKey;
import io.github.susimsek.springbootjweauthjpademo.config.JwtProperties;
import io.github.susimsek.springbootjweauthjpademo.dto.TokenDTO;
import lombok.RequiredArgsConstructor;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.oauth2.jose.jws.SignatureAlgorithm;
import org.springframework.security.oauth2.jwt.*;
import org.springframework.stereotype.Component;

import java.time.Instant;
import java.util.List;

import static io.github.susimsek.springbootjweauthjpademo.security.SecurityUtils.AUTHORITIES_KEY;

@Component
@RequiredArgsConstructor
public class JweUtil {

    private final JwtEncoder jwtEncoder;
    private final RSAKey signingKey;
    private final RSAKey encryptionKey;
    private final JwtProperties props;

    public TokenDTO generateToken(Authentication authentication) throws JOSEException {
        String subject = authentication.getName();
        List<String> roles = authentication.getAuthorities()
            .stream()
            .map(GrantedAuthority::getAuthority)
            .toList();

        Instant now = Instant.now();
        long expiresIn = props.getExpirationDuration().getSeconds();
        Instant exp = now.plusSeconds(expiresIn);

        JwtClaimsSet claims = JwtClaimsSet.builder()
            .issuer(props.getIssuer())
            .issuedAt(now)
            .expiresAt(exp)
            .subject(subject)
            .claim(AUTHORITIES_KEY, roles)
            .build();

        JwsHeader jwsHeader = JwsHeader.with(SignatureAlgorithm.RS256)
            .keyId(signingKey.getKeyID())
            .build();

        String jws = jwtEncoder
            .encode(JwtEncoderParameters.from(jwsHeader, claims))
            .getTokenValue();

        JWEHeader jweHeader = new JWEHeader.Builder(JWEAlgorithm.RSA_OAEP_256, EncryptionMethod.A128GCM)
            .contentType("JWT")
            .keyID(encryptionKey.getKeyID())
            .build();

        JWEObject jweObject = new JWEObject(jweHeader, new Payload(jws));
        jweObject.encrypt(new RSAEncrypter(encryptionKey.toRSAPublicKey()));
        String token = jweObject.serialize();

        return new TokenDTO(token, "Bearer", expiresIn);
    }
}

Kotlin

package io.github.susimsek.springbootjweauthjpademo.security

import com.nimbusds.jose.EncryptionMethod
import com.nimbusds.jose.JOSEException
import com.nimbusds.jose.JWEAlgorithm
import com.nimbusds.jose.JWEHeader
import com.nimbusds.jose.JWEObject
import com.nimbusds.jose.Payload
import com.nimbusds.jose.crypto.RSAEncrypter
import com.nimbusds.jose.jwk.RSAKey
import io.github.susimsek.springbootjweauthjpademo.config.JwtProperties
import io.github.susimsek.springbootjweauthjpademo.dto.TokenDTO
import lombok.RequiredArgsConstructor
import org.springframework.security.core.Authentication
import org.springframework.security.oauth2.jose.jws.SignatureAlgorithm
import org.springframework.security.oauth2.jwt.JwtClaimsSet
import org.springframework.security.oauth2.jwt.JwtEncoder
import org.springframework.security.oauth2.jwt.JwtEncoderParameters
import org.springframework.stereotype.Component

import java.time.Instant

@Component
@RequiredArgsConstructor
class JweUtil(
    private val jwtEncoder: JwtEncoder,
    private val signingKey: RSAKey,
    private val encryptionKey: RSAKey,
    private val props: JwtProperties
) {
    fun generateToken(authentication: Authentication): TokenDTO {
        val subject = authentication.name
        val roles = authentication.authorities.map { it.authority }

        val now = Instant.now()
        val expiresIn = props.expirationDuration.seconds
        val exp = now.plusSeconds(expiresIn)

        val claims = JwtClaimsSet.builder()
            .issuer(props.issuer)
            .issuedAt(now)
            .expiresAt(exp)
            .subject(subject)
            .claim(AUTHORITIES_KEY, roles)
            .build()

        val jwsHeader = org.springframework.security.oauth2.jwt.JwsHeader.with(SignatureAlgorithm.RS256)
            .keyId(signingKey.keyID)
            .build()

        val jws = jwtEncoder
            .encode(JwtEncoderParameters.from(jwsHeader, claims))
            .tokenValue

        val jweHeader = JWEHeader.Builder(JWEAlgorithm.RSA_OAEP_256, EncryptionMethod.A128GCM)
            .contentType("JWT")
            .keyID(encryptionKey.keyID)
            .build()

        val jweObject = JWEObject(jweHeader, Payload(jws))
        jweObject.encrypt(RSAEncrypter(encryptionKey.toRSAPublicKey()))
        val token = jweObject.serialize()

        return TokenDTO(token, "Bearer", expiresIn)
    }
}

KeyUtils

Java

package io.github.susimsek.springbootjweauthjpademo.security;

import com.nimbusds.jose.JWEAlgorithm;
import com.nimbusds.jose.JWSAlgorithm;
import com.nimbusds.jose.jwk.KeyUse;
import com.nimbusds.jose.jwk.RSAKey;
import lombok.experimental.UtilityClass;

import java.security.KeyFactory;
import java.security.interfaces.RSAPrivateKey;
import java.security.interfaces.RSAPublicKey;
import java.security.spec.PKCS8EncodedKeySpec;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;

@UtilityClass
public class KeyUtils {
    public RSAKey buildRsaKey(
            String pubPem,
            String privPem,
            String kid,
            boolean forSign
    ) throws Exception {
        String pubContent = pubPem
            .replace("-----BEGIN PUBLIC KEY-----", "")
            .replace("-----END PUBLIC KEY-----", "")
            .replaceAll("\\s", "");
        String privContent = privPem
            .replace("-----BEGIN PRIVATE KEY-----", "")
            .replace("-----END PRIVATE KEY-----", "")
            .replaceAll("\\s", "");

        byte[] decodedPub = Base64.getDecoder().decode(pubContent);
        byte[] decodedPriv = Base64.getDecoder().decode(privContent);

        KeyFactory kf = KeyFactory.getInstance("RSA");
        RSAPublicKey publicKey = (RSAPublicKey) kf.generatePublic(new X509EncodedKeySpec(decodedPub));
        RSAPrivateKey privateKey = (RSAPrivateKey) kf.generatePrivate(new PKCS8EncodedKeySpec(decodedPriv));

        RSAKey.Builder builder = new RSAKey.Builder(publicKey)
            .privateKey(privateKey)
            .keyID(kid);

        if (forSign) {
            builder
                .algorithm(JWSAlgorithm.RS256)
                .keyUse(KeyUse.SIGNATURE);
        } else {
            builder
                .algorithm(JWEAlgorithm.RSA_OAEP_256)
                .keyUse(KeyUse.ENCRYPTION);
        }

        return builder.build();
    }
}

Kotlin

package io.github.susimsek.springbootjweauthjpademo.security

import com.nimbusds.jose.JWEAlgorithm
import com.nimbusds.jose.JWSAlgorithm
import com.nimbusds.jose.jwk.KeyUse
import com.nimbusds.jose.jwk.RSAKey
import java.security.KeyFactory
import java.security.interfaces.RSAPrivateKey
import java.security.interfaces.RSAPublicKey
import java.security.spec.PKCS8EncodedKeySpec
import java.security.spec.X509EncodedKeySpec
import java.util.Base64

object KeyUtils {
    @JvmStatic
    @Throws(Exception::class)
    fun buildRsaKey(
        pubPem: String,
        privPem: String,
        kid: String,
        forSign: Boolean
    ): RSAKey {
        val pubContent = pubPem
            .replace("-----BEGIN PUBLIC KEY-----", "")
            .replace("-----END PUBLIC KEY-----", "")
            .replace(Regex("\\s"), "")
        val privContent = privPem
            .replace("-----BEGIN PRIVATE KEY-----", "")
            .replace("-----END PRIVATE KEY-----", "")
            .replace(Regex("\\s"), "")

        val decodedPub = Base64.getDecoder().decode(pubContent)
        val decodedPriv = Base64.getDecoder().decode(privContent)

        val kf = KeyFactory.getInstance("RSA")
        val publicKey = kf.generatePublic(X509EncodedKeySpec(decodedPub)) as RSAPublicKey
        val privateKey = kf.generatePrivate(PKCS8EncodedKeySpec(decodedPriv)) as RSAPrivateKey

        val builder = RSAKey.Builder(publicKey)
            .privateKey(privateKey)
            .keyID(kid)

        if (forSign) {
            builder
                .algorithm(JWSAlgorithm.RS256)
                .keyUse(KeyUse.SIGNATURE)
        } else {
            builder
                .algorithm(JWEAlgorithm.RSA_OAEP_256)
                .keyUse(KeyUse.ENCRYPTION)
        }

        return builder.build()
    }
}

SecurityUtils

Java

package io.github.susimsek.springbootjweauthjpademo.security;

import lombok.experimental.UtilityClass;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.oauth2.jwt.Jwt;

import java.util.Optional;

@UtilityClass
public class SecurityUtils {

    public static final String AUTHORITIES_KEY = "auth";

    public Optional<String> getCurrentUserLogin() {
        var ctx = SecurityContextHolder.getContext();
        return Optional.ofNullable(extractPrincipal(ctx.getAuthentication()));
    }

    private String extractPrincipal(Authentication authentication) {
        if (authentication == null) {
            return null;
        }
        Object principal = authentication.getPrincipal();
        if (principal instanceof Jwt jwt) {
            return jwt.getSubject();
        }
        if (principal instanceof UserDetails ud) {
            return ud.getUsername();
        }
        if (principal instanceof String username) {
            return username;
        }
        return null;
    }
}

Kotlin

package io.github.susimsek.springbootjweauthjpademo.security

import org.springframework.security.core.Authentication
import org.springframework.security.core.context.SecurityContextHolder
import org.springframework.security.core.userdetails.UserDetails
import org.springframework.security.oauth2.jwt.Jwt
import java.util.Optional

object SecurityUtils {
  const val AUTHORITIES_KEY = "auth"

  fun getCurrentUserLogin(): Optional<String> {
    val authentication: Authentication? = SecurityContextHolder.getContext().authentication
    return Optional.ofNullable(extractPrincipal(authentication))
  }

  private fun extractPrincipal(authentication: Authentication?): String? {
    return when (val principal = authentication?.principal) {
      is Jwt -> principal.subject
      is UserDetails -> principal.username
      is String -> principal
      else -> null
    }
  }
}

DomainUserDetailsService

Java

package io.github.susimsek.springbootjweauthjpademo.security;

import io.github.susimsek.springbootjweauthjpademo.entity.User;
import io.github.susimsek.springbootjweauthjpademo.repository.UserRepository;
import lombok.RequiredArgsConstructor;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.core.userdetails.UsernameNotFoundException;

import java.util.List;
import java.util.stream.Collectors;

@RequiredArgsConstructor
public class DomainUserDetailsService implements UserDetailsService {

  private final UserRepository userRepository;

  @Override
  public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {
    User user = userRepository.findOneWithAuthoritiesByUsername(username)
      .orElseThrow(() -> new UsernameNotFoundException("User not found with username: " + username));

    List<GrantedAuthority> authorities = user.getAuthorities().stream()
      .map(mapping -> mapping.getAuthority().getName())
      .map(SimpleGrantedAuthority::new)
      .collect(Collectors.toList());

    return new org.springframework.security.core.userdetails.User(
      user.getUsername(),
      user.getPassword(),
      user.isEnabled(),  // enabled
      true,              // accountNonExpired
      true,              // credentialsNonExpired
      true,              // accountNonLocked
      authorities
    );
  }
}

Kotlin

package io.github.susimsek.springbootjweauthjpademo.security

import io.github.susimsek.springbootjweauthjpademo.repository.UserRepository
import org.springframework.security.core.GrantedAuthority
import org.springframework.security.core.authority.SimpleGrantedAuthority
import org.springframework.security.core.userdetails.UserDetails
import org.springframework.security.core.userdetails.UserDetailsService
import org.springframework.security.core.userdetails.UsernameNotFoundException
import java.util.stream.Collectors

class DomainUserDetailsService(
  private val userRepository: UserRepository
) : UserDetailsService {
  override fun loadUserByUsername(username: String): UserDetails {
    val user = userRepository.findOneWithAuthoritiesByUsername(username)
      .orElseThrow { UsernameNotFoundException("User not found with username: $username") }

    val authorities: List<GrantedAuthority> = user.authorities.stream()
      .map { SimpleGrantedAuthority(it.authority.name) }
      .collect(Collectors.toList())

    return org.springframework.security.core.userdetails.User(
      user.username,
      user.password,
      user.enabled,
      true,
      true,
      true,
      authorities
    )
  }
}

SpringSecurityAuditorAware

Java

package io.github.susimsek.springbootjweauthjpademo.security;

import org.springframework.data.domain.AuditorAware;
import org.springframework.lang.NonNull;
import org.springframework.stereotype.Component;

import java.util.Optional;

@Component
public class SpringSecurityAuditorAware implements AuditorAware<String> {

  @Override
  @NonNull
  public Optional<String> getCurrentAuditor() {
    return Optional.of(SecurityUtils.getCurrentUserLogin().orElse("system"));
  }
}

Kotlin

package io.github.susimsek.springbootjweauthjpademo.security

import org.springframework.data.domain.AuditorAware
import org.springframework.lang.NonNull
import org.springframework.stereotype.Component

@Component
class SpringSecurityAuditorAware : AuditorAware<String> {
    @NonNull
    override fun getCurrentAuditor(): Optional<String> =
        Optional.of(SecurityUtils.getCurrentUserLogin().orElse("system"))
}

🛠️ Step 6: Authentication & Protected Endpoints

In this section, we define the REST controllers and DTOs necessary for:

• AuthController: Authenticate users, issue JWE tokens, and set secure cookies.
• HelloController: Expose protected resource endpoints for authenticated users and admin-specific paths.
• LoginRequestDTO: Model the login request payload (username/password).
• TokenDTO: Model the authentication response including token and expiration.

These components complete the stateless authentication flow by handling login, token issuance, cookie management, and resource protection.

In this section, we expose REST controllers and DTOs to handle user authentication, token issuance, and protected resource access.

AuthController

Java

package io.github.susimsek.springbootjweauthjpademo.controller;

import io.github.susimsek.springbootjweauthjpademo.dto.LoginRequestDTO;
import io.github.susimsek.springbootjweauthjpademo.dto.TokenDTO;
import io.github.susimsek.springbootjweauthjpademo.security.CookieUtils;
import io.github.susimsek.springbootjweauthjpademo.security.JweUtil;
import lombok.RequiredArgsConstructor;
import org.springframework.http.HttpHeaders;
import org.springframework.http.ResponseCookie;
import org.springframework.http.ResponseEntity;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequiredArgsConstructor
@RequestMapping("/api/auth")
public class AuthController {

    private final AuthenticationManager authenticationManager;
    private final JweUtil jweUtil;

    @PostMapping("/login")
    public ResponseEntity<TokenDTO> login(@RequestBody LoginRequestDTO loginRequest) throws Exception {
        // Authenticate user
        var authToken = new UsernamePasswordAuthenticationToken(
            loginRequest.username(), loginRequest.password()
        );
        Authentication auth = authenticationManager.authenticate(authToken);
        SecurityContextHolder.getContext().setAuthentication(auth);

        // Generate JWE token and cookie
        TokenDTO tokenDto = jweUtil.generateToken(auth);
        ResponseCookie cookie = CookieUtils.createAccessTokenCookie(tokenDto);

        return ResponseEntity.ok()
            .header(HttpHeaders.SET_COOKIE, cookie.toString())
            .body(tokenDto);
    }
}

Kotlin

package io.github.susimsek.springbootjweauthjpademo.controller

import io.github.susimsek.springbootjweauthjpademo.dto.LoginRequestDTO
import io.github.susimsek.springbootjweauthjpademo.dto.TokenDTO
import io.github.susimsek.springbootjweauthjpademo.security.CookieUtils
import io.github.susimsek.springbootjweauthjpademo.security.JweUtil
import lombok.RequiredArgsConstructor
import org.springframework.http.HttpHeaders
import org.springframework.http.ResponseCookie
import org.springframework.http.ResponseEntity
import org.springframework.security.authentication.AuthenticationManager
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken
import org.springframework.security.core.Authentication
import org.springframework.security.core.context.SecurityContextHolder
import org.springframework.web.bind.annotation.PostMapping
import org.springframework.web.bind.annotation.RequestBody
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController

@RestController
@RequiredArgsConstructor
@RequestMapping("/api/auth")
class AuthController(
    private val authenticationManager: AuthenticationManager,
    private val jweUtil: JweUtil
) {

    @PostMapping("/login")
    fun login(@RequestBody loginRequest: LoginRequestDTO): ResponseEntity<TokenDTO> {
        val authToken = UsernamePasswordAuthenticationToken(
            loginRequest.username, loginRequest.password
        )
        val auth: Authentication = authenticationManager.authenticate(authToken)
        SecurityContextHolder.getContext().authentication = auth

        val tokenDto: TokenDTO = jweUtil.generateToken(auth)
        val cookie: ResponseCookie = CookieUtils.createAccessTokenCookie(tokenDto)

        return ResponseEntity.ok()
            .header(HttpHeaders.SET_COOKIE, cookie.toString())
            .body(tokenDto)
    }
}

HelloController

Java

package io.github.susimsek.springbootjweauthjpademo.controller;

import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.jwt.Jwt;
import org.springframework.web.bind.annotation.*;

import static io.github.susimsek.springbootjweauthjpademo.security.SecurityUtils.AUTHORITIES_KEY;

@RestController
@RequestMapping("/api/hello")
public class HelloController {

    @GetMapping
    public String helloAll(@AuthenticationPrincipal Jwt jwt) {
        String user = jwt.getSubject();
        var roles = jwt.getClaimAsStringList(AUTHORITIES_KEY);
        return "Hello, " + user + "! Your roles: " + roles;
    }

    @GetMapping("/admin")
    public String helloAdmin(@AuthenticationPrincipal Jwt jwt) {
        return "Hello Admin, " + jwt.getSubject() + "!";
    }
}

Kotlin

package io.github.susimsek.springbootjweauthjpademo.controller

import org.springframework.security.core.annotation.AuthenticationPrincipal
import org.springframework.security.oauth2.jwt.Jwt
import org.springframework.web.bind.annotation.*

import io.github.susimsek.springbootjweauthjpademo.security.SecurityUtils.AUTHORITIES_KEY

@RestController
@RequestMapping("/api/hello")
class HelloController {

    @GetMapping
    fun helloAll(@AuthenticationPrincipal jwt: Jwt): String {
        val user = jwt.subject
        val roles = jwt.getClaimAsStringList(AUTHORITIES_KEY)
        return "Hello, \$user! Your roles: \$roles"
    }

    @GetMapping("/admin")
    fun helloAdmin(@AuthenticationPrincipal jwt: Jwt): String {
        return "Hello Admin, \${jwt.subject}!"
    }
}

LoginRequestDTO

Java

package io.github.susimsek.springbootjweauthjpademo.dto;

public record LoginRequestDTO(
    String username,
    String password
) { }

Kotlin

package io.github.susimsek.springbootjweauthjpademo.dto

data class LoginRequestDTO(
    val username: String,
    val password: String
)

TokenDTO

Java

package io.github.susimsek.springbootjweauthjpademo.dto;

public record TokenDTO(
    String accessToken,
    String tokenType,
    long accessTokenExpiresIn
) {}

Kotlin

package io.github.susimsek.springbootjweauthjpademo.dto

import kotlin.Long

data class TokenDTO(
    val accessToken: String,
    val tokenType: String,
    val accessTokenExpiresIn: Long
)

▶️ Run the App

./mvnw spring-boot:run
# or
gradle bootRun

🧪 Test Endpoints

In this section, we clarify Test Endpoints and summarize the key points you will apply in implementation.

Admin Flow

Login as admin and capture the JWE token from the Set-Cookie header:

curl -i -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"adminpass"}'

• Set-Cookie header contains accessToken=<jwe-token>
• Response body:

{
  "accessToken": "<jwe-token>",
  "tokenType": "Bearer",
  "accessTokenExpiresIn": 3600
}

Use cookie to access hello endpoint:

curl -b "accessToken=<jwe-token>" http://localhost:8080/api/hello

Use Authorization header instead:

curl -H "Authorization: Bearer <jwe-token>" http://localhost:8080/api/hello

Access admin-only endpoint:

curl -H "Authorization: Bearer <jwe-token>" http://localhost:8080/api/hello/admin

User Flow

Login as user and capture JWE token from cookie:

curl -i -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"user","password":"userpass"}'

• Set-Cookie header contains accessToken=<jwe-token>

Use cookie to access hello endpoint:

curl -b "accessToken=<jwe-token>" http://localhost:8080/api/hello

Use Authorization header:

curl -H "Authorization: Bearer <jwe-token>" http://localhost:8080/api/hello

Attempt admin endpoint (should be 403 Forbidden):

curl -H "Authorization: Bearer <jwe-token>" http://localhost:8080/api/hello/admin
# HTTP/1.1 403 Forbidden

🏁 Conclusion

You now have a practical Spring Boot JWE Authentication with JPA implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why Combine LDAP & JWE?

In this section, we clarify Why Combine LDAP & JWE? and summarize the key points you will apply in implementation.

• External Directory: Centralize user management with LDAP (e.g., corporate or embedded directory).
• Integrity & Confidentiality: Sign tokens (JWS) and encrypt payloads (JWE) for secure claims transport.
• Standards-based: Leverage JOSE (JWS & JWE) and Spring Security’s OAuth2 Resource Server.
• Role-based Access: Map LDAP groups to ROLE_USER / ROLE_ADMIN automatically.

📋 Prerequisites

In this section, we clarify Prerequisites and summarize the key points you will apply in implementation.

• ☕ Java Development Kit (JDK) 17 or higher
• 📦 Spring Boot 3.2+
• 🗄️ LDAP (Embedded via Spring Boot or external)
• 🔤 IDE (IntelliJ IDEA, Eclipse)

🛠️ Step 1: Add Dependencies

Include these in your pom.xml or build.gradle file.

Maven:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.security</groupId>
  <artifactId>spring-security-oauth2-resource-server</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.security</groupId>
  <artifactId>spring-security-ldap</artifactId>
</dependency>
<dependency>
  <groupId>com.unboundid</groupId>
  <artifactId>unboundid-ldapsdk</artifactId>
</dependency>
<dependency>
  <groupId>org.projectlombok</groupId>
  <artifactId>lombok</artifactId>
  <optional>true</optional>
</dependency>

Gradle:

implementation 'org.springframework.boot:spring-boot-starter-web'
implementation 'org.springframework.security:spring-security-oauth2-resource-server'
implementation 'org.springframework.security:spring-security-ldap'
implementation 'com.unboundid:unboundid-ldapsdk'
compileOnly 'org.projectlombok:lombok'

🛠️ Step 2: LDAP and Keys Configuration

Define your embedded LDAP directory, user/group structure, and RSA key properties in your application.yml and schema.ldif:

application.yml

spring:
  ldap:
    embedded:
      ldif: classpath:schema.ldif
      base-dn: dc=suaybsimsek,dc=com
      port: 8389
    urls: ldap://localhost:8389
    base: dc=suaybsimsek,dc=com
security:
  jwt:
    issuer: demo-issuer
    expiration-duration: 3600s
    signing:
      key-id: signing-key
      public-key: |-
        -----BEGIN PUBLIC KEY-----
        MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAjZEcz5itWkDGOSqZdB5P
        JE0ccOCckskp0hN3kQbT1qnv+9/k66jlWgVi4HSTppwdNF/Ylu5u541Qj+Okyg+u
        8o2PvKo5CfgvTDsFLTrZHUXU6hCSGatLAQoeN6lT8wzov2r4DFecXrIqcO6SvMB5
        ecPqsfiTi4trsNKgJ4cWS6gILH62ISd1ipUadfpnUzDMO1OulV0CJNV6bcBk7Es9
        RW6AHfg9j8osSanpwvRM4MJkB0SRxYUnrN9faGpkBZISZJ8TShhaTHEGfSNgKe5y
        8iu+AMGGZu8DYczVmqS3Ske1fq6y5HEGCma7Mo019GmwKeHBo1obuET6cZRygj4y
        twIDAQAB
        -----END PUBLIC KEY-----
      private-key: |-
        -----BEGIN PRIVATE KEY-----
        MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQCNkRzPmK1aQMY5
        Kpl0Hk8kTRxw4JySySnSE3eRBtPWqe/73+TrqOVaBWLgdJOmnB00X9iW7m7njVCP
        46TKD67yjY+8qjkJ+C9MOwUtOtkdRdTqEJIZq0sBCh43qVPzDOi/avgMV5xesipw
        7pK8wHl5w+qx+JOLi2uw0qAnhxZLqAgsfrYhJ3WKlRp1+mdTMMw7U66VXQIk1Xpt
        wGTsSz1FboAd+D2PyixJqenC9EzgwmQHRJHFhSes319oamQFkhJknxNKGFpMcQZ9
        I2Ap7nLyK74AwYZm7wNhzNWapLdKR7V+rrLkcQYKZrsyjTX0abAp4cGjWhu4RPpx
        lHKCPjK3AgMBAAECggEABMo/sNCIMREXA/EqjxDFecN4LmOTOK5A0YBiH9Cc01sd
        qSaavtSQqhqbjV+0bUNEA7UohXbc3s3bx3qa5VFhiIh8sBQMaQdyRkCK/MxMc16d
        BSx5XQ/8MjVO73A1zHgH2g47BWPjgRrDL94KrgNPOO0FoG76QxL9GlcOHzhFa1rf
        xbb2auLBtflKy+5TZNnB/sbFC9ISpWywzfblD2Fsvxupl0vNWtA0Y2rPbKMZRnY+
        V6NC38yxW3HHAdWQRYLGOitM59I0HBgnjQKzTBNIsjPnJA2BSZvMBtQ1e3RQV0qE
        8VVoktZ8A0KDUxqdKWYlGYAY5hIw1y3UUsPRUbS3fQKBgQDAZehu+Kb5Sw+h00Qu
        vViNHDvi0PwmhQrHVpgjrppCnWsTk6FJFm+EBLY+87usXuRCnfZ1semb6P+yjLh2
        bJ9IXIrFAztcyE+7eZfn0H7mHA7E2ICKTjNdKbjy8kHViHpgdXREnAOrFTTk/BqW
        dq+weG2OuxYczWsY4XliWaVyiwKBgQC8XYExpSmoyI37o+jr9405k30tbGUw4X+/
        xYOvSUuafI8IOSLfKTpsvkMN3hxpJO6apIRAjOALbotKUA5FrHQPenuBWOr3mBJT
        euLiaWphqU8YN5dbNd+JhC/Jh5DLhY5FpB2Fv2MKSoF7+onpjDy9pEU5aReeBB0v
        ekUw4nWiBQKBgHxyrnjxP1frFG5xMB4nfZqw04+v7BmiXsl3mqsh6kgCeNtN17pl
        17YGMjfgAdnJ+02XzW5tqRSfDp3YZgy7z//HVD+BCqnGK8SxLu/ULfD73xW2kNZl
        JNYzAZ2r06eiQr4X2x/x5nGIIxGmfDAtDxFPpFX5b6ErwgVy+sgCAoFnAoGAWSpu
        EMEdQk+FnnwNsz2g9YNSuyDXmdb08SOfXWd1yXBzCLJ7RmYuyPEbrsHYcxFPfZap
        ICFPoTm35/qTdvnWiskxE56yw3eSHUBLjF/YQtixn0YZeMy8v0z6jgyFR0I2gdLZ
        QsnBKUrxlm2XwR1oV2Eef7m2u085PZNEk4pvor0CgYA6n060r48/CgRVslAeGder
        fZ3n+2ru8q2UVB38evepjLifn5+tKdFzZ7/NckXMC0NOVzm74qG46VFLMw5TtyT4
        /hRvGSYxA6dMjXy+tcrAns9Isrz2PnYFntlbhU6hw0um809tFunbvITfyeOjAsDW
        stC4thnhzXXT1Y3RfFtYEg==
        -----END PRIVATE KEY-----
    encryption:
      key-id: encryption-key
      public-key: |-
        -----BEGIN PUBLIC KEY-----
        MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtU7Vu4tML8qg9BISaUH0
        BTU0+qkHJS3TUl3R0hEPttZJGf8EgT7bpWqRjdhMC2SYt2ifNF82EgMo/eva1rLn
        wYtCsxjJ7oB4U2m16/JKHtphmMUGhSLgbp+Y8pGAQ+P6u4HLlI0qbL92Syb6QCTr
        nYIlzZ2uUAvUQg/SbuAvdS4kdauZtpMNbhryusMVvILVBC5yUhfLJAkjbU3qWo/n
        2NKPr4kjwwFh6FaAf0HLsXCFmJbPPok6WMZeDqPORPZCt5gU2t04fS7s/2SSbhQ/
        i+7yyT4pl44cUlNLLN3Qo73sai5H90q7Dvmk3M5/YMJB0Ueyb705LHyOO5xA618s
        qQIDAQAB
        -----END PUBLIC KEY-----
      private-key: |-
        -----BEGIN PRIVATE KEY-----
        MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC1TtW7i0wvyqD0
        EhJpQfQFNTT6qQclLdNSXdHSEQ+21kkZ/wSBPtulapGN2EwLZJi3aJ80XzYSAyj9
        69rWsufBi0KzGMnugHhTabXr8koe2mGYxQaFIuBun5jykYBD4/q7gcuUjSpsv3ZL
        JvpAJOudgiXNna5QC9RCD9Ju4C91LiR1q5m2kw1uGvK6wxW8gtUELnJSF8skCSNt
        Tepaj+fY0o+viSPDAWHoVoB/QcuxcIWYls8+iTpYxl4Oo85E9kK3mBTa3Th9Luz/
        ZJJuFD+L7vLJPimXjhxSU0ss3dCjvexqLkf3SrsO+aTczn9gwkHRR7JvvTksfI47
        nEDrXyypAgMBAAECggEAREnJHrY8n9OGA+e6n4KD0mJT7gUz98Dm0yMbIC/k50yW
        hAAVRkjSmd8lq3NIURI2ov342NTznJ0sF1d6OVtxBujY2nP/uqEQsPoj1xaO7Ef8
        cnnjFsooFgJurQ44bVm02mLstqrky8jhWTT5FKfTRqP6cRNu0B9kdu1WqQQvW8a/
        C8xD8XUFzzJFQsEstJ076NjlZNH3EeqFiLxyVdV7tPEJRnOe2V2BAAgda3ByA6Jc
        Nd4xYHTVr5rZ+KES9gaAgb86+S7hNigsxz5Gp58NimLEyz1Qd+d9QCgPRgKOV5Uq
        0ci6c28ZrxW9wa/2CGCpoow1V7hRy1fZ24g2Tz91cQKBgQDbSdP/FQYuem0pUf8u
        mA/niEC8Jz30FW3ix5aqbQ8YRudK48Xy8F7AWnlS0wT2k/Xaeppn9YSPK4HlsNk2
        1gnpNfzdqXpJQtuxcPPeFNzUdXzBrsLXYqtlhOX/afrzqMhp73gkqoxXtqwD7BqN
        VfMcVXsWrEZQrRPBn/RUnnLdJwKBgQDTqUGupm93UlhoPgLXHGF/seQwPPHcU6lS
        SS9l512Ie21B+vZecgO4r77BXJwbY4rZVA5/m+wrsNmsT2f8yfdbs84cBDDWiKy5
        t2Um8zrus+BCIffxc9Fck9/htK33jLLcYwdSAm3a9pJxR9f/kAdredSTGBNJ3W/2
        rfh3cdNprwKBgDi7WfBFRSsjGzi0cPth9cNlubGzyVBrdtlT34PJ4Tzboxz53o1i
        aHEFNxwZYdBVKSbTzzyUBS5xCBMfdKK+LyQ5hmjmXq+zb1jxqvXKmfMRTixhhSDp
        8wO5pTM1/Omqwea+QGvj/5j1tnzxSVFFajbrWoPcH/jhPho6wqBducPDAoGBALOJ
        MEOavZXy7TaO0w3v7uvH0wzvxR/kfw1jMqc3l2j7ePOskmoOQAXaXO3bRjcdOlua
        Jyoq8islOZ4lRMlx7zWD0OKG035GNGzbmRtu2aA8R48RDSVr3jyu2gqznZULbXPv
        M/hmQxSmbhVUoW0PmJubnaqfk0zmXeBaNRXsIS3VAoGBALdsAtqR23PVeL6sYj2l
        dRNTDXpfvjFqJ5NThRO/4mT0CrPHQVj+Mz2bTc/Dxiwi8s8m3L+g23i3hodh/QMb
        Iz+UbcJZBGAKsFbPKGOtj6Bi07y/L11mcuNJzOWe61/JbVmJss0s+N/v3XucK/Ge
        CUaGOccsMO221v6JoBh9J3Hz
        -----END PRIVATE KEY-----

LDAP Schema (schema.ldif)

# 1) Root DN
 dn: dc=suaybsimsek,dc=com
 objectClass: top
 objectClass: domain
 objectClass: extensibleObject
 dc: suaybsimsek

# 2) People OU
 dn: ou=people,dc=suaybsimsek,dc=com
 objectClass: top
 objectClass: organizationalUnit
 ou: people

# 3) Admin user
 dn: uid=admin,ou=people,dc=suaybsimsek,dc=com
 objectClass: top
 objectClass: person
 objectClass: inetOrgPerson
 cn: Admin User
 sn: User
 uid: admin
 userPassword: $2a$10$sva6wl8pmGKJE6NIWrxwcuJK1Jaa2I/LOI43iHVpbR4YB8KjGViiK

# 4) Normal user
 dn: uid=user,ou=people,dc=suaybsimsek,dc=com
 objectClass: top
 objectClass: person
 objectClass: inetOrgPerson
 cn: Normal User
 sn: User
 uid: user
 userPassword: $2a$10$5Py4PyteLuXEqnGpSigzfu0V55C7Hi7zX18lmh.J8Bpmft.h23voG

# 5) Groups OU
 dn: ou=groups,dc=suaybsimsek,dc=com
 objectClass: top
 objectClass: organizationalUnit
 ou: groups

# 6) USER group → maps to ROLE_USER
 dn: cn=USER,ou=groups,dc=suaybsimsek,dc=com
 objectClass: top
 objectClass: groupOfUniqueNames
 cn: USER
 uniqueMember: uid=user,ou=people,dc=suaybsimsek,dc=com
 uniqueMember: uid=admin,ou=people,dc=suaybsimsek,dc=com

# 7) ADMIN group → maps to ROLE_ADMIN
 dn: cn=ADMIN,ou=groups,dc=suaybsimsek,dc=com
 objectClass: top
 objectClass: groupOfUniqueNames
 cn: ADMIN
 uniqueMember: uid=admin,ou=people,dc=suaybsimsek,dc=com

This combined configuration ensures your application boots an embedded LDAP server with the defined schema, and loads RSA keys for JWE signing and encryption. You can now proceed to configure Spring Security to use LDAP for authentication and JWE for token issuance.

🛠️ Step 3: Security Configuration

In this section, we define the beans and properties configure LDAP authentication, set up RSA keys, and enforce HTTP security filters for a JWE-based authentication:

• JwtProperties: Configures JWT issuer, expiration, and signing/encryption key pairs.
• SecurityJwtConfig: Builds RSA JWKs, JWT encoder/decoder, authentication converter, and token resolver.
• SecurityConfig: Defines embedded LDAP authentication, JWE resource server, and stateless security filter chain with route authorization.

SecurityJwtConfig

Java

package io.github.susimsek.springbootldapjwedemo.config;

import com.nimbusds.jose.EncryptionMethod;
import com.nimbusds.jose.JWEAlgorithm;
import com.nimbusds.jose.JWSAlgorithm;
import com.nimbusds.jose.jwk.JWKSet;
import com.nimbusds.jose.jwk.RSAKey;
import com.nimbusds.jose.jwk.source.JWKSource;
import com.nimbusds.jose.proc.JWEDecryptionKeySelector;
import com.nimbusds.jose.proc.JWSVerificationKeySelector;
import com.nimbusds.jose.proc.SecurityContext;
import com.nimbusds.jwt.proc.DefaultJWTProcessor;
import io.github.susimsek.springbootldapjwedemo.security.CookieBearerTokenResolver;
import io.github.susimsek.springbootldapjwedemo.security.KeyUtils;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.oauth2.jwt.JwtDecoder;
import org.springframework.security.oauth2.jwt.JwtEncoder;
import org.springframework.security.oauth2.jwt.NimbusJwtDecoder;
import org.springframework.security.oauth2.jwt.NimbusJwtEncoder;
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter;
import org.springframework.security.oauth2.server.resource.authentication.JwtGrantedAuthoritiesConverter;
import org.springframework.security.oauth2.server.resource.web.BearerTokenResolver;

import java.util.List;

import static io.github.susimsek.springbootldapjwedemo.security.SecurityUtils.AUTHORITIES_KEY;

@Configuration
public class SecurityJwtConfig {

    private final JwtProperties props;
    public SecurityJwtConfig(JwtProperties props) { this.props = props; }

    @Bean
    public RSAKey signingKey() throws Exception {
        return KeyUtils.buildRsaKey(
            props.getSigning().getPublicKey(),
            props.getSigning().getPrivateKey(),
            props.getSigning().getKeyId(),
            true
        );
    }

    @Bean
    public RSAKey encryptionKey() throws Exception {
        return KeyUtils.buildRsaKey(
            props.getEncryption().getPublicKey(),
            props.getEncryption().getPrivateKey(),
            props.getEncryption().getKeyId(),
            false
        );
    }

    @Bean
    public JWKSource<SecurityContext> jwkSource(RSAKey signingKey, RSAKey encryptionKey) {
        JWKSet jwkSet = new JWKSet(List.of(
            signingKey,
            encryptionKey
        ));
        return (jwkSelector, context) -> jwkSelector.select(jwkSet);
    }

    @Bean
    public JwtDecoder jwtDecoder(JWKSource<SecurityContext> jwkSource) {
        DefaultJWTProcessor<SecurityContext> jwtProcessor = new DefaultJWTProcessor<>();
        JWEDecryptionKeySelector<SecurityContext> jweKeySelector =
            new JWEDecryptionKeySelector<>(
                JWEAlgorithm.RSA_OAEP_256,
                EncryptionMethod.A128GCM,
                jwkSource
            );
        jwtProcessor.setJWEKeySelector(jweKeySelector);

        JWSVerificationKeySelector<SecurityContext> jwsKeySelector =
            new JWSVerificationKeySelector<>(
                JWSAlgorithm.RS256,
                jwkSource
            );
        jwtProcessor.setJWSKeySelector(jwsKeySelector);
        jwtProcessor.setJWTClaimsSetVerifier((claims, context) -> {});

        return new NimbusJwtDecoder(jwtProcessor);
    }

    @Bean
    public JwtEncoder jwtEncoder(JWKSource<SecurityContext> jwkSource) {
        return new NimbusJwtEncoder(jwkSource);
    }

    @Bean
    public JwtAuthenticationConverter jwtAuthenticationConverter() {
        JwtGrantedAuthoritiesConverter converter = new JwtGrantedAuthoritiesConverter();
        converter.setAuthorityPrefix("");
        converter.setAuthoritiesClaimName(AUTHORITIES_KEY);

        JwtAuthenticationConverter authConverter = new JwtAuthenticationConverter();
        authConverter.setJwtGrantedAuthoritiesConverter(converter);
        return authConverter;
    }

    @Bean
    public BearerTokenResolver bearerTokenResolver() {
        CookieBearerTokenResolver resolver = new CookieBearerTokenResolver();
        resolver.setAllowUriQueryParameter(false);
        resolver.setAllowFormEncodedBodyParameter(false);
        resolver.setAllowCookie(true);
        return resolver;
    }
}

Kotlin

package io.github.susimsek.springbootldapjwedemo.config

import com.nimbusds.jose.EncryptionMethod
import com.nimbusds.jose.JWEAlgorithm
import com.nimbusds.jose.JWSAlgorithm
import com.nimbusds.jose.jwk.JWKSet
import com.nimbusds.jose.jwk.RSAKey
import com.nimbusds.jose.jwk.source.JWKSource
import com.nimbusds.jose.proc.JWEDecryptionKeySelector
import com.nimbusds.jose.proc.JWSVerificationKeySelector
import com.nimbusds.jose.proc.SecurityContext
import com.nimbusds.jwt.proc.DefaultJWTProcessor
import io.github.susimsek.springbootldapjwedemo.security.CookieBearerTokenResolver
import io.github.susimsek.springbootldapjwedemo.security.KeyUtils
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.security.oauth2.jwt.JwtDecoder
import org.springframework.security.oauth2.jwt.JwtEncoder
import org.springframework.security.oauth2.jwt.NimbusJwtDecoder
import org.springframework.security.oauth2.jwt.NimbusJwtEncoder
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter
import org.springframework.security.oauth2.server.resource.authentication.JwtGrantedAuthoritiesConverter
import org.springframework.security.oauth2.server.resource.web.BearerTokenResolver

@Configuration
class SecurityJwtConfig(private val props: JwtProperties) {

    @Bean
    @Throws(Exception::class)
    fun signingKey(): RSAKey =
        KeyUtils.buildRsaKey(
            props.signing.publicKey,
            props.signing.privateKey,
            props.signing.keyId,
            true
        )

    @Bean
    @Throws(Exception::class)
    fun encryptionKey(): RSAKey =
        KeyUtils.buildRsaKey(
            props.encryption.publicKey,
            props.encryption.privateKey,
            props.encryption.keyId,
            false
        )

    @Bean
    fun jwkSource(signingKey: RSAKey, encryptionKey: RSAKey): JWKSource<SecurityContext> {
        val jwkSet = JWKSet(listOf(signingKey, encryptionKey))
        return JWKSource { jwkSelector, context -> jwkSelector.select(jwkSet) }
    }

    @Bean
    fun jwtDecoder(jwkSource: JWKSource<SecurityContext>): JwtDecoder {
        val jwtProcessor = DefaultJWTProcessor<SecurityContext>()
        val jweKeySelector = JWEDecryptionKeySelector(
            JWEAlgorithm.RSA_OAEP_256,
            EncryptionMethod.A128GCM,
            jwkSource
        )
        jwtProcessor.jweKeySelector = jweKeySelector
        val jwsKeySelector = JWSVerificationKeySelector(
            JWSAlgorithm.RS256,
            jwkSource
        )
        jwtProcessor.jwsKeySelector = jwsKeySelector
        jwtProcessor.jwtClaimsSetVerifier = { _, _ -> }
        return NimbusJwtDecoder(jwtProcessor)
    }

    @Bean
    fun jwtEncoder(jwkSource: JWKSource<SecurityContext>): JwtEncoder =
        NimbusJwtEncoder(jwkSource)

    @Bean
    fun jwtAuthenticationConverter(): JwtAuthenticationConverter {
        val converter = JwtGrantedAuthoritiesConverter().apply {
            setAuthorityPrefix("")
            setAuthoritiesClaimName(AUTHORITIES_KEY)
        }
        return JwtAuthenticationConverter().apply {
            setJwtGrantedAuthoritiesConverter(converter)
        }
    }

    @Bean
    fun bearerTokenResolver(): BearerTokenResolver =
        CookieBearerTokenResolver().apply {
            setAllowUriQueryParameter(false)
            setAllowFormEncodedBodyParameter(false)
            setAllowCookie(true)
        }
}

SecurityConfig

Java

package io.github.susimsek.springbootldapjwedemo.config;

import io.github.susimsek.springbootldapjwedemo.security.AuthoritiesConstants;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.ldap.core.support.BaseLdapPathContextSource;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.config.ldap.LdapPasswordComparisonAuthenticationManagerFactory;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.ldap.userdetails.DefaultLdapAuthoritiesPopulator;
import org.springframework.security.ldap.userdetails.LdapAuthoritiesPopulator;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.servlet.util.matcher.MvcRequestMatcher;
import org.springframework.web.servlet.handler.HandlerMappingIntrospector;

import static org.springframework.security.config.Customizer.withDefaults;

@Configuration
@EnableMethodSecurity(securedEnabled = true)
public class SecurityConfig {

  @Bean
  public SecurityFilterChain securityFilterChain(HttpSecurity http,
                                                 MvcRequestMatcher.Builder mvc) throws Exception {
    http
      .cors(withDefaults())
      .csrf(AbstractHttpConfigurer::disable)
      .authorizeHttpRequests(authz ->
        authz
          .requestMatchers(
            mvc.pattern("/webjars/**"),
            mvc.pattern("/css/**"),
            mvc.pattern("/js/**")
          ).permitAll()
          .requestMatchers(
            mvc.pattern("/*.ico"),
            mvc.pattern("/*.png"),
            mvc.pattern("/*.svg"),
            mvc.pattern("/*.webapp")
          ).permitAll()
          .requestMatchers("/actuator/**").permitAll()
          .requestMatchers(
            "/v3/api-docs/**",
            "/swagger-ui.html",
            "/swagger-ui/**"
          ).permitAll()
          .requestMatchers(mvc.pattern("/api/auth/login")).permitAll()
          .requestMatchers(mvc.pattern("/api/hello/admin"))
          .hasAuthority(AuthoritiesConstants.ADMIN)
          .anyRequest().authenticated()
      )
      .sessionManagement(session ->
        session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
      .oauth2ResourceServer(oauth2 -> oauth2
        .jwt(withDefaults())
      );
    return http.build();
  }

  @Bean
  public PasswordEncoder passwordEncoder() {
    return new BCryptPasswordEncoder();
  }

  @Bean
  public LdapAuthoritiesPopulator authorities(BaseLdapPathContextSource contextSource) {
    DefaultLdapAuthoritiesPopulator populator =
      new DefaultLdapAuthoritiesPopulator(contextSource, "ou=groups");
    populator.setGroupSearchFilter("uniqueMember={0}");
    populator.setGroupRoleAttribute("cn");
    populator.setRolePrefix("ROLE_");
    return populator;
  }

  @Bean
  public AuthenticationManager authenticationManager(
    BaseLdapPathContextSource contextSource,
    PasswordEncoder passwordEncoder,
    LdapAuthoritiesPopulator authorities
  ) {
    LdapPasswordComparisonAuthenticationManagerFactory factory =
      new LdapPasswordComparisonAuthenticationManagerFactory(contextSource, passwordEncoder);
    factory.setUserDnPatterns("uid={0},ou=people");
    factory.setPasswordAttribute("userPassword");
    factory.setLdapAuthoritiesPopulator(authorities);
    return factory.createAuthenticationManager();
  }

  @Bean
  public MvcRequestMatcher.Builder mvc(HandlerMappingIntrospector introspector) {
    return new MvcRequestMatcher.Builder(introspector);
  }
}

Kotlin

package io.github.susimsek.springbootldapjwedemo.config

import io.github.susimsek.springbootldapjwedemo.security.AuthoritiesConstants
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.ldap.core.support.BaseLdapPathContextSource
import org.springframework.security.authentication.AuthenticationManager
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity
import org.springframework.security.config.annotation.web.builders.HttpSecurity
import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer
import org.springframework.security.config.http.SessionCreationPolicy
import org.springframework.security.config.ldap.LdapPasswordComparisonAuthenticationManagerFactory
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder
import org.springframework.security.crypto.password.PasswordEncoder
import org.springframework.security.ldap.userdetails.DefaultLdapAuthoritiesPopulator
import org.springframework.security.ldap.userdetails.LdapAuthoritiesPopulator
import org.springframework.security.web.SecurityFilterChain
import org.springframework.security.web.servlet.util.matcher.MvcRequestMatcher
import org.springframework.web.servlet.handler.HandlerMappingIntrospector
import org.springframework.security.config.Customizer.withDefaults

@Configuration
@EnableMethodSecurity(securedEnabled = true)
class SecurityConfig {

  @Bean
  fun securityFilterChain(
    http: HttpSecurity,
    mvc: MvcRequestMatcher.Builder
  ): SecurityFilterChain = http
    .cors(withDefaults())
    .csrf { it.disable() }
    .authorizeHttpRequests { authz ->
      authz
        .requestMatchers(
          mvc.pattern("/webjars/**"),
          mvc.pattern("/css/**"),
          mvc.pattern("/js/**")
        ).permitAll()
        .requestMatchers(
          mvc.pattern("/*.ico"),
          mvc.pattern("/*.png"),
          mvc.pattern("/*.svg"),
          mvc.pattern("/*.webapp")
        ).permitAll()
        .requestMatchers("/actuator/**").permitAll()
        .requestMatchers("/v3/api-docs/**", "/swagger-ui.html", "/swagger-ui/**")
        .permitAll()
        .requestMatchers(mvc.pattern("/api/auth/login")).permitAll()
        .requestMatchers(mvc.pattern("/api/hello/admin"))
        .hasAuthority(AuthoritiesConstants.ADMIN)
        .anyRequest().authenticated()
    }
    .sessionManagement { it.sessionCreationPolicy(SessionCreationPolicy.STATELESS) }
    .oauth2ResourceServer { it.jwt(withDefaults()) }
    .build()

  @Bean
  fun passwordEncoder(): PasswordEncoder = BCryptPasswordEncoder()

  @Bean
  fun authorities(contextSource: BaseLdapPathContextSource): LdapAuthoritiesPopulator {
    return DefaultLdapAuthoritiesPopulator(contextSource, "ou=groups").apply {
      setGroupSearchFilter("uniqueMember={0}")
      setGroupRoleAttribute("cn")
      setRolePrefix("ROLE_")
    }
  }

  @Bean
  fun authenticationManager(
    contextSource: BaseLdapPathContextSource,
    passwordEncoder: PasswordEncoder,
    authorities: LdapAuthoritiesPopulator
  ): AuthenticationManager {
    return LdapPasswordComparisonAuthenticationManagerFactory(contextSource, passwordEncoder).apply {
      setUserDnPatterns("uid={0},ou=people")
      setPasswordAttribute("userPassword")
      setLdapAuthoritiesPopulator(authorities)
    }.createAuthenticationManager()
  }

  @Bean
  fun mvc(introspector: HandlerMappingIntrospector): MvcRequestMatcher.Builder =
    MvcRequestMatcher.Builder(introspector)
}

JwtProperties

Java

package io.github.susimsek.springbootldapjwedemo.config;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;

import java.time.Duration;

@Configuration
@ConfigurationProperties(prefix = "security.jwt")
@Data
public class JwtProperties {

    @Data
    public static class Pair {
        private String publicKey;
        private String privateKey;
        private String keyId;
    }

    private Pair signing;
    private Pair encryption;
    private String issuer;
    private Duration expirationDuration;
}

Kotlin

package io.github.susimsek.springbootldapjwedemo.config

import org.springframework.boot.context.properties.ConfigurationProperties
import org.springframework.context.annotation.Configuration
import java.time.Duration

@Configuration
@ConfigurationProperties(prefix = "security.jwt")
class JwtProperties {

  class Pair {
    lateinit var publicKey: String
    lateinit var privateKey: String
    lateinit var keyId: String
  }

  lateinit var signing: Pair
  lateinit var encryption: Pair
  lateinit var issuer: String
  lateinit var expirationDuration: Duration
}

🛠️ Step 4: Secure JWE Token Utilities

In this section, we define the core utility classes and constants needed to generate, encrypt, and resolve JSON Web Encryption (JWE) tokens in your Spring Boot application. These components work together to:

• AuthoritiesConstants: Centralize role names with the ROLE_ prefix.
• CookieBearerTokenResolver: Resolve bearer tokens from Authorization headers or HTTP cookies.
• CookieUtils: Create HTTP-only, secure cookies for access tokens.
• JweUtil: Sign (JWS) and encrypt (JWE) JWTs using RSA keys and Nimbus.
• KeyUtils: Build RSA JWKs from PEM‐encoded key material.
• SecurityUtils: Extract the current user’s login from the security context.

These utilities form the foundation for a stateless, JWE‐based authentication flow in Spring Security.

AuthoritiesConstants

Java

package io.github.susimsek.springbootldapjwedemo.security;

import lombok.AccessLevel;
import lombok.NoArgsConstructor;

@NoArgsConstructor(access = AccessLevel.PRIVATE)
public final class AuthoritiesConstants {
    public static final String ADMIN = "ROLE_ADMIN";
    public static final String USER = "ROLE_USER";
    public static final String ANONYMOUS = "ROLE_ANONYMOUS";
}

Kotlin

package io.github.susimsek.springbootldapjwedemo.security

object AuthoritiesConstants {
  const val ADMIN = "ROLE_ADMIN"
  const val USER = "ROLE_USER"
  const val ANONYMOUS = "ROLE_ANONYMOUS"
}

CookieBearerTokenResolver

Java

package io.github.susimsek.springbootldapjwedemo.security;

import jakarta.servlet.http.Cookie;
import jakarta.servlet.http.HttpServletRequest;
import lombok.Setter;
import org.springframework.http.HttpMethod;
import org.springframework.security.oauth2.core.OAuth2AuthenticationException;
import org.springframework.security.oauth2.server.resource.BearerTokenError;
import org.springframework.security.oauth2.server.resource.BearerTokenErrors;
import org.springframework.security.oauth2.server.resource.web.BearerTokenResolver;
import org.springframework.util.StringUtils;

import java.util.regex.Matcher;
import java.util.regex.Pattern;

@Setter
public class CookieBearerTokenResolver implements BearerTokenResolver {
    private static final String ACCESS_TOKEN_PARAMETER_NAME = "access_token";
    private static final Pattern AUTHORIZATION_PATTERN =
        Pattern.compile("^Bearer (?<token>[A-Za-z0-9-._~+/]+=*)$", Pattern.CASE_INSENSITIVE);

    private boolean allowFormEncodedBodyParameter = false;
    private boolean allowUriQueryParameter       = false;
    private boolean allowCookie                  = true;
    private String  bearerTokenHeaderName       = "Authorization";
    private String  cookieName                  = "accessToken";

    @Override
    public String resolve(HttpServletRequest request) {
        String headerToken = resolveFromAuthorizationHeader(request);
        String queryToken  = resolveAccessTokenFromQueryString(request);
        String bodyToken   = resolveAccessTokenFromBody(request);
        String cookieToken = (headerToken == null && queryToken == null && bodyToken == null)
            ? resolveFromCookie(request)
            : null;

        return resolveToken(headerToken, queryToken, bodyToken, cookieToken);
    }

    private String resolveFromAuthorizationHeader(HttpServletRequest request) {
        String authorization = request.getHeader(this.bearerTokenHeaderName);
        if (!StringUtils.hasText(authorization) || !authorization.toLowerCase().startsWith("bearer")) {
            return null;
        }
        Matcher matcher = AUTHORIZATION_PATTERN.matcher(authorization.trim());
        if (!matcher.matches()) {
            BearerTokenError error = BearerTokenErrors.invalidToken("Bearer token is malformed");
            throw new OAuth2AuthenticationException(error);
        }
        return matcher.group("token");
    }

    private String resolveAccessTokenFromQueryString(HttpServletRequest request) {
        if (allowUriQueryParameter && HttpMethod.GET.matches(request.getMethod())) {
            return resolveToken(request.getParameterValues(ACCESS_TOKEN_PARAMETER_NAME));
        }
        return null;
    }

    private String resolveAccessTokenFromBody(HttpServletRequest request) {
        if (allowFormEncodedBodyParameter
            && HttpMethod.POST.matches(request.getMethod())
            && "application/x-www-form-urlencoded".equals(request.getContentType())) {
            return resolveToken(request.getParameterValues(ACCESS_TOKEN_PARAMETER_NAME));
        }
        return null;
    }

    private String resolveFromCookie(HttpServletRequest request) {
        if (!allowCookie || request.getCookies() == null) {
            return null;
        }
        for (Cookie cookie : request.getCookies()) {
            if (cookieName.equals(cookie.getName())) {
                String val = cookie.getValue();
                return StringUtils.hasText(val) ? val : null;
            }
        }
        return null;
    }

    private String resolveToken(String... tokens) {
        String found = null;
        for (String token : tokens) {
            if (token == null) continue;
            if (found != null) {
                BearerTokenError error = BearerTokenErrors.invalidRequest("Found multiple bearer tokens in the request");
                throw new OAuth2AuthenticationException(error);
            }
            found = token;
        }
        if (found != null && found.isBlank()) {
            BearerTokenError error = BearerTokenErrors.invalidRequest("The requested token parameter is an empty string");
            throw new OAuth2AuthenticationException(error);
        }
        return found;
    }

Kotlin

package io.github.susimsek.springbootldapjwedemo.security

import jakarta.servlet.http.Cookie
import jakarta.servlet.http.HttpServletRequest
import org.springframework.http.HttpMethod
import org.springframework.security.oauth2.core.OAuth2AuthenticationException
import org.springframework.security.oauth2.server.resource.BearerTokenError
import org.springframework.security.oauth2.server.resource.BearerTokenErrors
import org.springframework.security.oauth2.server.resource.web.BearerTokenResolver
import org.springframework.util.StringUtils
import java.util.regex.Pattern

class CookieBearerTokenResolver {
    var allowFormEncodedBodyParameter: Boolean = false
    var allowUriQueryParameter: Boolean = false
    var allowCookie: Boolean = true
    var bearerTokenHeaderName: String = "Authorization"
    var cookieName: String = "accessToken"

    companion object {
        private const val ACCESS_TOKEN_PARAMETER_NAME = "access_token"
        private val AUTHORIZATION_PATTERN =
            Pattern.compile("^Bearer (?<token>[A-Za-z0-9-._~+/]+=*)$", Pattern.CASE_INSENSITIVE)
    }

    fun resolve(request: HttpServletRequest): String? {
        val header = resolveFromAuthorizationHeader(request)
        val query  = if (allowUriQueryParameter && HttpMethod.GET.matches(request.method))
            request.getParameterValues(ACCESS_TOKEN_PARAMETER_NAME)?.let(::resolveToken)
        else null
        val body   = if (allowFormEncodedBodyParameter && HttpMethod.POST.matches(request.method)
            && request.contentType == "application/x-www-form-urlencoded")
            request.getParameterValues(ACCESS_TOKEN_PARAMETER_NAME)?.let(::resolveToken)
        else null
        val cookie = if (header == null && query == null && body == null)
            resolveFromCookie(request)
        else null
      return listOf(header, query, body, cookie).filterNotNull().let {
            if (it.size > 1) throw OAuth2AuthenticationException(BearerTokenErrors.invalidRequest("Found multiple bearer tokens"))
            it.firstOrNull()?: null
        }
    }

    private fun resolveFromAuthorizationHeader(request: HttpServletRequest): String? {
        val auth = request.getHeader(bearerTokenHeaderName) ?: return null
        if (!auth.startsWith("Bearer ", true)) return null
        val matcher = AUTHORIZATION_PATTERN.matcher(auth.trim())
        return if (matcher.matches()) matcher.group("token")
        else throw OAuth2AuthenticationException(BearerTokenErrors.invalidToken("Malformed token"))
    }

    private fun resolveFromCookie(request: HttpServletRequest): String? {
        if (!allowCookie) return null
        return request.cookies?.firstOrNull { it.name == cookieName }?.value?.takeIf { it.isNotBlank() }
    }

    private fun resolveToken(tokens: Array<String>): String? {
        return tokens.filter { it.isNotBlank() }.let {
            when {
                it.isEmpty() -> null
                it.size > 1   -> throw OAuth2AuthenticationException(BearerTokenErrors.invalidRequest("Multiple tokens"))
                else          -> it[0]
            }
        }
    }

CookieUtils

Java

package io.github.susimsek.springbootldapjwedemo.security;

import io.github.susimsek.springbootldapjwedemo.dto.TokenDTO;
import lombok.experimental.UtilityClass;
import org.springframework.http.ResponseCookie;

@UtilityClass
public class CookieUtils {

    private static final String COOKIE_NAME = "accessToken";

    public ResponseCookie createAccessTokenCookie(TokenDTO tokenDto) {
        return ResponseCookie.from(COOKIE_NAME, tokenDto.accessToken())
            .httpOnly(true)
            .secure(true)
            .path("/")
            .maxAge(tokenDto.accessTokenExpiresIn())
            .sameSite("Strict")
            .build();
    }
}

Kotlin

package io.github.susimsek.springbootldapjwedemo.security

import io.github.susimsek.springbootldapjwedemo.dto.TokenDTO
import org.springframework.http.ResponseCookie

object CookieUtils {

  private const val COOKIE_NAME = "accessToken"

  fun createAccessTokenCookie(tokenDto: TokenDTO): ResponseCookie {
    return ResponseCookie.from(COOKIE_NAME, tokenDto.accessToken())
      .httpOnly(true)
      .secure(true)
      .path("/")
      .maxAge(tokenDto.accessTokenExpiresIn())
      .sameSite("Strict")
      .build()
  }
}

JweUtil

Java

package io.github.susimsek.springbootldapjwedemo.security;

import com.nimbusds.jose.EncryptionMethod;
import com.nimbusds.jose.JOSEException;
import com.nimbusds.jose.JWEAlgorithm;
import com.nimbusds.jose.JWEHeader;
import com.nimbusds.jose.JWEObject;
import com.nimbusds.jose.Payload;
import com.nimbusds.jose.crypto.RSAEncrypter;
import com.nimbusds.jose.jwk.RSAKey;
import io.github.susimsek.springbootldapjwedemo.config.JwtProperties;
import io.github.susimsek.springbootldapjwedemo.dto.TokenDTO;
import lombok.RequiredArgsConstructor;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.oauth2.jose.jws.SignatureAlgorithm;
import org.springframework.security.oauth2.jwt.*;
import org.springframework.stereotype.Component;

import java.time.Instant;
import java.util.List;

import static io.github.susimsek.springbootldapjwedemo.security.SecurityUtils.AUTHORITIES_KEY;

@Component
@RequiredArgsConstructor
public class JweUtil {

    private final JwtEncoder jwtEncoder;
    private final RSAKey signingKey;
    private final RSAKey encryptionKey;
    private final JwtProperties props;

    public TokenDTO generateToken(Authentication authentication) throws JOSEException {
        String subject = authentication.getName();
        List<String> roles = authentication.getAuthorities()
            .stream()
            .map(GrantedAuthority::getAuthority)
            .toList();

        Instant now = Instant.now();
        long expiresIn = props.getExpirationDuration().getSeconds();
        Instant exp = now.plusSeconds(expiresIn);

        JwtClaimsSet claims = JwtClaimsSet.builder()
            .issuer(props.getIssuer())
            .issuedAt(now)
            .expiresAt(exp)
            .subject(subject)
            .claim(AUTHORITIES_KEY, roles)
            .build();

        JwsHeader jwsHeader = JwsHeader.with(SignatureAlgorithm.RS256)
            .keyId(signingKey.getKeyID())
            .build();

        String jws = jwtEncoder
            .encode(JwtEncoderParameters.from(jwsHeader, claims))
            .getTokenValue();

        JWEHeader jweHeader = new JWEHeader.Builder(JWEAlgorithm.RSA_OAEP_256, EncryptionMethod.A128GCM)
            .contentType("JWT")
            .keyID(encryptionKey.getKeyID())
            .build();

        JWEObject jweObject = new JWEObject(jweHeader, new Payload(jws));
        jweObject.encrypt(new RSAEncrypter(encryptionKey.toRSAPublicKey()));
        String token = jweObject.serialize();

        return new TokenDTO(token, "Bearer", expiresIn);
    }
}

Kotlin

package io.github.susimsek.springbootldapjwedemo.security

import com.nimbusds.jose.EncryptionMethod
import com.nimbusds.jose.JOSEException
import com.nimbusds.jose.JWEAlgorithm
import com.nimbusds.jose.JWEHeader
import com.nimbusds.jose.JWEObject
import com.nimbusds.jose.Payload
import com.nimbusds.jose.crypto.RSAEncrypter
import com.nimbusds.jose.jwk.RSAKey
import io.github.susimsek.springbootldapjwedemo.config.JwtProperties
import io.github.susimsek.springbootldapjwedemo.dto.TokenDTO
import lombok.RequiredArgsConstructor
import org.springframework.security.core.Authentication
import org.springframework.security.oauth2.jose.jws.SignatureAlgorithm
import org.springframework.security.oauth2.jwt.JwtClaimsSet
import org.springframework.security.oauth2.jwt.JwtEncoder
import org.springframework.security.oauth2.jwt.JwtEncoderParameters
import org.springframework.stereotype.Component

import java.time.Instant

@Component
@RequiredArgsConstructor
class JweUtil(
    private val jwtEncoder: JwtEncoder,
    private val signingKey: RSAKey,
    private val encryptionKey: RSAKey,
    private val props: JwtProperties
) {
    fun generateToken(authentication: Authentication): TokenDTO {
        val subject = authentication.name
        val roles = authentication.authorities.map { it.authority }

        val now = Instant.now()
        val expiresIn = props.expirationDuration.seconds
        val exp = now.plusSeconds(expiresIn)

        val claims = JwtClaimsSet.builder()
            .issuer(props.issuer)
            .issuedAt(now)
            .expiresAt(exp)
            .subject(subject)
            .claim(AUTHORITIES_KEY, roles)
            .build()

        val jwsHeader = org.springframework.security.oauth2.jwt.JwsHeader.with(SignatureAlgorithm.RS256)
            .keyId(signingKey.keyID)
            .build()

        val jws = jwtEncoder
            .encode(JwtEncoderParameters.from(jwsHeader, claims))
            .tokenValue

        val jweHeader = JWEHeader.Builder(JWEAlgorithm.RSA_OAEP_256, EncryptionMethod.A128GCM)
            .contentType("JWT")
            .keyID(encryptionKey.keyID)
            .build()

        val jweObject = JWEObject(jweHeader, Payload(jws))
        jweObject.encrypt(RSAEncrypter(encryptionKey.toRSAPublicKey()))
        val token = jweObject.serialize()

        return TokenDTO(token, "Bearer", expiresIn)
    }
}

KeyUtils

Java

package io.github.susimsek.springbootldapjwedemo.security;

import com.nimbusds.jose.JWEAlgorithm;
import com.nimbusds.jose.JWSAlgorithm;
import com.nimbusds.jose.jwk.KeyUse;
import com.nimbusds.jose.jwk.RSAKey;
import lombok.experimental.UtilityClass;

import java.security.KeyFactory;
import java.security.interfaces.RSAPrivateKey;
import java.security.interfaces.RSAPublicKey;
import java.security.spec.PKCS8EncodedKeySpec;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;

@UtilityClass
public class KeyUtils {
    public RSAKey buildRsaKey(
            String pubPem,
            String privPem,
            String kid,
            boolean forSign
    ) throws Exception {
        String pubContent = pubPem
            .replace("-----BEGIN PUBLIC KEY-----", "")
            .replace("-----END PUBLIC KEY-----", "")
            .replaceAll("\\s", "");
        String privContent = privPem
            .replace("-----BEGIN PRIVATE KEY-----", "")
            .replace("-----END PRIVATE KEY-----", "")
            .replaceAll("\\s", "");

        byte[] decodedPub = Base64.getDecoder().decode(pubContent);
        byte[] decodedPriv = Base64.getDecoder().decode(privContent);

        KeyFactory kf = KeyFactory.getInstance("RSA");
        RSAPublicKey publicKey = (RSAPublicKey) kf.generatePublic(new X509EncodedKeySpec(decodedPub));
        RSAPrivateKey privateKey = (RSAPrivateKey) kf.generatePrivate(new PKCS8EncodedKeySpec(decodedPriv));

        RSAKey.Builder builder = new RSAKey.Builder(publicKey)
            .privateKey(privateKey)
            .keyID(kid);

        if (forSign) {
            builder
                .algorithm(JWSAlgorithm.RS256)
                .keyUse(KeyUse.SIGNATURE);
        } else {
            builder
                .algorithm(JWEAlgorithm.RSA_OAEP_256)
                .keyUse(KeyUse.ENCRYPTION);
        }

        return builder.build();
    }
}

Kotlin

package io.github.susimsek.springbootldapjwedemo.security

import com.nimbusds.jose.JWEAlgorithm
import com.nimbusds.jose.JWSAlgorithm
import com.nimbusds.jose.jwk.KeyUse
import com.nimbusds.jose.jwk.RSAKey
import java.security.KeyFactory
import java.security.interfaces.RSAPrivateKey
import java.security.interfaces.RSAPublicKey
import java.security.spec.PKCS8EncodedKeySpec
import java.security.spec.X509EncodedKeySpec
import java.util.Base64

object KeyUtils {
    @JvmStatic
    @Throws(Exception::class)
    fun buildRsaKey(
        pubPem: String,
        privPem: String,
        kid: String,
        forSign: Boolean
    ): RSAKey {
        val pubContent = pubPem
            .replace("-----BEGIN PUBLIC KEY-----", "")
            .replace("-----END PUBLIC KEY-----", "")
            .replace(Regex("\\s"), "")
        val privContent = privPem
            .replace("-----BEGIN PRIVATE KEY-----", "")
            .replace("-----END PRIVATE KEY-----", "")
            .replace(Regex("\\s"), "")

        val decodedPub = Base64.getDecoder().decode(pubContent)
        val decodedPriv = Base64.getDecoder().decode(privContent)

        val kf = KeyFactory.getInstance("RSA")
        val publicKey = kf.generatePublic(X509EncodedKeySpec(decodedPub)) as RSAPublicKey
        val privateKey = kf.generatePrivate(PKCS8EncodedKeySpec(decodedPriv)) as RSAPrivateKey

        val builder = RSAKey.Builder(publicKey)
            .privateKey(privateKey)
            .keyID(kid)

        if (forSign) {
            builder
                .algorithm(JWSAlgorithm.RS256)
                .keyUse(KeyUse.SIGNATURE)
        } else {
            builder
                .algorithm(JWEAlgorithm.RSA_OAEP_256)
                .keyUse(KeyUse.ENCRYPTION)
        }

        return builder.build()
    }
}

SecurityUtils

Java

package io.github.susimsek.springbootldapjwedemo.security;

import lombok.experimental.UtilityClass;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.oauth2.jwt.Jwt;

import java.util.Optional;

@UtilityClass
public class SecurityUtils {

    public static final String AUTHORITIES_KEY = "auth";

    public Optional<String> getCurrentUserLogin() {
        var ctx = SecurityContextHolder.getContext();
        return Optional.ofNullable(extractPrincipal(ctx.getAuthentication()));
    }

    private String extractPrincipal(Authentication authentication) {
        if (authentication == null) {
            return null;
        }
        Object principal = authentication.getPrincipal();
        if (principal instanceof Jwt jwt) {
            return jwt.getSubject();
        }
        if (principal instanceof UserDetails ud) {
            return ud.getUsername();
        }
        if (principal instanceof String username) {
            return username;
        }
        return null;
    }
}

Kotlin

package io.github.susimsek.springbootldapjwedemo.security

import org.springframework.security.core.Authentication
import org.springframework.security.core.context.SecurityContextHolder
import org.springframework.security.core.userdetails.UserDetails
import org.springframework.security.oauth2.jwt.Jwt
import java.util.Optional

object SecurityUtils {
  const val AUTHORITIES_KEY = "auth"

  fun getCurrentUserLogin(): Optional<String> {
    val authentication: Authentication? = SecurityContextHolder.getContext().authentication
    return Optional.ofNullable(extractPrincipal(authentication))
  }

  private fun extractPrincipal(authentication: Authentication?): String? {
    return when (val principal = authentication?.principal) {
      is Jwt -> principal.subject
      is UserDetails -> principal.username
      is String -> principal
      else -> null
    }
  }
}

🛠️ Step 5: Authentication & Protected Endpoints

In this section, we define the REST controllers and DTOs necessary for:

• AuthController: Authenticate users, issue JWE tokens, and set secure cookies.
• HelloController: Expose protected resource endpoints for authenticated users and admin-specific paths.
• LoginRequestDTO: Model the login request payload (username/password).
• TokenDTO: Model the authentication response including token and expiration.

These components complete the stateless authentication flow by handling login, token issuance, cookie management, and resource protection.

In this section, we expose REST controllers and DTOs to handle user authentication, token issuance, and protected resource access.

AuthController

Java

package io.github.susimsek.springbootldapjwedemo.controller;

import io.github.susimsek.springbootldapjwedemo.dto.LoginRequestDTO;
import io.github.susimsek.springbootldapjwedemo.dto.TokenDTO;
import io.github.susimsek.springbootldapjwedemo.security.CookieUtils;
import io.github.susimsek.springbootldapjwedemo.security.JweUtil;
import lombok.RequiredArgsConstructor;
import org.springframework.http.HttpHeaders;
import org.springframework.http.ResponseCookie;
import org.springframework.http.ResponseEntity;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequiredArgsConstructor
@RequestMapping("/api/auth")
public class AuthController {

    private final AuthenticationManager authenticationManager;
    private final JweUtil jweUtil;

    @PostMapping("/login")
    public ResponseEntity<TokenDTO> login(@RequestBody LoginRequestDTO loginRequest) throws Exception {
        // Authenticate user
        var authToken = new UsernamePasswordAuthenticationToken(
            loginRequest.username(), loginRequest.password()
        );
        Authentication auth = authenticationManager.authenticate(authToken);
        SecurityContextHolder.getContext().setAuthentication(auth);

        // Generate JWE token and cookie
        TokenDTO tokenDto = jweUtil.generateToken(auth);
        ResponseCookie cookie = CookieUtils.createAccessTokenCookie(tokenDto);

        return ResponseEntity.ok()
            .header(HttpHeaders.SET_COOKIE, cookie.toString())
            .body(tokenDto);
    }
}

Kotlin

package io.github.susimsek.springbootldapjwedemo.controller

import io.github.susimsek.springbootldapjwedemo.dto.LoginRequestDTO
import io.github.susimsek.springbootldapjwedemo.dto.TokenDTO
import io.github.susimsek.springbootldapjwedemo.security.CookieUtils
import io.github.susimsek.springbootldapjwedemo.security.JweUtil
import lombok.RequiredArgsConstructor
import org.springframework.http.HttpHeaders
import org.springframework.http.ResponseCookie
import org.springframework.http.ResponseEntity
import org.springframework.security.authentication.AuthenticationManager
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken
import org.springframework.security.core.Authentication
import org.springframework.security.core.context.SecurityContextHolder
import org.springframework.web.bind.annotation.PostMapping
import org.springframework.web.bind.annotation.RequestBody
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController

@RestController
@RequiredArgsConstructor
@RequestMapping("/api/auth")
class AuthController(
    private val authenticationManager: AuthenticationManager,
    private val jweUtil: JweUtil
) {

    @PostMapping("/login")
    fun login(@RequestBody loginRequest: LoginRequestDTO): ResponseEntity<TokenDTO> {
        val authToken = UsernamePasswordAuthenticationToken(
            loginRequest.username, loginRequest.password
        )
        val auth: Authentication = authenticationManager.authenticate(authToken)
        SecurityContextHolder.getContext().authentication = auth

        val tokenDto: TokenDTO = jweUtil.generateToken(auth)
        val cookie: ResponseCookie = CookieUtils.createAccessTokenCookie(tokenDto)

        return ResponseEntity.ok()
            .header(HttpHeaders.SET_COOKIE, cookie.toString())
            .body(tokenDto)
    }
}

HelloController

Java

package io.github.susimsek.springbootldapjwedemo.controller;

import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.jwt.Jwt;
import org.springframework.web.bind.annotation.*;

import static io.github.susimsek.springbootldapjwedemo.security.SecurityUtils.AUTHORITIES_KEY;

@RestController
@RequestMapping("/api/hello")
public class HelloController {

    @GetMapping
    public String helloAll(@AuthenticationPrincipal Jwt jwt) {
        String user = jwt.getSubject();
        var roles = jwt.getClaimAsStringList(AUTHORITIES_KEY);
        return "Hello, " + user + "! Your roles: " + roles;
    }

    @GetMapping("/admin")
    public String helloAdmin(@AuthenticationPrincipal Jwt jwt) {
        return "Hello Admin, " + jwt.getSubject() + "!";
    }
}

Kotlin

package io.github.susimsek.springbootldapjwedemo.controller

import org.springframework.security.core.annotation.AuthenticationPrincipal
import org.springframework.security.oauth2.jwt.Jwt
import org.springframework.web.bind.annotation.*

import io.github.susimsek.springbootldapjwedemo.security.SecurityUtils.AUTHORITIES_KEY

@RestController
@RequestMapping("/api/hello")
class HelloController {

    @GetMapping
    fun helloAll(@AuthenticationPrincipal jwt: Jwt): String {
        val user = jwt.subject
        val roles = jwt.getClaimAsStringList(AUTHORITIES_KEY)
        return "Hello, \$user! Your roles: \$roles"
    }

    @GetMapping("/admin")
    fun helloAdmin(@AuthenticationPrincipal jwt: Jwt): String {
        return "Hello Admin, \${jwt.subject}!"
    }
}

LoginRequestDTO

Java

package io.github.susimsek.springbootldapjwedemo.dto;

public record LoginRequestDTO(
    String username,
    String password
) { }

Kotlin

package io.github.susimsek.springbootldapjwedemo.dto

data class LoginRequestDTO(
    val username: String,
    val password: String
)

TokenDTO

Java

package io.github.susimsek.springbootldapjwedemo.dto;

public record TokenDTO(
    String accessToken,
    String tokenType,
    long accessTokenExpiresIn
) {}

Kotlin

package io.github.susimsek.springbootldapjwedemo.dto

import kotlin.Long

data class TokenDTO(
    val accessToken: String,
    val tokenType: String,
    val accessTokenExpiresIn: Long
)

▶️ Run the App

./mvnw spring-boot:run
# or
gradle bootRun

🧪 Test Endpoints

In this section, we clarify Test Endpoints and summarize the key points you will apply in implementation.

Admin Flow

Login as admin and capture the JWE token from the Set-Cookie header:

curl -i -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"adminpass"}'

• Set-Cookie header contains accessToken=<jwe-token>
• Response body:

{
  "accessToken": "<jwe-token>",
  "tokenType": "Bearer",
  "accessTokenExpiresIn": 3600
}

Use cookie to access hello endpoint:

curl -b "accessToken=<jwe-token>" http://localhost:8080/api/hello

Use Authorization header instead:

curl -H "Authorization: Bearer <jwe-token>" http://localhost:8080/api/hello

Access admin-only endpoint:

curl -H "Authorization: Bearer <jwe-token>" http://localhost:8080/api/hello/admin

User Flow

Login as user and capture JWE token from cookie:

curl -i -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"user","password":"userpass"}'

• Set-Cookie header contains accessToken=<jwe-token>

Use cookie to access hello endpoint:

curl -b "accessToken=<jwe-token>" http://localhost:8080/api/hello

Use Authorization header:

curl -H "Authorization: Bearer <jwe-token>" http://localhost:8080/api/hello

Attempt admin endpoint (should be 403 Forbidden):

curl -H "Authorization: Bearer <jwe-token>" http://localhost:8080/api/hello/admin
# HTTP/1.1 403 Forbidden

🏁 Conclusion

You now have a practical Spring Boot LDAP and JWE Authentication implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why Use JWE Authentication?

In this section, we clarify Why Use JWE Authentication? and summarize the key points you will apply in implementation.

• Integrity: Ensure tokens are signed (JWS) and tamper-evident.
• Confidentiality: Encrypt sensitive claims so only holders of the private key can read them (JWE).
• Standards-based: Built on the JOSE (JWS, JWE) specifications.
• Spring Support: Spring Security’s OAuth2 Resource Server handles JWE+JWS seamlessly.

📋 Prerequisites

In this section, we clarify Prerequisites and summarize the key points you will apply in implementation.

• ☕ Java Development Kit (JDK) 17 or higher
• 📦 Spring Boot 3.2+
• 🔤 IDE (IntelliJ IDEA, Eclipse)

🛠️ Step 1: Add Dependencies

Include these in your pom.xml or build.gradle file.

Maven:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.security</groupId>
  <artifactId>spring-security-oauth2-resource-server</artifactId>
</dependency>
<dependency>
  <groupId>org.projectlombok</groupId>
  <artifactId>lombok</artifactId>
  <optional>true</optional>
</dependency>

Gradle:

implementation 'org.springframework.boot:spring-boot-starter-web'
implementation 'org.springframework.security:spring-security-oauth2-resource-server'
compileOnly 'org.projectlombok:lombok'

🛠️ Step 2: Keys Configuration

Define RSA keys and user credentials in application.yml:

security:
  admin:
    username: admin
    password: adminpass
  user:
    username: user
    password: userpass
  jwt:
    issuer: demo-issuer
    expiration-duration: 3600s
    signing:
      key-id: signing-key
      public-key: |-
        -----BEGIN PUBLIC KEY-----
        MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAjZEcz5itWkDGOSqZdB5P
        JE0ccOCckskp0hN3kQbT1qnv+9/k66jlWgVi4HSTppwdNF/Ylu5u541Qj+Okyg+u
        8o2PvKo5CfgvTDsFLTrZHUXU6hCSGatLAQoeN6lT8wzov2r4DFecXrIqcO6SvMB5
        ecPqsfiTi4trsNKgJ4cWS6gILH62ISd1ipUadfpnUzDMO1OulV0CJNV6bcBk7Es9
        RW6AHfg9j8osSanpwvRM4MJkB0SRxYUnrN9faGpkBZISZJ8TShhaTHEGfSNgKe5y
        8iu+AMGGZu8DYczVmqS3Ske1fq6y5HEGCma7Mo019GmwKeHBo1obuET6cZRygj4y
        twIDAQAB
        -----END PUBLIC KEY-----
      private-key: |-
        -----BEGIN PRIVATE KEY-----
        MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQCNkRzPmK1aQMY5
        Kpl0Hk8kTRxw4JySySnSE3eRBtPWqe/73+TrqOVaBWLgdJOmnB00X9iW7m7njVCP
        46TKD67yjY+8qjkJ+C9MOwUtOtkdRdTqEJIZq0sBCh43qVPzDOi/avgMV5xesipw
        7pK8wHl5w+qx+JOLi2uw0qAnhxZLqAgsfrYhJ3WKlRp1+mdTMMw7U66VXQIk1Xpt
        wGTsSz1FboAd+D2PyixJqenC9EzgwmQHRJHFhSes319oamQFkhJknxNKGFpMcQZ9
        I2Ap7nLyK74AwYZm7wNhzNWapLdKR7V+rrLkcQYKZrsyjTX0abAp4cGjWhu4RPpx
        lHKCPjK3AgMBAAECggEABMo/sNCIMREXA/EqjxDFecN4LmOTOK5A0YBiH9Cc01sd
        qSaavtSQqhqbjV+0bUNEA7UohXbc3s3bx3qa5VFhiIh8sBQMaQdyRkCK/MxMc16d
        BSx5XQ/8MjVO73A1zHgH2g47BWPjgRrDL94KrgNPOO0FoG76QxL9GlcOHzhFa1rf
        xbb2auLBtflKy+5TZNnB/sbFC9ISpWywzfblD2Fsvxupl0vNWtA0Y2rPbKMZRnY+
        V6NC38yxW3HHAdWQRYLGOitM59I0HBgnjQKzTBNIsjPnJA2BSZvMBtQ1e3RQV0qE
        8VVoktZ8A0KDUxqdKWYlGYAY5hIw1y3UUsPRUbS3fQKBgQDAZehu+Kb5Sw+h00Qu
        vViNHDvi0PwmhQrHVpgjrppCnWsTk6FJFm+EBLY+87usXuRCnfZ1semb6P+yjLh2
        bJ9IXIrFAztcyE+7eZfn0H7mHA7E2ICKTjNdKbjy8kHViHpgdXREnAOrFTTk/BqW
        dq+weG2OuxYczWsY4XliWaVyiwKBgQC8XYExpSmoyI37o+jr9405k30tbGUw4X+/
        xYOvSUuafI8IOSLfKTpsvkMN3hxpJO6apIRAjOALbotKUA5FrHQPenuBWOr3mBJT
        euLiaWphqU8YN5dbNd+JhC/Jh5DLhY5FpB2Fv2MKSoF7+onpjDy9pEU5aReeBB0v
        ekUw4nWiBQKBgHxyrnjxP1frFG5xMB4nfZqw04+v7BmiXsl3mqsh6kgCeNtN17pl
        17YGMjfgAdnJ+02XzW5tqRSfDp3YZgy7z//HVD+BCqnGK8SxLu/ULfD73xW2kNZl
        JNYzAZ2r06eiQr4X2x/x5nGIIxGmfDAtDxFPpFX5b6ErwgVy+sgCAoFnAoGAWSpu
        EMEdQk+FnnwNsz2g9YNSuyDXmdb08SOfXWd1yXBzCLJ7RmYuyPEbrsHYcxFPfZap
        ICFPoTm35/qTdvnWiskxE56yw3eSHUBLjF/YQtixn0YZeMy8v0z6jgyFR0I2gdLZ
        QsnBKUrxlm2XwR1oV2Eef7m2u085PZNEk4pvor0CgYA6n060r48/CgRVslAeGder
        fZ3n+2ru8q2UVB38evepjLifn5+tKdFzZ7/NckXMC0NOVzm74qG46VFLMw5TtyT4
        /hRvGSYxA6dMjXy+tcrAns9Isrz2PnYFntlbhU6hw0um809tFunbvITfyeOjAsDW
        stC4thnhzXXT1Y3RfFtYEg==
        -----END PRIVATE KEY-----
    encryption:
      key-id: encryption-key
      public-key: |-
        -----BEGIN PUBLIC KEY-----
        MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtU7Vu4tML8qg9BISaUH0
        BTU0+qkHJS3TUl3R0hEPttZJGf8EgT7bpWqRjdhMC2SYt2ifNF82EgMo/eva1rLn
        wYtCsxjJ7oB4U2m16/JKHtphmMUGhSLgbp+Y8pGAQ+P6u4HLlI0qbL92Syb6QCTr
        nYIlzZ2uUAvUQg/SbuAvdS4kdauZtpMNbhryusMVvILVBC5yUhfLJAkjbU3qWo/n
        2NKPr4kjwwFh6FaAf0HLsXCFmJbPPok6WMZeDqPORPZCt5gU2t04fS7s/2SSbhQ/
        i+7yyT4pl44cUlNLLN3Qo73sai5H90q7Dvmk3M5/YMJB0Ueyb705LHyOO5xA618s
        qQIDAQAB
        -----END PUBLIC KEY-----
      private-key: |-
        -----BEGIN PRIVATE KEY-----
        MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC1TtW7i0wvyqD0
        EhJpQfQFNTT6qQclLdNSXdHSEQ+21kkZ/wSBPtulapGN2EwLZJi3aJ80XzYSAyj9
        69rWsufBi0KzGMnugHhTabXr8koe2mGYxQaFIuBun5jykYBD4/q7gcuUjSpsv3ZL
        JvpAJOudgiXNna5QC9RCD9Ju4C91LiR1q5m2kw1uGvK6wxW8gtUELnJSF8skCSNt
        Tepaj+fY0o+viSPDAWHoVoB/QcuxcIWYls8+iTpYxl4Oo85E9kK3mBTa3Th9Luz/
        ZJJuFD+L7vLJPimXjhxSU0ss3dCjvexqLkf3SrsO+aTczn9gwkHRR7JvvTksfI47
        nEDrXyypAgMBAAECggEAREnJHrY8n9OGA+e6n4KD0mJT7gUz98Dm0yMbIC/k50yW
        hAAVRkjSmd8lq3NIURI2ov342NTznJ0sF1d6OVtxBujY2nP/uqEQsPoj1xaO7Ef8
        cnnjFsooFgJurQ44bVm02mLstqrky8jhWTT5FKfTRqP6cRNu0B9kdu1WqQQvW8a/
        C8xD8XUFzzJFQsEstJ076NjlZNH3EeqFiLxyVdV7tPEJRnOe2V2BAAgda3ByA6Jc
        Nd4xYHTVr5rZ+KES9gaAgb86+S7hNigsxz5Gp58NimLEyz1Qd+d9QCgPRgKOV5Uq
        0ci6c28ZrxW9wa/2CGCpoow1V7hRy1fZ24g2Tz91cQKBgQDbSdP/FQYuem0pUf8u
        mA/niEC8Jz30FW3ix5aqbQ8YRudK48Xy8F7AWnlS0wT2k/Xaeppn9YSPK4HlsNk2
        1gnpNfzdqXpJQtuxcPPeFNzUdXzBrsLXYqtlhOX/afrzqMhp73gkqoxXtqwD7BqN
        VfMcVXsWrEZQrRPBn/RUnnLdJwKBgQDTqUGupm93UlhoPgLXHGF/seQwPPHcU6lS
        SS9l512Ie21B+vZecgO4r77BXJwbY4rZVA5/m+wrsNmsT2f8yfdbs84cBDDWiKy5
        t2Um8zrus+BCIffxc9Fck9/htK33jLLcYwdSAm3a9pJxR9f/kAdredSTGBNJ3W/2
        rfh3cdNprwKBgDi7WfBFRSsjGzi0cPth9cNlubGzyVBrdtlT34PJ4Tzboxz53o1i
        aHEFNxwZYdBVKSbTzzyUBS5xCBMfdKK+LyQ5hmjmXq+zb1jxqvXKmfMRTixhhSDp
        8wO5pTM1/Omqwea+QGvj/5j1tnzxSVFFajbrWoPcH/jhPho6wqBducPDAoGBALOJ
        MEOavZXy7TaO0w3v7uvH0wzvxR/kfw1jMqc3l2j7ePOskmoOQAXaXO3bRjcdOlua
        Jyoq8islOZ4lRMlx7zWD0OKG035GNGzbmRtu2aA8R48RDSVr3jyu2gqznZULbXPv
        M/hmQxSmbhVUoW0PmJubnaqfk0zmXeBaNRXsIS3VAoGBALdsAtqR23PVeL6sYj2l
        dRNTDXpfvjFqJ5NThRO/4mT0CrPHQVj+Mz2bTc/Dxiwi8s8m3L+g23i3hodh/QMb
        Iz+UbcJZBGAKsFbPKGOtj6Bi07y/L11mcuNJzOWe61/JbVmJss0s+N/v3XucK/Ge
        CUaGOccsMO221v6JoBh9J3Hz
        -----END PRIVATE KEY-----

🛠️ Step 3: Security Configuration

In this section, we define the beans and properties required to load credentials, RSA keys, and HTTP security filters for JWE-based authentication:

• AdminProperties: Loads admin username and password from application properties.
• UserProperties: Loads normal user credentials from application properties.
• JwtProperties: Configures JWT issuer, expiration, and signing/encryption key pairs.
• SecurityJwtConfig: Builds RSA JWKs, JWT encoder/decoder, authentication converter, and token resolver.
• SecurityConfig: Defines in-memory users and the stateless security filter chain with route authorization.

AdminProperties

Java

package io.github.susimsek.springbootjwedemo.config;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;

@Configuration
@ConfigurationProperties(prefix = "security.admin")
@Data
public class AdminProperties {
    private String username;
    private String password;
}

Kotlin

package io.github.susimsek.springbootjwedemo.config

import org.springframework.boot.context.properties.ConfigurationProperties
import org.springframework.context.annotation.Configuration

@Configuration
@ConfigurationProperties(prefix = "security.admin")
class AdminProperties {
  lateinit var username: String
  lateinit var password: String
}

SecurityJwtConfig

Java

package io.github.susimsek.springbootjwedemo.config;

import com.nimbusds.jose.EncryptionMethod;
import com.nimbusds.jose.JWEAlgorithm;
import com.nimbusds.jose.JWSAlgorithm;
import com.nimbusds.jose.jwk.JWKSet;
import com.nimbusds.jose.jwk.RSAKey;
import com.nimbusds.jose.jwk.source.JWKSource;
import com.nimbusds.jose.proc.JWEDecryptionKeySelector;
import com.nimbusds.jose.proc.JWSVerificationKeySelector;
import com.nimbusds.jose.proc.SecurityContext;
import com.nimbusds.jwt.proc.DefaultJWTProcessor;
import io.github.susimsek.springbootjwedemo.security.CookieBearerTokenResolver;
import io.github.susimsek.springbootjwedemo.security.KeyUtils;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.oauth2.jwt.JwtDecoder;
import org.springframework.security.oauth2.jwt.JwtEncoder;
import org.springframework.security.oauth2.jwt.NimbusJwtDecoder;
import org.springframework.security.oauth2.jwt.NimbusJwtEncoder;
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter;
import org.springframework.security.oauth2.server.resource.authentication.JwtGrantedAuthoritiesConverter;
import org.springframework.security.oauth2.server.resource.web.BearerTokenResolver;

import java.util.List;

import static io.github.susimsek.springbootjwedemo.security.SecurityUtils.AUTHORITIES_KEY;

@Configuration
public class SecurityJwtConfig {

    private final JwtProperties props;
    public SecurityJwtConfig(JwtProperties props) { this.props = props; }

    @Bean
    public RSAKey signingKey() throws Exception {
        return KeyUtils.buildRsaKey(
            props.getSigning().getPublicKey(),
            props.getSigning().getPrivateKey(),
            props.getSigning().getKeyId(),
            true
        );
    }

    @Bean
    public RSAKey encryptionKey() throws Exception {
        return KeyUtils.buildRsaKey(
            props.getEncryption().getPublicKey(),
            props.getEncryption().getPrivateKey(),
            props.getEncryption().getKeyId(),
            false
        );
    }

    @Bean
    public JWKSource<SecurityContext> jwkSource(RSAKey signingKey, RSAKey encryptionKey) {
        JWKSet jwkSet = new JWKSet(List.of(
            signingKey,
            encryptionKey
        ));
        return (jwkSelector, context) -> jwkSelector.select(jwkSet);
    }

    @Bean
    public JwtDecoder jwtDecoder(JWKSource<SecurityContext> jwkSource) {
        DefaultJWTProcessor<SecurityContext> jwtProcessor = new DefaultJWTProcessor<>();
        JWEDecryptionKeySelector<SecurityContext> jweKeySelector =
            new JWEDecryptionKeySelector<>(
                JWEAlgorithm.RSA_OAEP_256,
                EncryptionMethod.A128GCM,
                jwkSource
            );
        jwtProcessor.setJWEKeySelector(jweKeySelector);

        JWSVerificationKeySelector<SecurityContext> jwsKeySelector =
            new JWSVerificationKeySelector<>(
                JWSAlgorithm.RS256,
                jwkSource
            );
        jwtProcessor.setJWSKeySelector(jwsKeySelector);
        jwtProcessor.setJWTClaimsSetVerifier((claims, context) -> {});

        return new NimbusJwtDecoder(jwtProcessor);
    }

    @Bean
    public JwtEncoder jwtEncoder(JWKSource<SecurityContext> jwkSource) {
        return new NimbusJwtEncoder(jwkSource);
    }

    @Bean
    public JwtAuthenticationConverter jwtAuthenticationConverter() {
        JwtGrantedAuthoritiesConverter converter = new JwtGrantedAuthoritiesConverter();
        converter.setAuthorityPrefix("");
        converter.setAuthoritiesClaimName(AUTHORITIES_KEY);

        JwtAuthenticationConverter authConverter = new JwtAuthenticationConverter();
        authConverter.setJwtGrantedAuthoritiesConverter(converter);
        return authConverter;
    }

    @Bean
    public BearerTokenResolver bearerTokenResolver() {
        CookieBearerTokenResolver resolver = new CookieBearerTokenResolver();
        resolver.setAllowUriQueryParameter(false);
        resolver.setAllowFormEncodedBodyParameter(false);
        resolver.setAllowCookie(true);
        return resolver;
    }
}

Kotlin

package io.github.susimsek.springbootjwedemo.config

import com.nimbusds.jose.EncryptionMethod
import com.nimbusds.jose.JWEAlgorithm
import com.nimbusds.jose.JWSAlgorithm
import com.nimbusds.jose.jwk.JWKSet
import com.nimbusds.jose.jwk.RSAKey
import com.nimbusds.jose.jwk.source.JWKSource
import com.nimbusds.jose.proc.JWEDecryptionKeySelector
import com.nimbusds.jose.proc.JWSVerificationKeySelector
import com.nimbusds.jose.proc.SecurityContext
import com.nimbusds.jwt.proc.DefaultJWTProcessor
import io.github.susimsek.springbootjwedemo.security.CookieBearerTokenResolver
import io.github.susimsek.springbootjwedemo.security.KeyUtils
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.security.oauth2.jwt.JwtDecoder
import org.springframework.security.oauth2.jwt.JwtEncoder
import org.springframework.security.oauth2.jwt.NimbusJwtDecoder
import org.springframework.security.oauth2.jwt.NimbusJwtEncoder
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter
import org.springframework.security.oauth2.server.resource.authentication.JwtGrantedAuthoritiesConverter
import org.springframework.security.oauth2.server.resource.web.BearerTokenResolver

@Configuration
class SecurityJwtConfig(private val props: JwtProperties) {

    @Bean
    @Throws(Exception::class)
    fun signingKey(): RSAKey =
        KeyUtils.buildRsaKey(
            props.signing.publicKey,
            props.signing.privateKey,
            props.signing.keyId,
            true
        )

    @Bean
    @Throws(Exception::class)
    fun encryptionKey(): RSAKey =
        KeyUtils.buildRsaKey(
            props.encryption.publicKey,
            props.encryption.privateKey,
            props.encryption.keyId,
            false
        )

    @Bean
    fun jwkSource(signingKey: RSAKey, encryptionKey: RSAKey): JWKSource<SecurityContext> {
        val jwkSet = JWKSet(listOf(signingKey, encryptionKey))
        return JWKSource { jwkSelector, context -> jwkSelector.select(jwkSet) }
    }

    @Bean
    fun jwtDecoder(jwkSource: JWKSource<SecurityContext>): JwtDecoder {
        val jwtProcessor = DefaultJWTProcessor<SecurityContext>()
        val jweKeySelector = JWEDecryptionKeySelector(
            JWEAlgorithm.RSA_OAEP_256,
            EncryptionMethod.A128GCM,
            jwkSource
        )
        jwtProcessor.jweKeySelector = jweKeySelector
        val jwsKeySelector = JWSVerificationKeySelector(
            JWSAlgorithm.RS256,
            jwkSource
        )
        jwtProcessor.jwsKeySelector = jwsKeySelector
        jwtProcessor.jwtClaimsSetVerifier = { _, _ -> }
        return NimbusJwtDecoder(jwtProcessor)
    }

    @Bean
    fun jwtEncoder(jwkSource: JWKSource<SecurityContext>): JwtEncoder =
        NimbusJwtEncoder(jwkSource)

    @Bean
    fun jwtAuthenticationConverter(): JwtAuthenticationConverter {
        val converter = JwtGrantedAuthoritiesConverter().apply {
            setAuthorityPrefix("")
            setAuthoritiesClaimName(AUTHORITIES_KEY)
        }
        return JwtAuthenticationConverter().apply {
            setJwtGrantedAuthoritiesConverter(converter)
        }
    }

    @Bean
    fun bearerTokenResolver(): BearerTokenResolver =
        CookieBearerTokenResolver().apply {
            setAllowUriQueryParameter(false)
            setAllowFormEncodedBodyParameter(false)
            setAllowCookie(true)
        }
}

SecurityConfig

Java

package io.github.susimsek.springbootjwedemo.config;

import io.github.susimsek.springbootjwedemo.security.AuthoritiesConstants;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.ProviderManager;
import org.springframework.security.authentication.dao.DaoAuthenticationProvider;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.core.userdetails.User;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.provisioning.InMemoryUserDetailsManager;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.servlet.util.matcher.MvcRequestMatcher;
import org.springframework.web.servlet.handler.HandlerMappingIntrospector;

import static org.springframework.security.config.Customizer.withDefaults;

@Configuration
@EnableMethodSecurity(securedEnabled = true)
public class SecurityConfig {

    @Bean
    public InMemoryUserDetailsManager userDetailsService(AdminProperties adminProps,
                                                         UserProperties userProps,
                                                         PasswordEncoder passwordEncoder) {
        var admin = User.withUsername(adminProps.getUsername())
            .password(passwordEncoder.encode(adminProps.getPassword()))
            .authorities(AuthoritiesConstants.ADMIN)
            .build();

        var user = User.withUsername(userProps.getUsername())
            .password(passwordEncoder.encode(userProps.getPassword()))
            .authorities(AuthoritiesConstants.USER)
            .build();

        return new InMemoryUserDetailsManager(admin, user);
    }

    @Bean public PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(); }

    @Bean
    public AuthenticationManager authenticationManager(UserDetailsService uds) {
        var provider = new DaoAuthenticationProvider();
        provider.setUserDetailsService(uds);
        provider.setPasswordEncoder(passwordEncoder());
        return new ProviderManager(provider);
    }

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http,
                                           MvcRequestMatcher.Builder mvc) throws Exception {
        http
            .cors(withDefaults())
            .csrf(AbstractHttpConfigurer::disable)
            .authorizeHttpRequests(authz ->
                authz
                    .requestMatchers(mvc.pattern("/*.ico"), mvc.pattern("/*.png"), mvc.pattern("/*.svg"),
                        mvc.pattern("/*.webapp")
                    ).permitAll()
                    .requestMatchers("/actuator/**").permitAll()
                    .requestMatchers(
                        "/v3/api-docs/**",
                        "/swagger-ui.html",
                        "/swagger-ui/**"
                    ).permitAll()
                    .requestMatchers(mvc.pattern("/api/auth/login")).permitAll()
                    .requestMatchers(mvc.pattern("/api/hello/admin")).hasAuthority(AuthoritiesConstants.ADMIN)
                .anyRequest().authenticated()
            )
            .sessionManagement(session ->
                session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .oauth2ResourceServer(oauth2 -> oauth2
                .jwt(withDefaults())
            );
        return http.build();
    }

    @Bean
    public MvcRequestMatcher.Builder mvc(HandlerMappingIntrospector introspector) {
        return new MvcRequestMatcher.Builder(introspector);
    }
}

Kotlin

package io.github.susimsek.springbootjwedemo.config

import io.github.susimsek.springbootjwedemo.security.AuthoritiesConstants
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.security.authentication.AuthenticationManager
import org.springframework.security.authentication.ProviderManager
import org.springframework.security.authentication.dao.DaoAuthenticationProvider
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity
import org.springframework.security.config.annotation.web.builders.HttpSecurity
import org.springframework.security.config.http.SessionCreationPolicy
import org.springframework.security.core.userdetails.User
import org.springframework.security.core.userdetails.UserDetailsService
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder
import org.springframework.security.crypto.password.PasswordEncoder
import org.springframework.security.provisioning.InMemoryUserDetailsManager
import org.springframework.security.web.SecurityFilterChain
import org.springframework.security.web.servlet.util.matcher.MvcRequestMatcher
import org.springframework.web.servlet.handler.HandlerMappingIntrospector
import org.springframework.security.config.Customizer.withDefaults

@Configuration
@EnableMethodSecurity(securedEnabled = true)
class SecurityConfig {

    @Bean
    fun userDetailsService(
        adminProps: AdminProperties,
        userProps: UserProperties,
        passwordEncoder: PasswordEncoder
    ): UserDetailsService {
        val admin = User.withUsername(adminProps.username)
            .password(passwordEncoder.encode(adminProps.password))
            .authorities(AuthoritiesConstants.ADMIN)
            .build()
        val user = User.withUsername(userProps.username)
            .password(passwordEncoder.encode(userProps.password))
            .authorities(AuthoritiesConstants.USER)
            .build()
        return InMemoryUserDetailsManager(admin, user)
    }

    @Bean
    fun passwordEncoder(): PasswordEncoder = BCryptPasswordEncoder()

    @Bean
    fun authenticationManager(uds: UserDetailsService): AuthenticationManager {
        val provider = DaoAuthenticationProvider().apply {
            setUserDetailsService(uds)
            setPasswordEncoder(passwordEncoder())
        }
        return ProviderManager(provider)
    }

    @Bean
    fun filterChain(http: HttpSecurity, mvc: MvcRequestMatcher.Builder): SecurityFilterChain =
        http.cors(withDefaults())
            .csrf { it.disable() }
            .authorizeHttpRequests { authz ->
                authz
                    .requestMatchers(mvc.pattern("/*.ico"), mvc.pattern("/*.png"), mvc.pattern("/*.svg"), mvc.pattern("/*.webapp")).permitAll()
                    .requestMatchers("/actuator/**").permitAll()
                    .requestMatchers("/v3/api-docs/**", "/swagger-ui.html", "/swagger-ui/**").permitAll()
                    .requestMatchers(mvc.pattern("/api/auth/login")).permitAll()
                    .requestMatchers(mvc.pattern("/api/hello/admin")).hasAuthority(AuthoritiesConstants.ADMIN)
                    .anyRequest().authenticated()
            }
            .sessionManagement { it.sessionCreationPolicy(SessionCreationPolicy.STATELESS) }
            .oauth2ResourceServer { it.jwt(withDefaults()) }
            .build()

    @Bean
    fun mvc(introspector: HandlerMappingIntrospector): MvcRequestMatcher.Builder =
        MvcRequestMatcher.Builder(introspector)
}

JwtProperties

Java

package io.github.susimsek.springbootjwedemo.config;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;

import java.time.Duration;

@Configuration
@ConfigurationProperties(prefix = "security.jwt")
@Data
public class JwtProperties {

    @Data
    public static class Pair {
        private String publicKey;
        private String privateKey;
        private String keyId;
    }

    private Pair signing;
    private Pair encryption;
    private String issuer;
    private Duration expirationDuration;
}

Kotlin

package io.github.susimsek.springbootjwedemo.config

import org.springframework.boot.context.properties.ConfigurationProperties
import org.springframework.context.annotation.Configuration
import java.time.Duration

@Configuration
@ConfigurationProperties(prefix = "security.jwt")
class JwtProperties {

  class Pair {
    lateinit var publicKey: String
    lateinit var privateKey: String
    lateinit var keyId: String
  }

  lateinit var signing: Pair
  lateinit var encryption: Pair
  lateinit var issuer: String
  lateinit var expirationDuration: Duration
}

UserProperties

Java

package io.github.susimsek.springbootjwedemo.config;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;

@Configuration
@ConfigurationProperties(prefix = "security.user")
@Data
public class UserProperties {
    private String username;
    private String password;
}

Kotlin

package io.github.susimsek.springbootjwedemo.config

import org.springframework.boot.context.properties.ConfigurationProperties
import org.springframework.context.annotation.Configuration

@Configuration
@ConfigurationProperties(prefix = "security.user")
class UserProperties {
  lateinit var username: String
  lateinit var password: String
}

🛠️ Step 4: Secure JWE Token Utilities

In this section, we define the core utility classes and constants needed to generate, encrypt, and resolve JSON Web Encryption (JWE) tokens in your Spring Boot application. These components work together to:

• AuthoritiesConstants: Centralize role names with the ROLE_ prefix.
• CookieBearerTokenResolver: Resolve bearer tokens from Authorization headers or HTTP cookies.
• CookieUtils: Create HTTP-only, secure cookies for access tokens.
• JweUtil: Sign (JWS) and encrypt (JWE) JWTs using RSA keys and Nimbus.
• KeyUtils: Build RSA JWKs from PEM‐encoded key material.
• SecurityUtils: Extract the current user’s login from the security context.

These utilities form the foundation for a stateless, JWE‐based authentication flow in Spring Security.

AuthoritiesConstants

Java

package io.github.susimsek.springbootjwedemo.security;

import lombok.AccessLevel;
import lombok.NoArgsConstructor;

@NoArgsConstructor(access = AccessLevel.PRIVATE)
public final class AuthoritiesConstants {
    public static final String ADMIN = "ROLE_ADMIN";
    public static final String USER = "ROLE_USER";
    public static final String ANONYMOUS = "ROLE_ANONYMOUS";
}

Kotlin

package io.github.susimsek.springbootjwedemo.security

object AuthoritiesConstants {
  const val ADMIN = "ROLE_ADMIN"
  const val USER = "ROLE_USER"
  const val ANONYMOUS = "ROLE_ANONYMOUS"
}

CookieBearerTokenResolver

Java

package io.github.susimsek.springbootjwedemo.security;

import jakarta.servlet.http.Cookie;
import jakarta.servlet.http.HttpServletRequest;
import lombok.Setter;
import org.springframework.http.HttpMethod;
import org.springframework.security.oauth2.core.OAuth2AuthenticationException;
import org.springframework.security.oauth2.server.resource.BearerTokenError;
import org.springframework.security.oauth2.server.resource.BearerTokenErrors;
import org.springframework.security.oauth2.server.resource.web.BearerTokenResolver;
import org.springframework.util.StringUtils;

import java.util.regex.Matcher;
import java.util.regex.Pattern;

@Setter
public class CookieBearerTokenResolver implements BearerTokenResolver {
    private static final String ACCESS_TOKEN_PARAMETER_NAME = "access_token";
    private static final Pattern AUTHORIZATION_PATTERN =
        Pattern.compile("^Bearer (?<token>[A-Za-z0-9-._~+/]+=*)$", Pattern.CASE_INSENSITIVE);

    private boolean allowFormEncodedBodyParameter = false;
    private boolean allowUriQueryParameter       = false;
    private boolean allowCookie                  = true;
    private String  bearerTokenHeaderName       = "Authorization";
    private String  cookieName                  = "accessToken";

    @Override
    public String resolve(HttpServletRequest request) {
        String headerToken = resolveFromAuthorizationHeader(request);
        String queryToken  = resolveAccessTokenFromQueryString(request);
        String bodyToken   = resolveAccessTokenFromBody(request);
        String cookieToken = (headerToken == null && queryToken == null && bodyToken == null)
            ? resolveFromCookie(request)
            : null;

        return resolveToken(headerToken, queryToken, bodyToken, cookieToken);
    }

    private String resolveFromAuthorizationHeader(HttpServletRequest request) {
        String authorization = request.getHeader(this.bearerTokenHeaderName);
        if (!StringUtils.hasText(authorization) || !authorization.toLowerCase().startsWith("bearer")) {
            return null;
        }
        Matcher matcher = AUTHORIZATION_PATTERN.matcher(authorization.trim());
        if (!matcher.matches()) {
            BearerTokenError error = BearerTokenErrors.invalidToken("Bearer token is malformed");
            throw new OAuth2AuthenticationException(error);
        }
        return matcher.group("token");
    }

    private String resolveAccessTokenFromQueryString(HttpServletRequest request) {
        if (allowUriQueryParameter && HttpMethod.GET.matches(request.getMethod())) {
            return resolveToken(request.getParameterValues(ACCESS_TOKEN_PARAMETER_NAME));
        }
        return null;
    }

    private String resolveAccessTokenFromBody(HttpServletRequest request) {
        if (allowFormEncodedBodyParameter
            && HttpMethod.POST.matches(request.getMethod())
            && "application/x-www-form-urlencoded".equals(request.getContentType())) {
            return resolveToken(request.getParameterValues(ACCESS_TOKEN_PARAMETER_NAME));
        }
        return null;
    }

    private String resolveFromCookie(HttpServletRequest request) {
        if (!allowCookie || request.getCookies() == null) {
            return null;
        }
        for (Cookie cookie : request.getCookies()) {
            if (cookieName.equals(cookie.getName())) {
                String val = cookie.getValue();
                return StringUtils.hasText(val) ? val : null;
            }
        }
        return null;
    }

    private String resolveToken(String... tokens) {
        String found = null;
        for (String token : tokens) {
            if (token == null) continue;
            if (found != null) {
                BearerTokenError error = BearerTokenErrors.invalidRequest("Found multiple bearer tokens in the request");
                throw new OAuth2AuthenticationException(error);
            }
            found = token;
        }
        if (found != null && found.isBlank()) {
            BearerTokenError error = BearerTokenErrors.invalidRequest("The requested token parameter is an empty string");
            throw new OAuth2AuthenticationException(error);
        }
        return found;
    }

Kotlin

package io.github.susimsek.springbootjwedemo.security

import jakarta.servlet.http.Cookie
import jakarta.servlet.http.HttpServletRequest
import org.springframework.http.HttpMethod
import org.springframework.security.oauth2.core.OAuth2AuthenticationException
import org.springframework.security.oauth2.server.resource.BearerTokenError
import org.springframework.security.oauth2.server.resource.BearerTokenErrors
import org.springframework.security.oauth2.server.resource.web.BearerTokenResolver
import org.springframework.util.StringUtils
import java.util.regex.Pattern

class CookieBearerTokenResolver {
    var allowFormEncodedBodyParameter: Boolean = false
    var allowUriQueryParameter: Boolean = false
    var allowCookie: Boolean = true
    var bearerTokenHeaderName: String = "Authorization"
    var cookieName: String = "accessToken"

    companion object {
        private const val ACCESS_TOKEN_PARAMETER_NAME = "access_token"
        private val AUTHORIZATION_PATTERN =
            Pattern.compile("^Bearer (?<token>[A-Za-z0-9-._~+/]+=*)$", Pattern.CASE_INSENSITIVE)
    }

    fun resolve(request: HttpServletRequest): String? {
        val header = resolveFromAuthorizationHeader(request)
        val query  = if (allowUriQueryParameter && HttpMethod.GET.matches(request.method))
            request.getParameterValues(ACCESS_TOKEN_PARAMETER_NAME)?.let(::resolveToken)
        else null
        val body   = if (allowFormEncodedBodyParameter && HttpMethod.POST.matches(request.method)
            && request.contentType == "application/x-www-form-urlencoded")
            request.getParameterValues(ACCESS_TOKEN_PARAMETER_NAME)?.let(::resolveToken)
        else null
        val cookie = if (header == null && query == null && body == null)
            resolveFromCookie(request)
        else null
      return listOf(header, query, body, cookie).filterNotNull().let {
            if (it.size > 1) throw OAuth2AuthenticationException(BearerTokenErrors.invalidRequest("Found multiple bearer tokens"))
            it.firstOrNull()?: null
        }
    }

    private fun resolveFromAuthorizationHeader(request: HttpServletRequest): String? {
        val auth = request.getHeader(bearerTokenHeaderName) ?: return null
        if (!auth.startsWith("Bearer ", true)) return null
        val matcher = AUTHORIZATION_PATTERN.matcher(auth.trim())
        return if (matcher.matches()) matcher.group("token")
        else throw OAuth2AuthenticationException(BearerTokenErrors.invalidToken("Malformed token"))
    }

    private fun resolveFromCookie(request: HttpServletRequest): String? {
        if (!allowCookie) return null
        return request.cookies?.firstOrNull { it.name == cookieName }?.value?.takeIf { it.isNotBlank() }
    }

    private fun resolveToken(tokens: Array<String>): String? {
        return tokens.filter { it.isNotBlank() }.let {
            when {
                it.isEmpty() -> null
                it.size > 1   -> throw OAuth2AuthenticationException(BearerTokenErrors.invalidRequest("Multiple tokens"))
                else          -> it[0]
            }
        }
    }

CookieUtils

Java

package io.github.susimsek.springbootjwedemo.security;

import io.github.susimsek.springbootjwedemo.dto.TokenDTO;
import lombok.experimental.UtilityClass;
import org.springframework.http.ResponseCookie;

@UtilityClass
public class CookieUtils {

    private static final String COOKIE_NAME = "accessToken";

    public ResponseCookie createAccessTokenCookie(TokenDTO tokenDto) {
        return ResponseCookie.from(COOKIE_NAME, tokenDto.accessToken())
            .httpOnly(true)
            .secure(true)
            .path("/")
            .maxAge(tokenDto.accessTokenExpiresIn())
            .sameSite("Strict")
            .build();
    }
}

Kotlin

package io.github.susimsek.springbootjwedemo.security

import io.github.susimsek.springbootjwedemo.dto.TokenDTO
import org.springframework.http.ResponseCookie

object CookieUtils {

  private const val COOKIE_NAME = "accessToken"

  fun createAccessTokenCookie(tokenDto: TokenDTO): ResponseCookie {
    return ResponseCookie.from(COOKIE_NAME, tokenDto.accessToken())
      .httpOnly(true)
      .secure(true)
      .path("/")
      .maxAge(tokenDto.accessTokenExpiresIn())
      .sameSite("Strict")
      .build()
  }
}

JweUtil

Java

package io.github.susimsek.springbootjwedemo.security;

import com.nimbusds.jose.EncryptionMethod;
import com.nimbusds.jose.JOSEException;
import com.nimbusds.jose.JWEAlgorithm;
import com.nimbusds.jose.JWEHeader;
import com.nimbusds.jose.JWEObject;
import com.nimbusds.jose.Payload;
import com.nimbusds.jose.crypto.RSAEncrypter;
import com.nimbusds.jose.jwk.RSAKey;
import io.github.susimsek.springbootjwedemo.config.JwtProperties;
import io.github.susimsek.springbootjwedemo.dto.TokenDTO;
import lombok.RequiredArgsConstructor;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.oauth2.jose.jws.SignatureAlgorithm;
import org.springframework.security.oauth2.jwt.*;
import org.springframework.stereotype.Component;

import java.time.Instant;
import java.util.List;

import static io.github.susimsek.springbootjwedemo.security.SecurityUtils.AUTHORITIES_KEY;

@Component
@RequiredArgsConstructor
public class JweUtil {

    private final JwtEncoder jwtEncoder;
    private final RSAKey signingKey;
    private final RSAKey encryptionKey;
    private final JwtProperties props;

    public TokenDTO generateToken(Authentication authentication) throws JOSEException {
        String subject = authentication.getName();
        List<String> roles = authentication.getAuthorities()
            .stream()
            .map(GrantedAuthority::getAuthority)
            .toList();

        Instant now = Instant.now();
        long expiresIn = props.getExpirationDuration().getSeconds();
        Instant exp = now.plusSeconds(expiresIn);

        JwtClaimsSet claims = JwtClaimsSet.builder()
            .issuer(props.getIssuer())
            .issuedAt(now)
            .expiresAt(exp)
            .subject(subject)
            .claim(AUTHORITIES_KEY, roles)
            .build();

        JwsHeader jwsHeader = JwsHeader.with(SignatureAlgorithm.RS256)
            .keyId(signingKey.getKeyID())
            .build();

        String jws = jwtEncoder
            .encode(JwtEncoderParameters.from(jwsHeader, claims))
            .getTokenValue();

        JWEHeader jweHeader = new JWEHeader.Builder(JWEAlgorithm.RSA_OAEP_256, EncryptionMethod.A128GCM)
            .contentType("JWT")
            .keyID(encryptionKey.getKeyID())
            .build();

        JWEObject jweObject = new JWEObject(jweHeader, new Payload(jws));
        jweObject.encrypt(new RSAEncrypter(encryptionKey.toRSAPublicKey()));
        String token = jweObject.serialize();

        return new TokenDTO(token, "Bearer", expiresIn);
    }
}

Kotlin

package io.github.susimsek.springbootjwedemo.security

import com.nimbusds.jose.EncryptionMethod
import com.nimbusds.jose.JOSEException
import com.nimbusds.jose.JWEAlgorithm
import com.nimbusds.jose.JWEHeader
import com.nimbusds.jose.JWEObject
import com.nimbusds.jose.Payload
import com.nimbusds.jose.crypto.RSAEncrypter
import com.nimbusds.jose.jwk.RSAKey
import io.github.susimsek.springbootjwedemo.config.JwtProperties
import io.github.susimsek.springbootjwedemo.dto.TokenDTO
import lombok.RequiredArgsConstructor
import org.springframework.security.core.Authentication
import org.springframework.security.oauth2.jose.jws.SignatureAlgorithm
import org.springframework.security.oauth2.jwt.JwtClaimsSet
import org.springframework.security.oauth2.jwt.JwtEncoder
import org.springframework.security.oauth2.jwt.JwtEncoderParameters
import org.springframework.stereotype.Component

import java.time.Instant

@Component
@RequiredArgsConstructor
class JweUtil(
    private val jwtEncoder: JwtEncoder,
    private val signingKey: RSAKey,
    private val encryptionKey: RSAKey,
    private val props: JwtProperties
) {
    fun generateToken(authentication: Authentication): TokenDTO {
        val subject = authentication.name
        val roles = authentication.authorities.map { it.authority }

        val now = Instant.now()
        val expiresIn = props.expirationDuration.seconds
        val exp = now.plusSeconds(expiresIn)

        val claims = JwtClaimsSet.builder()
            .issuer(props.issuer)
            .issuedAt(now)
            .expiresAt(exp)
            .subject(subject)
            .claim(AUTHORITIES_KEY, roles)
            .build()

        val jwsHeader = org.springframework.security.oauth2.jwt.JwsHeader.with(SignatureAlgorithm.RS256)
            .keyId(signingKey.keyID)
            .build()

        val jws = jwtEncoder
            .encode(JwtEncoderParameters.from(jwsHeader, claims))
            .tokenValue

        val jweHeader = JWEHeader.Builder(JWEAlgorithm.RSA_OAEP_256, EncryptionMethod.A128GCM)
            .contentType("JWT")
            .keyID(encryptionKey.keyID)
            .build()

        val jweObject = JWEObject(jweHeader, Payload(jws))
        jweObject.encrypt(RSAEncrypter(encryptionKey.toRSAPublicKey()))
        val token = jweObject.serialize()

        return TokenDTO(token, "Bearer", expiresIn)
    }
}

KeyUtils

Java

package io.github.susimsek.springbootjwedemo.security;

import com.nimbusds.jose.JWEAlgorithm;
import com.nimbusds.jose.JWSAlgorithm;
import com.nimbusds.jose.jwk.KeyUse;
import com.nimbusds.jose.jwk.RSAKey;
import lombok.experimental.UtilityClass;

import java.security.KeyFactory;
import java.security.interfaces.RSAPrivateKey;
import java.security.interfaces.RSAPublicKey;
import java.security.spec.PKCS8EncodedKeySpec;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;

@UtilityClass
public class KeyUtils {
    public RSAKey buildRsaKey(
            String pubPem,
            String privPem,
            String kid,
            boolean forSign
    ) throws Exception {
        String pubContent = pubPem
            .replace("-----BEGIN PUBLIC KEY-----", "")
            .replace("-----END PUBLIC KEY-----", "")
            .replaceAll("\\s", "");
        String privContent = privPem
            .replace("-----BEGIN PRIVATE KEY-----", "")
            .replace("-----END PRIVATE KEY-----", "")
            .replaceAll("\\s", "");

        byte[] decodedPub = Base64.getDecoder().decode(pubContent);
        byte[] decodedPriv = Base64.getDecoder().decode(privContent);

        KeyFactory kf = KeyFactory.getInstance("RSA");
        RSAPublicKey publicKey = (RSAPublicKey) kf.generatePublic(new X509EncodedKeySpec(decodedPub));
        RSAPrivateKey privateKey = (RSAPrivateKey) kf.generatePrivate(new PKCS8EncodedKeySpec(decodedPriv));

        RSAKey.Builder builder = new RSAKey.Builder(publicKey)
            .privateKey(privateKey)
            .keyID(kid);

        if (forSign) {
            builder
                .algorithm(JWSAlgorithm.RS256)
                .keyUse(KeyUse.SIGNATURE);
        } else {
            builder
                .algorithm(JWEAlgorithm.RSA_OAEP_256)
                .keyUse(KeyUse.ENCRYPTION);
        }

        return builder.build();
    }
}

Kotlin

package io.github.susimsek.springbootjwedemo.security

import com.nimbusds.jose.JWEAlgorithm
import com.nimbusds.jose.JWSAlgorithm
import com.nimbusds.jose.jwk.KeyUse
import com.nimbusds.jose.jwk.RSAKey
import java.security.KeyFactory
import java.security.interfaces.RSAPrivateKey
import java.security.interfaces.RSAPublicKey
import java.security.spec.PKCS8EncodedKeySpec
import java.security.spec.X509EncodedKeySpec
import java.util.Base64

object KeyUtils {
    @JvmStatic
    @Throws(Exception::class)
    fun buildRsaKey(
        pubPem: String,
        privPem: String,
        kid: String,
        forSign: Boolean
    ): RSAKey {
        val pubContent = pubPem
            .replace("-----BEGIN PUBLIC KEY-----", "")
            .replace("-----END PUBLIC KEY-----", "")
            .replace(Regex("\\s"), "")
        val privContent = privPem
            .replace("-----BEGIN PRIVATE KEY-----", "")
            .replace("-----END PRIVATE KEY-----", "")
            .replace(Regex("\\s"), "")

        val decodedPub = Base64.getDecoder().decode(pubContent)
        val decodedPriv = Base64.getDecoder().decode(privContent)

        val kf = KeyFactory.getInstance("RSA")
        val publicKey = kf.generatePublic(X509EncodedKeySpec(decodedPub)) as RSAPublicKey
        val privateKey = kf.generatePrivate(PKCS8EncodedKeySpec(decodedPriv)) as RSAPrivateKey

        val builder = RSAKey.Builder(publicKey)
            .privateKey(privateKey)
            .keyID(kid)

        if (forSign) {
            builder
                .algorithm(JWSAlgorithm.RS256)
                .keyUse(KeyUse.SIGNATURE)
        } else {
            builder
                .algorithm(JWEAlgorithm.RSA_OAEP_256)
                .keyUse(KeyUse.ENCRYPTION)
        }

        return builder.build()
    }
}

SecurityUtils

Java

package io.github.susimsek.springbootjwedemo.security;

import lombok.experimental.UtilityClass;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.oauth2.jwt.Jwt;

import java.util.Optional;

@UtilityClass
public class SecurityUtils {

    public static final String AUTHORITIES_KEY = "auth";

    public Optional<String> getCurrentUserLogin() {
        var ctx = SecurityContextHolder.getContext();
        return Optional.ofNullable(extractPrincipal(ctx.getAuthentication()));
    }

    private String extractPrincipal(Authentication authentication) {
        if (authentication == null) {
            return null;
        }
        Object principal = authentication.getPrincipal();
        if (principal instanceof Jwt jwt) {
            return jwt.getSubject();
        }
        if (principal instanceof UserDetails ud) {
            return ud.getUsername();
        }
        if (principal instanceof String username) {
            return username;
        }
        return null;
    }
}

Kotlin

package io.github.susimsek.springbootjwedemo.security

import org.springframework.security.core.Authentication
import org.springframework.security.core.context.SecurityContextHolder
import org.springframework.security.core.userdetails.UserDetails
import org.springframework.security.oauth2.jwt.Jwt
import java.util.Optional

object SecurityUtils {
  const val AUTHORITIES_KEY = "auth"

  fun getCurrentUserLogin(): Optional<String> {
    val authentication: Authentication? = SecurityContextHolder.getContext().authentication
    return Optional.ofNullable(extractPrincipal(authentication))
  }

  private fun extractPrincipal(authentication: Authentication?): String? {
    return when (val principal = authentication?.principal) {
      is Jwt -> principal.subject
      is UserDetails -> principal.username
      is String -> principal
      else -> null
    }
  }
}

🛠️ Step 5: Authentication & Protected Endpoints

In this section, we define the REST controllers and DTOs necessary for:

• AuthController: Authenticate users, issue JWE tokens, and set secure cookies.
• HelloController: Expose protected resource endpoints for authenticated users and admin-specific paths.
• LoginRequestDTO: Model the login request payload (username/password).
• TokenDTO: Model the authentication response including token and expiration.

These components complete the stateless authentication flow by handling login, token issuance, cookie management, and resource protection.

In this section, we expose REST controllers and DTOs to handle user authentication, token issuance, and protected resource access.

AuthController

Java

package io.github.susimsek.springbootjwedemo.controller;

import io.github.susimsek.springbootjwedemo.dto.LoginRequestDTO;
import io.github.susimsek.springbootjwedemo.dto.TokenDTO;
import io.github.susimsek.springbootjwedemo.security.CookieUtils;
import io.github.susimsek.springbootjwedemo.security.JweUtil;
import lombok.RequiredArgsConstructor;
import org.springframework.http.HttpHeaders;
import org.springframework.http.ResponseCookie;
import org.springframework.http.ResponseEntity;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequiredArgsConstructor
@RequestMapping("/api/auth")
public class AuthController {

    private final AuthenticationManager authenticationManager;
    private final JweUtil jweUtil;

    @PostMapping("/login")
    public ResponseEntity<TokenDTO> login(@RequestBody LoginRequestDTO loginRequest) throws Exception {
        // Authenticate user
        var authToken = new UsernamePasswordAuthenticationToken(
            loginRequest.username(), loginRequest.password()
        );
        Authentication auth = authenticationManager.authenticate(authToken);
        SecurityContextHolder.getContext().setAuthentication(auth);

        // Generate JWE token and cookie
        TokenDTO tokenDto = jweUtil.generateToken(auth);
        ResponseCookie cookie = CookieUtils.createAccessTokenCookie(tokenDto);

        return ResponseEntity.ok()
            .header(HttpHeaders.SET_COOKIE, cookie.toString())
            .body(tokenDto);
    }
}

Kotlin

package io.github.susimsek.springbootjwedemo.controller

import io.github.susimsek.springbootjwedemo.dto.LoginRequestDTO
import io.github.susimsek.springbootjwedemo.dto.TokenDTO
import io.github.susimsek.springbootjwedemo.security.CookieUtils
import io.github.susimsek.springbootjwedemo.security.JweUtil
import lombok.RequiredArgsConstructor
import org.springframework.http.HttpHeaders
import org.springframework.http.ResponseCookie
import org.springframework.http.ResponseEntity
import org.springframework.security.authentication.AuthenticationManager
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken
import org.springframework.security.core.Authentication
import org.springframework.security.core.context.SecurityContextHolder
import org.springframework.web.bind.annotation.PostMapping
import org.springframework.web.bind.annotation.RequestBody
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController

@RestController
@RequiredArgsConstructor
@RequestMapping("/api/auth")
class AuthController(
    private val authenticationManager: AuthenticationManager,
    private val jweUtil: JweUtil
) {

    @PostMapping("/login")
    fun login(@RequestBody loginRequest: LoginRequestDTO): ResponseEntity<TokenDTO> {
        val authToken = UsernamePasswordAuthenticationToken(
            loginRequest.username, loginRequest.password
        )
        val auth: Authentication = authenticationManager.authenticate(authToken)
        SecurityContextHolder.getContext().authentication = auth

        val tokenDto: TokenDTO = jweUtil.generateToken(auth)
        val cookie: ResponseCookie = CookieUtils.createAccessTokenCookie(tokenDto)

        return ResponseEntity.ok()
            .header(HttpHeaders.SET_COOKIE, cookie.toString())
            .body(tokenDto)
    }
}

HelloController

Java

package io.github.susimsek.springbootjwedemo.controller;

import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.jwt.Jwt;
import org.springframework.web.bind.annotation.*;

import static io.github.susimsek.springbootjwedemo.security.SecurityUtils.AUTHORITIES_KEY;

@RestController
@RequestMapping("/api/hello")
public class HelloController {

    @GetMapping
    public String helloAll(@AuthenticationPrincipal Jwt jwt) {
        String user = jwt.getSubject();
        var roles = jwt.getClaimAsStringList(AUTHORITIES_KEY);
        return "Hello, " + user + "! Your roles: " + roles;
    }

    @GetMapping("/admin")
    public String helloAdmin(@AuthenticationPrincipal Jwt jwt) {
        return "Hello Admin, " + jwt.getSubject() + "!";
    }
}

Kotlin

package io.github.susimsek.springbootjwedemo.controller

import org.springframework.security.core.annotation.AuthenticationPrincipal
import org.springframework.security.oauth2.jwt.Jwt
import org.springframework.web.bind.annotation.*

import io.github.susimsek.springbootjwedemo.security.SecurityUtils.AUTHORITIES_KEY

@RestController
@RequestMapping("/api/hello")
class HelloController {

    @GetMapping
    fun helloAll(@AuthenticationPrincipal jwt: Jwt): String {
        val user = jwt.subject
        val roles = jwt.getClaimAsStringList(AUTHORITIES_KEY)
        return "Hello, \$user! Your roles: \$roles"
    }

    @GetMapping("/admin")
    fun helloAdmin(@AuthenticationPrincipal jwt: Jwt): String {
        return "Hello Admin, \${jwt.subject}!"
    }
}

LoginRequestDTO

Java

package io.github.susimsek.springbootjwedemo.dto;

public record LoginRequestDTO(
    String username,
    String password
) { }

Kotlin

package io.github.susimsek.springbootjwedemo.dto

data class LoginRequestDTO(
    val username: String,
    val password: String
)

TokenDTO

Java

package io.github.susimsek.springbootjwedemo.dto;

public record TokenDTO(
    String accessToken,
    String tokenType,
    long accessTokenExpiresIn
) {}

Kotlin

package io.github.susimsek.springbootjwedemo.dto

import kotlin.Long

data class TokenDTO(
    val accessToken: String,
    val tokenType: String,
    val accessTokenExpiresIn: Long
)

▶️ Run the App

./mvnw spring-boot:run
# or
gradle bootRun

🧪 Test Endpoints

In this section, we clarify Test Endpoints and summarize the key points you will apply in implementation.

Admin Flow

Login as admin and capture the JWE token from the Set-Cookie header:

curl -i -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"adminpass"}'

• Set-Cookie header contains accessToken=<jwe-token>
• Response body:

{
  "accessToken": "<jwe-token>",
  "tokenType": "Bearer",
  "accessTokenExpiresIn": 3600
}

Use cookie to access hello endpoint:

curl -b "accessToken=<jwe-token>" http://localhost:8080/api/hello

Use Authorization header instead:

curl -H "Authorization: Bearer <jwe-token>" http://localhost:8080/api/hello

Access admin-only endpoint:

curl -H "Authorization: Bearer <jwe-token>" http://localhost:8080/api/hello/admin

User Flow

Login as user and capture JWE token from cookie:

curl -i -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"user","password":"userpass"}'

• Set-Cookie header contains accessToken=<jwe-token>

Use cookie to access hello endpoint:

curl -b "accessToken=<jwe-token>" http://localhost:8080/api/hello

Use Authorization header:

curl -H "Authorization: Bearer <jwe-token>" http://localhost:8080/api/hello

Attempt admin endpoint (should be 403 Forbidden):

curl -H "Authorization: Bearer <jwe-token>" http://localhost:8080/api/hello/admin
# HTTP/1.1 403 Forbidden

🏁 Conclusion

You now have a practical Spring Boot JWE Authentication implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why HTTP Interface Client?

In this section, we clarify Why HTTP Interface Client? and summarize the key points you will apply in implementation.

• Declarative: Define an interface and annotate methods for HTTP calls.
• Type-safe: Compiler catches mismatched signatures or misconfigured paths.
• Minimal boilerplate: One bean definition, no manual proxy or template code.
• Spring-friendly: Leverages Spring Framework 6.2’s @HttpExchange, @GetExchange, and WebClientAdapter.

📋 Prerequisites

In this section, we clarify Prerequisites and summarize the key points you will apply in implementation.

• ☕ Java Development Kit (JDK) 21 or higher
• 📦 Spring Boot 3.2+
• 🔤 IDE (IntelliJ IDEA, Eclipse, etc.)

🛠️ Step 1: Add Dependencies

Add the Web starter to your build:

Maven:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-web</artifactId>
</dependency>

Gradle:

implementation 'org.springframework.boot:spring-boot-starter-web'

🛠️ Step 2: Configure Base URL

Add to application.yml or application.properties:

jsonplaceholder:
  base-url: https://jsonplaceholder.typicode.com

jsonplaceholder.base-url=https://jsonplaceholder.typicode.com

🛠️ Step 3: Define DTO and Client Interface

Java

// src/main/java/com/example/client/dto/PostDTO.java
package com.example.client.dto;

public record PostDTO(
    Integer userId,
    Integer id,
    String title,
    String body
) {}

// src/main/java/com/example/client/JsonPlaceholderClient.java
package com.example.client;

import com.example.client.dto.PostDTO;
import org.springframework.web.service.annotation.GetExchange;
import org.springframework.web.service.annotation.HttpExchange;
import org.springframework.web.bind.annotation.PathVariable;
import java.util.List;

@HttpExchange(url = "${jsonplaceholder.base-url}", accept = "application/json")
public interface JsonPlaceholderClient {

    @GetExchange("/posts")
    List<PostDTO> getPosts();

    @GetExchange("/posts/{id}")
    PostDTO getPost(@PathVariable("id") Integer id);
}

Kotlin

// src/main/kotlin/com/example/client/dto/PostDTO.kt
package com.example.client.dto

data class PostDTO(
    val userId: Int,
    val id: Int,
    val title: String,
    val body: String
)

// src/main/kotlin/com/example/client/JsonPlaceholderClient.kt
package com.example.client

import com.example.client.dto.PostDTO
import org.springframework.web.service.annotation.GetExchange
import org.springframework.web.service.annotation.HttpExchange
import org.springframework.web.bind.annotation.PathVariable

@HttpExchange(url = "${jsonplaceholder.base-url}", accept = "application/json")
interface JsonPlaceholderClient {

    @GetExchange("/posts")
    fun getPosts(): List<PostDTO>

    @GetExchange("/posts/{id}")
    fun getPost(@PathVariable("id") id: Int): PostDTO
}

🛠️ Step 4: Configure the Client Bean

Java

// src/main/java/com/example/config/HttpClientConfig.java
package com.example.config;

import com.example.client.JsonPlaceholderClient;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.client.support.RestClientAdapter;
import org.springframework.web.service.invoker.HttpServiceProxyFactory;
import org.springframework.web.service.invoker.RestClient;

@Configuration
public class HttpClientConfig {

    @Bean
    public JsonPlaceholderClient jsonPlaceholderClient(RestClient.Builder restClientBuilder) {
        RestClient restClient = restClientBuilder
            .baseUrl("https://jsonplaceholder.typicode.com")
            .build();

        var factory = HttpServiceProxyFactory
            .builderFor(RestClientAdapter.create(restClient))
            .build();

        return factory.createClient(JsonPlaceholderClient.class);
    }
}

Kotlin

// src/main/kotlin/com/example/config/HttpClientConfig.kt
package com.example.config

import com.example.client.JsonPlaceholderClient
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.web.client.support.RestClientAdapter
import org.springframework.web.service.invoker.HttpServiceProxyFactory
import org.springframework.web.service.invoker.RestClient

@Configuration
class HttpClientConfig {

    @Bean
    fun jsonPlaceholderClient(restClientBuilder: RestClient.Builder): JsonPlaceholderClient {
        val restClient = restClientBuilder
            .baseUrl("https://jsonplaceholder.typicode.com")
            .build()

        val factory = HttpServiceProxyFactory
            .builderFor(RestClientAdapter.create(restClient))
            .build()

        return factory.createClient(JsonPlaceholderClient::class.java)
    }
}

🛠️ Step 5: Implement Service and Controller

Java

// src/main/java/com/example/service/PostService.java
package com.example.service;

import com.example.client.JsonPlaceholderClient;
import com.example.client.dto.PostDTO;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;
import java.util.List;

@Service
@RequiredArgsConstructor
public class PostService {
    private final JsonPlaceholderClient client;

    public List<PostDTO> getAllPosts() {
        return client.getPosts();
    }

    public PostDTO getPostById(Integer id) {
        return client.getPost(id);
    }
}

// src/main/java/com/example/controller/PostController.java
package com.example.controller;

import com.example.client.dto.PostDTO;
import com.example.service.PostService;
import lombok.RequiredArgsConstructor;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import java.util.List;

@RestController
@RequestMapping("/posts")
@RequiredArgsConstructor
public class PostController {
    private final PostService postService;

    @GetMapping
    public List<PostDTO> getAllPosts() {
        return postService.getAllPosts();
    }

    @GetMapping("/{id}")
    public ResponseEntity<PostDTO> getPostById(@PathVariable Integer id) {
        PostDTO post = postService.getPostById(id);
        return post != null ? ResponseEntity.ok(post) : ResponseEntity.notFound().build();
    }
}

Kotlin

// src/main/kotlin/com/example/service/PostService.kt
package com.example.service

import com.example.client.JsonPlaceholderClient
import com.example.client.dto.PostDTO
import org.springframework.stereotype.Service

@Service
class PostService(private val client: JsonPlaceholderClient) {
    fun getAllPosts(): List<PostDTO> = client.getPosts()
    fun getPostById(id: Int): PostDTO = client.getPost(id)
}

// src/main/kotlin/com/example/controller/PostController.kt
package com.example.controller

import com.example.client.dto.PostDTO
import com.example.service.PostService
import org.springframework.http.ResponseEntity
import org.springframework.web.bind.annotation.*

@RestController
@RequestMapping("/posts")
class PostController(private val postService: PostService) {
    @GetMapping
    fun getAllPosts(): List<PostDTO> = postService.getAllPosts()

    @GetMapping("/{id}")
    fun getPostById(@PathVariable id: Int): ResponseEntity<PostDTO> =
        ResponseEntity.ok(postService.getPostById(id))
}

▶️ Run the Application

./mvnw spring-boot:run
# or
gradle bootRun

🧪 Test Endpoints

curl http://localhost:8080/posts
curl http://localhost:8080/posts/1

🏁 Conclusion

You now have a practical Spring Boot HTTP Interface Client implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why Use Virtual Thread in Spring Boot?

In this section, we clarify Why Use Virtual Thread in Spring Boot? and summarize the key points you will apply in implementation.

• Ultra-Lightweight: Virtual threads are thousands of times cheaper than platform threads.
• Non-Blocking: @Async methods run off the main thread, improving responsiveness.
• Scalable: Handle high concurrency with minimal resource overhead.
• Simple Config: Enable with a single property, no custom executors needed.

📋 Prerequisites

In this section, we clarify Prerequisites and summarize the key points you will apply in implementation.

• ☕ Java Development Kit (JDK) 21 or higher
• 📦 Spring Boot 3.2+
• 🔤 IDE (IntelliJ IDEA, Eclipse)

🛠️ Step 1: Add Dependencies

To enable async processing, include spring-boot-starter-web in your pom.xml or build.gradle file.

Maven:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

Gradle:

implementation 'org.springframework.boot:spring-boot-starter-web'

🛠️ Step 2: Enable Virtual Threads

Add to application.yml or application.properties:

spring:
  threads:
    virtual:
      enabled: true

spring.threads.virtual.enabled=true

This setting auto-configures the following:

• applicationTaskExecutor for @Async support
• Task scheduler for @Scheduled methods
• Servlet container thread pools (Tomcat/Jetty) to use virtual threads

🛠️ Step 3: Enable Async Support

Annotate your main application class in Java or Kotlin:

Java

package com.example.async;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.scheduling.annotation.EnableAsync;

@SpringBootApplication
@EnableAsync
public class AsyncVirtualApplication {
    public static void main(String[] args) {
        SpringApplication.run(AsyncVirtualApplication.class, args);
    }
}

Kotlin

package com.example.async

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.scheduling.annotation.EnableAsync

@SpringBootApplication
@EnableAsync
class AsyncVirtualApplication

fun main(args: Array<String>) {
    runApplication<AsyncVirtualApplication>(*args)
}

🛠️ Step 4: Define an Async Service

Create a service with @Async. It will run each call on a new virtual thread.

Java

package com.example.async;

import lombok.extern.slf4j.Slf4j;
import org.springframework.scheduling.annotation.Async;
import org.springframework.stereotype.Service;

import java.time.LocalTime;
import java.util.concurrent.CompletableFuture;

@Slf4j
@Service
public class AsyncVirtualService {

  @Async
  public void runTask() {
    log.info("[{}] Async start on {}", LocalTime.now(), Thread.currentThread());
    try {
      Thread.sleep(1000);
    } catch (InterruptedException ignored) {}
    log.info("[{}] Async end on {}", LocalTime.now(), Thread.currentThread());
  }

  @Async
  public CompletableFuture<String> runAndReturn() throws InterruptedException {
    Thread.sleep(500);
    return CompletableFuture.completedFuture("Completed");
  }
}

Kotlin

package com.example.async

import org.slf4j.LoggerFactory
import org.springframework.scheduling.annotation.Async
import org.springframework.stereotype.Service

import java.time.LocalTime
import java.util.concurrent.CompletableFuture

@Service
class AsyncVirtualService {
  private val log = LoggerFactory.getLogger(AsyncVirtualService::class.java)

  @Async
  fun runTask() {
    log.info("[{}] Async start on {}", LocalTime.now(), Thread.currentThread())
    try {
      Thread.sleep(1000)
    } catch (_: InterruptedException) {}
    log.info("[{}] Async end on {}", LocalTime.now(), Thread.currentThread())
  }

  @Async
  fun runAndReturn(): CompletableFuture<String> {
    Thread.sleep(500)
    return CompletableFuture.completedFuture("Completed")
  }
}

🛠️ Step 5: Trigger via REST Controller

Expose endpoints to invoke your async methods:

Java

package com.example.async;

import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/async")
@RequiredArgsConstructor
public class AsyncVirtualController {

  private final AsyncVirtualService service;

  @GetMapping("/run")
  public String triggerRun() {
    service.runTask();
    return "Async virtual thread task triggered";
  }

  @GetMapping("/run-return")
  public String triggerRunAndReturn() throws Exception {
    var future = service.runAndReturn();
    return future.get();
  }
}

Kotlin

package com.example.async

import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController

import lombok.RequiredArgsConstructor

@RestController
@RequestMapping("/async")
@RequiredArgsConstructor
class AsyncVirtualController(private val service: AsyncVirtualService) {

  @GetMapping("/run")
  fun triggerRun(): String {
    service.runTask()
    return "Async virtual thread task triggered"
  }

  @GetMapping("/run-return")
  @Throws(Exception::class)
  fun triggerRunAndReturn(): String {
    val future = service.runAndReturn()
    return future.get()
  }
}

▶️ Run the App

./mvnw spring-boot:run
# or
gradle bootRun

🧪 Test Endpoints

Trigger void task

curl http://localhost:8080/async/run

Check logs for virtual thread start/end.

Trigger task with return

curl http://localhost:8080/async/run-return
# returns "Completed"

🏁 Conclusion

You now have a practical Spring Boot Async Tasks with Virtual Thread implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why Use Spring AI?

In this section, we clarify Why Use Spring AI? and summarize the key points you will apply in implementation.

• Provider-agnostic portability: Write code once and switch between AI providers (OpenAI, Anthropic, Azure, etc.) without changes.
• POJO-based design: Model AI inputs and outputs as plain Java/Kotlin objects for type safety and easy integration.
• Structured outputs: Automatically map model responses to your domain objects.
• Vector store integration: Seamless support for major vector databases (Chroma, Pinecone, Redis, etc.) via a unified API.
• Tool/function calling: Enable LLMs to invoke custom functions or services for real-time data.
• Observability & evaluation: Built-in metrics and evaluation utilities to monitor AI operations and detect hallucinations.
• Chat abstractions: Fluent ChatClient API, similar to Spring’s WebClient, for building conversational agents.
• Retrieval-augmented generation (RAG): Simplify document-based QA and memory-backed chat with advisors and memory APIs.

📋 Prerequisites

Ensure you have the following:

• ☕ Java Development Kit (JDK) 17+
• 📦 Maven or Gradle installed
• 🐳 Spring Boot 3+
• 🔑 OpenAI API Key (set as environment variable OPENAI_API_KEY)

🛠️ Step 1: Add Dependencies

Include Spring AI starter for OpenAI, Spring Web, and Lombok.

Maven

<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
  </dependency>
  <dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <scope>provided</scope>
  </dependency>
</dependencies>

Gradle

plugins {
  id 'org.springframework.boot' version '3.2.0'
}

dependencies {
  implementation 'org.springframework.boot:spring-boot-starter-web'
  implementation 'org.springframework.ai:spring-ai-starter-model-openai'
  compileOnly 'org.projectlombok:lombok'
  annotationProcessor 'org.projectlombok:lombok'
}

🛠️ Step 2: Configuration

In application.yml, configure your OpenAI key and set the ChatClient model:

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        options:
          model: gpt-4.1-mini

🛠️ Step 3: Implement the Service Layer

Create an AIService to wrap your ChatClient. Inject ChatClient.Builder and build the client.

Java

package com.example.ai.service;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.stereotype.Service;
import lombok.RequiredArgsConstructor;

@Service
public class AIService {
    private final ChatClient chatClient;

    public AIService(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    public String getJoke(String topic) {
        return chatClient.prompt()
                .user(u -> u.text("Tell me a joke about {topic}").param("topic", topic))
                .call()
                .content();
    }
}

Kotlin

package com.example.ai.service

import org.springframework.ai.chat.client.ChatClient
import org.springframework.stereotype.Service

@Service
class AIService(builder: ChatClient.Builder) {
    private val chatClient: ChatClient = builder.build()

    fun getJoke(topic: String): String {
        return chatClient.prompt()
            .user { it.text("Tell me a joke about {topic}").param("topic", topic) }
            .call()
            .content()
    }
}

🛠️ Step 4: Expose a REST Controller

Create a ChatController to expose your AIService over HTTP.

Java

package com.example.ai.controller;

import com.example.ai.service.AIService;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import lombok.RequiredArgsConstructor;

@RestController
@RequiredArgsConstructor
public class ChatController {

    private final AIService aiService;

    @GetMapping("/joke")
    public String getJoke(@RequestParam(defaultValue = "dogs") String topic) {
        return aiService.getJoke(topic);
    }
}

Kotlin

package com.example.ai.controller

import com.example.ai.service.AIService
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.RequestParam
import org.springframework.web.bind.annotation.RestController

@RestController
class ChatController(private val aiService: AIService) {

    @GetMapping("/joke")
    fun getJoke(@RequestParam(defaultValue = "dogs") topic: String): String {
        return aiService.getJoke(topic)
    }
}

▶️ Running the Application

Start your Spring Boot app:

./mvnw spring-boot:run
# or
gradle bootRun

🧪 Testing the Integration

Call your service via HTTP:

curl -X GET "http://localhost:8080/joke?topic=dogs"
# Returns a dog joke generated by the AI model.

🏁 Conclusion

You now have a practical Spring Boot AI Integration implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why Use JPA Auditing?

In this section, we clarify Why Use JPA Auditing? and summarize the key points you will apply in implementation.

• 📅 Auto track createdDate, lastModifiedDate
• 👤 Record createdBy, modifiedBy
• 🧼 Cleaner code by avoiding manual field setting

📋 Prerequisites

Before you start, prepare the following:

• Java 17+
• Spring Boot 3.x project with Spring Data JPA
• A configured datasource (H2, PostgreSQL, MySQL, etc.)
• Basic familiarity with JPA entities and repository flow

🛠️ Step 1: Add Dependencies

Make sure you have the following dependencies in your project:

Maven:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>

Gradle:

dependencies {
  implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
}

🛠️ Step 2: Enable JPA Auditing

Add @EnableJpaAuditing to your main class or a configuration class.

Java

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.data.jpa.repository.config.EnableJpaAuditing;

@SpringBootApplication
@EnableJpaAuditing(auditorAwareRef = "auditorProvider")
public class DemoApplication {
  public static void main(String[] args) {
    SpringApplication.run(DemoApplication.class, args);
  }
}

Kotlin

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.data.jpa.repository.config.EnableJpaAuditing

@SpringBootApplication
@EnableJpaAuditing(auditorAwareRef = "auditorProvider")
class DemoApplication

fun main(args: Array<String>) {
    runApplication<DemoApplication>(*args)
}

🛠️ Step 3: Create AuditorAware Bean

This bean tells Spring Security who the current user is. Here's a basic static user example:

Java

@Configuration
public class AuditingConfig {

  @Bean
  public AuditorAware<String> auditorProvider() {
    return () -> Optional.of("Şuayb");
  }
}

Kotlin

@Configuration
class AuditingConfig {

  @Bean
  fun auditorProvider(): AuditorAware<String> = AuditorAware { Optional.of("Şuayb") }
}

🛠️ Step 4: Annotate Your Entity

Use auditing annotations like @CreatedDate, @LastModifiedDate, etc.

Java

@Entity
@EntityListeners(AuditingEntityListener.class)
public class Article {

  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  private Long id;

  private String title;

  @CreatedDate
  private LocalDateTime createdDate;

  @LastModifiedDate
  private LocalDateTime lastModifiedDate;

  @CreatedBy
  private String createdBy;

  @LastModifiedBy
  private String lastModifiedBy;

  // getters & setters
}

Kotlin

@Entity
@EntityListeners(AuditingEntityListener::class)
data class Article(
  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  val id: Long? = null,

  var title: String? = null,

  @CreatedDate
  var createdDate: LocalDateTime? = null,

  @LastModifiedDate
  var lastModifiedDate: LocalDateTime? = null,

  @CreatedBy
  var createdBy: String? = null,

  @LastModifiedBy
  var lastModifiedBy: String? = null
)

▶️ Running the Application

Now when you save an entity using JpaRepository, auditing fields will be populated automatically.

🧪 Testing

You can test JPA Auditing functionality by saving an entity and checking whether the audit fields are populated.

Java

@SpringBootTest
@AutoConfigureTestDatabase
@Transactional
class ArticleRepositoryTest {

  @Autowired
  private ArticleRepository articleRepository;

  @Test
  void testAuditFieldsAreSet() {
    Article article = new Article();
    article.setTitle("Test Title");

    Article saved = articleRepository.save(article);

    assertNotNull(saved.getCreatedDate());
    assertNotNull(saved.getLastModifiedDate());
    assertEquals("Şuayb", saved.getCreatedBy());
    assertEquals("Şuayb", saved.getLastModifiedBy());
  }
}

Kotlin

@SpringBootTest
@AutoConfigureTestDatabase
@Transactional
class ArticleRepositoryTest {

  @Autowired
  lateinit var articleRepository: ArticleRepository

  @Test
  fun `should set audit fields`() {
    val article = Article().apply {
      title = "Test Title"
    }

    val saved = articleRepository.save(article)

    assertNotNull(saved.createdDate)
    assertNotNull(saved.lastModifiedDate)
    assertEquals("Şuayb", saved.createdBy)
    assertEquals("Şuayb", saved.lastModifiedBy)
  }
}

🏁 Conclusion

You now have a practical Spring Boot JPA Auditing implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why Use TDD in Spring Boot?

In this section, we clarify Why Use TDD in Spring Boot? and summarize the key points you will apply in implementation.

• Fail Fast: Catch issues early during development.
• Clean Design: Forces modular, testable code structure.
• Refactor with Confidence: Tests serve as a safety net.
• Documentation: Tests describe intended behavior clearly.

📋 Prerequisites

Make sure you have:

• ☕ JDK 17+ installed
• 📦 Maven or Gradle
• 🔤 A Java IDE like IntelliJ IDEA or Eclipse

🧪 Step 1: Add Test Dependencies

Add Spring Boot's test starter to your project.

Maven:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-test</artifactId>
  <scope>test</scope>
</dependency>

Gradle:

testImplementation 'org.springframework.boot:spring-boot-starter-test'

🧪 Step 2: Write Your First Test

Create a simple unit test before implementing the service.

Java

package com.example.tdd;

import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;

class GreetingServiceTest {

    @Test
    void shouldReturnGreetingMessage() {
        GreetingService service = new GreetingService();
        String result = service.greet("World");
        assertEquals("Hello, World!", result);
    }
}

Kotlin

package com.example.tdd

import org.junit.jupiter.api.Assertions.assertEquals
import org.junit.jupiter.api.Test

class GreetingServiceTest {

    @Test
    fun shouldReturnGreetingMessage() {
        val service = GreetingService()
        val result = service.greet("World")
        assertEquals("Hello, World!", result)
    }
}

🛠️ Step 3: Implement the Service

Now implement the GreetingService to pass the test.

Java

package com.example.tdd;

public class GreetingService {
    public String greet(String name) {
        return "Hello, " + name + "!";
    }
}

Kotlin

package com.example.tdd

class GreetingService {
    fun greet(name: String): String {
        return "Hello, $name!"
    }
}

▶️ Running the Tests

Use your build tool to run the tests:

./mvnw test

Or with Gradle:

gradle test

You should see the test pass ✅

Refactor and Repeat

Now that your test passes, you can safely refactor your code. TDD is a loop:

1. Red – Write a failing test
2. Green – Make it pass
3. Refactor – Improve the code

🏁 Conclusion

You now have a practical Spring Boot Test-Driven Development implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why Use Circuit Breaker?

In this section, we clarify Why Use Circuit Breaker? and summarize the key points you will apply in implementation.

• Prevents cascading failures in microservices.
• Improves application resilience by stopping excessive failed requests.
• Automatically recovers when services become healthy again.
• Reduces latency by preventing unnecessary waits for failed services.
• Configurable retry strategies to manage failures efficiently.

📋 Prerequisites

Ensure you have the following:

• ☕ Java Development Kit (JDK) 17+
• 📦 Maven or Gradle installed
• 🌐 Spring Boot & Spring Cloud
• 🛠 A REST API to demonstrate Circuit Breaker behavior

🛠️ Step 1: Add Dependencies

In this section, we clarify Step 1: Add Dependencies and summarize the key points you will apply in implementation.

Maven:

<dependency>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-starter-circuitbreaker-resilience4j</artifactId>
</dependency>

Gradle:

implementation 'org.springframework.cloud:spring-cloud-starter-circuitbreaker-resilience4j'

🛠️ Step 2: Configure Circuit Breaker Properties

Define Circuit Breaker settings in application.yml.

resilience4j:
  circuitbreaker:
    instances:
      externalService:
        failure-rate-threshold: 50
        slow-call-rate-threshold: 50
        slow-call-duration-threshold: 2000ms
        permitted-number-of-calls-in-half-open-state: 3
        sliding-window-size: 10
        minimum-number-of-calls: 5
        wait-duration-in-open-state: 5s

🛠️ Step 3: Implement Circuit Breaker in a REST Service

In this section, we clarify Step 3: Implement Circuit Breaker in a REST Service and summarize the key points you will apply in implementation.

Create a Service to Call an External API

The following example gives practical context for Create a Service to Call an External API and can be applied directly.

Java

package com.example.circuitbreaker.service;

import io.github.resilience4j.circuitbreaker.annotation.CircuitBreaker;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestTemplate;

@Service
public class ExternalService {

    private final RestTemplate restTemplate = new RestTemplate();

    @CircuitBreaker(name = "externalService", fallbackMethod = "fallbackResponse")
    public String callExternalAPI() {
        return restTemplate.getForObject("http://unreliable-service/api/data", String.class);
    }

    public String fallbackResponse(Exception e) {
        return "Fallback response: Service is unavailable!";
    }
}

Kotlin

package com.example.circuitbreaker.service

import io.github.resilience4j.circuitbreaker.annotation.CircuitBreaker
import org.springframework.stereotype.Service
import org.springframework.web.client.RestTemplate

@Service
class ExternalService {
    private val restTemplate = RestTemplate()

    @CircuitBreaker(name = "externalService", fallbackMethod = "fallbackResponse")
    fun callExternalAPI(): String {
        return restTemplate.getForObject("http://unreliable-service/api/data", String::class.java) ?: ""
    }

    fun fallbackResponse(e: Exception): String {
        return "Fallback response: Service is unavailable!"
    }
}

🛠️ Step 4: Create a REST Controller

Java

package com.example.circuitbreaker.controller;

import com.example.circuitbreaker.service.ExternalService;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
public class CircuitBreakerController {

    private final ExternalService externalService;

    public CircuitBreakerController(ExternalService externalService) {
        this.externalService = externalService;
    }

    @GetMapping("/data")
    public String fetchData() {
        return externalService.callExternalAPI();
    }
}

Kotlin

package com.example.circuitbreaker.controller

import com.example.circuitbreaker.service.ExternalService
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController

@RestController
@RequestMapping("/api")
class CircuitBreakerController(private val externalService: ExternalService) {

    @GetMapping("/data")
    fun fetchData(): String {
        return externalService.callExternalAPI()
    }
}

▶️ Running the Application

Start the application:

./mvnw spring-boot:run

or using Gradle:

gradle bootRun

🧪 Test the Circuit Breaker

Test the Circuit Breaker:

curl -X GET http://localhost:8080/api/data

🏁 Conclusion

You now have a practical Spring Boot Circuit Breaker implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why Use Eureka Server?

In this section, we clarify Why Use Eureka Server? and summarize the key points you will apply in implementation.

• Service Discovery: Automatically register and discover microservices.
• Load Balancing: Enables client-side load balancing with Ribbon.
• Failover Support: Services can find alternative instances if one fails.
• Scalability: Easily scale microservices without manual configuration.
• Spring Cloud Integration: Works seamlessly with Spring Boot applications.

📋 Prerequisites

Ensure you have the following:

• ☕ Java Development Kit (JDK) 17+
• 📦 Maven or Gradle installed

🛠️ Step 1: Add Dependencies

In this section, we clarify Step 1: Add Dependencies and summarize the key points you will apply in implementation.

Maven:

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-netflix-eureka-server</artifactId>
</dependency>

Gradle:

implementation 'org.springframework.cloud:spring-cloud-starter-netflix-eureka-server'

🛠️ Step 2: Create the Eureka Server Application

Java

package com.example.eurekaserver;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.netflix.eureka.server.EnableEurekaServer;

@SpringBootApplication
@EnableEurekaServer
public class EurekaServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(EurekaServerApplication.class, args);
    }
}

Kotlin

package com.example.eurekaserver

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.cloud.netflix.eureka.server.EnableEurekaServer

@SpringBootApplication
@EnableEurekaServer
class EurekaServerApplication

fun main(args: Array<String>) {
    runApplication<EurekaServerApplication>(*args)
}

🛠️ Step 3: Configure the Eureka Server

Create an application.yml file for Eureka Server configuration.

server:
  port: 8761
spring:
  application:
    name: eureka-server
eureka:
  client:
    register-with-eureka: false
    fetch-registry: false
  server:
    wait-time-in-ms-when-sync-empty: 5

Note: The Eureka Server does not register itself.

▶️ Running the Eureka Server

Start the Eureka Server application:

./mvnw spring-boot:run

or using Gradle:

gradle bootRun

Access the Eureka Server dashboard:

http://localhost:8761/

🛠️ Step 4: Register a Client Application

In this section, we clarify Step 4: Register a Client Application and summarize the key points you will apply in implementation.

Add Dependencies

Add the Eureka Client starter first so this application can register with the server and participate in service discovery.

Maven:

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
</dependency>

Gradle:

implementation 'org.springframework.cloud:spring-cloud-starter-netflix-eureka-client'

Client Application Configuration

In the client's application.yml, add the following:

spring:
  application:
    name: eureka-client
eureka:
  client:
    service-url:
      defaultZone: http://localhost:8761/eureka/

Client Application Code

The sample below provides a minimal client implementation so you can validate the server integration end to end.

Java

package com.example.eurekaclient;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
@RestController
@RequestMapping("/client")
public class EurekaClientApplication {

    @GetMapping
    public String getClientMessage() {
        return "Hello from Eureka Client!";
    }

    public static void main(String[] args) {
        SpringApplication.run(EurekaClientApplication.class, args);
    }
}

Kotlin

package com.example.eurekaclient

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController

@SpringBootApplication
@RestController
@RequestMapping("/client")
class EurekaClientApplication {

    @GetMapping
    fun getClientMessage(): String {
        return "Hello from Eureka Client!"
    }
}

fun main(args: Array<String>) {
    runApplication<EurekaClientApplication>(*args)
}

▶️ Running the Client Application

Run the Eureka Client application:

./mvnw spring-boot:run

or using Gradle:

gradle bootRun

Check if the client has registered with Eureka Server by visiting:

http://localhost:8761/

🏁 Conclusion

You now have a practical Spring Boot Eureka Server implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why Use Config Server?

In this section, we clarify Why Use Config Server? and summarize the key points you will apply in implementation.

• Centralized Configuration: Manage application settings in a single place.
• Dynamic Updates: Update configurations without restarting services.
• Environment Profiles: Support different configurations for dev, test, and production environments.
• Security & Access Control: Store sensitive configurations securely.
• Integration with Git: Keep configuration versions managed and trackable.

📋 Prerequisites

Ensure you have the following:

• ☕ Java Development Kit (JDK) 17+
• 📦 Maven or Gradle installed
• 📁 Git Repository (for storing configurations)

🛠️ Step 1: Add Dependencies

Add the necessary dependencies for Spring Cloud Config Server.

Maven:

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-config-server</artifactId>
</dependency>

Gradle:

implementation 'org.springframework.cloud:spring-cloud-config-server'

🛠️ Step 2: Create the Config Server Application

Java

package com.example.configserver;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.config.server.EnableConfigServer;

@SpringBootApplication
@EnableConfigServer
public class ConfigServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(ConfigServerApplication.class, args);
    }
}

Kotlin

package com.example.configserver

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.cloud.config.server.EnableConfigServer

@SpringBootApplication
@EnableConfigServer
class ConfigServerApplication

fun main(args: Array<String>) {
    runApplication<ConfigServerApplication>(*args)
}

🛠️ Step 3: Configure the Config Server

Create an application.yml file to specify the Git repository for storing configurations.

server:
  port: 8888
spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/example/config-repo
          default-label: main

Note: Replace https://github.com/example/config-repo with your actual Git repository.

🛠️ Step 4: Create a Configuration Repository

In your Git repository (e.g., config-repo), create an application.yml file with the following content:

config.key: 'Hello from Config Server!'

Commit and push the file to the repository:

git add application.yml
git commit -m "Add config properties"
git push origin main

▶️ Running the Config Server

Start the Config Server application:

./mvnw spring-boot:run

or using Gradle:

gradle bootRun

Verify it is running by accessing:

curl -X GET http://localhost:8888/application/default

Expected Output:

{
  "name": "application",
  "profiles": ["default"],
  "propertySources": [
    {
      "name": "https://github.com/example/config-repo/application.yml",
      "source": {
        "config.key": "Hello from Config Server!"
      }
    }
  ]
}

🛠️ Step 5: Configure a Client Application

In this section, we clarify Step 5: Configure a Client Application and summarize the key points you will apply in implementation.

Add Dependencies

First, include the Config Client starter so this service can pull centralized configuration during bootstrap.

Maven:

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-config</artifactId>
</dependency>

Gradle:

implementation 'org.springframework.cloud:spring-cloud-starter-config'

Client Application Configuration

In the client's bootstrap.yml, add the following:

spring:
  application:
    name: config-client
  cloud:
    config:
      uri: http://localhost:8888

Client Application Code

The sample below provides a minimal client implementation so you can validate the server integration end to end.

Java

package com.example.configclient;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.beans.factory.annotation.Value;

@SpringBootApplication
@RestController
@RequestMapping("/config")
public class ConfigClientApplication {

  @Value("${config.key:not found}")
  private String configValue;

  @GetMapping
  public String getConfigValue() {
    return "Config Value: " + configValue;
  }

  public static void main(String[] args) {
    SpringApplication.run(ConfigClientApplication.class, args);
  }
}

Kotlin

package com.example.configclient

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController
import org.springframework.beans.factory.annotation.Value

@SpringBootApplication
@RestController
@RequestMapping("/config")
class ConfigClientApplication {

    @Value("\${config.key:not found}")
    lateinit var configValue: String

    @GetMapping
    fun getConfigValue(): String {
        return "Config Value: \$configValue"
    }
}

fun main(args: Array<String>) {
    runApplication<ConfigClientApplication>(*args)
}

▶️ Running the Client Application

Run the Config Client application:

./mvnw spring-boot:run

or using Gradle:

gradle bootRun

Retrieve the configuration from Config Server:

curl -X GET http://localhost:8080/config

Expected Output:

Config Value: Hello from Config Server!

🏁 Conclusion

You now have a practical Spring Boot Config Server implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why Use Docker for Spring Boot?

In this section, we clarify Why Use Docker for Spring Boot? and summarize the key points you will apply in implementation.

• Portable Deployment: Run applications consistently across environments.
• Scalability: Easily scale and manage containerized applications.
• Lightweight and Efficient: Optimize resource utilization with minimal overhead.
• DevOps Friendly: Seamlessly integrate with CI/CD pipelines.

📋 Prerequisites

Ensure you have the following:

• ☕ Java Development Kit (JDK) 17+
• 📦 Maven or Gradle installed
• 🐳 Docker installed and running

🛠️ Step 1: Add Dependencies

To enable Docker support, add the Spring Boot Maven Plugin, Jib Plugin, and Spring Boot Web Starter to your build tool.

Maven:

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
        <plugin>
            <groupId>com.google.cloud.tools</groupId>
            <artifactId>jib-maven-plugin</artifactId>
            <version>3.3.2</version>
        </plugin>
    </plugins>
</build>

Gradle:

plugins {
    id 'org.springframework.boot' version '3.2.0'
    id 'com.google.cloud.tools.jib' version '3.3.2'
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
}

To enable Docker support, add the Spring Boot Maven Plugin and Jib Plugin to your build tool.

Maven:

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
        <plugin>
            <groupId>com.google.cloud.tools</groupId>
            <artifactId>jib-maven-plugin</artifactId>
            <version>3.3.2</version>
        </plugin>
    </plugins>
</build>

Gradle:

plugins {
    id 'org.springframework.boot' version '3.2.0'
    id 'com.google.cloud.tools.jib' version '3.3.2'
}

🛠️ Step 2: Create a Simple Spring Boot Application

Define a REST endpoint to deploy inside a Docker container.

Java

package com.example.docker;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
@RestController
public class DockerApplication {

    public static void main(String[] args) {
        SpringApplication.run(DockerApplication.class, args);
    }

    @GetMapping("/hello")
    public String hello() {
        return "Hello from Spring Boot running in Docker!";
    }
}

Kotlin

package com.example.docker

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.RestController

@SpringBootApplication
@RestController
class DockerApplication {

    @GetMapping("/hello")
    fun hello(): String = "Hello from Spring Boot running in Docker!"
}

fun main(args: Array<String>) {
    runApplication<DockerApplication>(*args)
}

▶️ Step 3: Build and Run a Docker Image

In this section, we clarify Step 3: Build and Run a Docker Image and summarize the key points you will apply in implementation.

Option 1: Using Buildpacks

Spring Boot provides built-in support for creating Docker images without a Dockerfile using Buildpacks.

mvn spring-boot:build-image

gradle bootBuildImage

Run the container:

docker run --rm -p 8080:8080 myproject:0.0.1-SNAPSHOT

Option 2: Using Jib

Jib allows building optimized container images without a Docker daemon.

mvn jib:dockerBuild

gradle jibDockerBuild

Run the Jib-built container:

docker run --rm -p 8080:8080 myproject:0.0.1-SNAPSHOT

▶️ Running the Application

Once the container is running, test the REST API:

curl -X GET http://localhost:8080/hello

Expected Output:

Hello from Spring Boot running in Docker!

🏁 Conclusion

You now have a practical Spring Boot Docker Integration implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why Use Kubernetes for Spring Boot?

In this section, we clarify Why Use Kubernetes for Spring Boot? and summarize the key points you will apply in implementation.

• Scalability: Automatically scale applications based on traffic.
• Self-Healing: Kubernetes restarts failed containers automatically.
• Declarative Configuration: Manage infrastructure with YAML configurations.
• Load Balancing & Service Discovery: Built-in support for routing requests efficiently.
• Efficient Resource Utilization: Optimize CPU and memory usage dynamically.

📋 Prerequisites

Ensure you have the following:

• ☕ Java Development Kit (JDK) 17+
• 📦 Maven or Gradle installed
• 🛠 Docker installed and running
• 🌐 Kubernetes Cluster (Minikube or a cloud provider like AWS EKS, GKE, or AKS)
• 🛠 kubectl installed for managing Kubernetes

🛠️ Step 1: Add Dependencies

Add the necessary dependencies for Spring Boot Web and Actuator to expose health endpoints.

Maven:

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
</dependencies>

Gradle:

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
}

🛠️ Step 2: Create a Simple Spring Boot Application

Define a REST endpoint to deploy inside Kubernetes.

Java

package com.example.kubernetes;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
@RestController
public class KubernetesApplication {

    public static void main(String[] args) {
        SpringApplication.run(KubernetesApplication.class, args);
    }

    @GetMapping("/hello")
    public String hello() {
        return "Hello from Spring Boot running in Kubernetes!";
    }
}

Kotlin

package com.example.kubernetes

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.RestController

@SpringBootApplication
@RestController
class KubernetesApplication {

    @GetMapping("/hello")
    fun hello(): String = "Hello from Spring Boot running in Kubernetes!"
}

fun main(args: Array<String>) {
    runApplication<KubernetesApplication>(*args)
}

🛠️ Step 3: Create Kubernetes Deployment and Service

Create a deployment.yaml file:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: spring-boot-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: spring-boot-app
  template:
    metadata:
      labels:
        app: spring-boot-app
    spec:
      containers:
        - name: spring-boot-app
          image: myproject:0.0.1-SNAPSHOT
          ports:
            - containerPort: 8080

Create a service.yaml file:

apiVersion: v1
kind: Service
metadata:
  name: spring-boot-service
spec:
  type: LoadBalancer
  selector:
    app: spring-boot-app
  ports:
    - protocol: TCP
      port: 80
      targetPort: 8080

Apply the configurations:

kubectl apply -f deployment.yaml
kubectl apply -f service.yaml

▶️ Running the Application

Once deployed, retrieve the service URL:

kubectl get services

Test the endpoint:

curl -X GET http://your-service-ip/hello

Expected Output:

Hello from Spring Boot running in Kubernetes!

🏁 Conclusion

You now have a practical Spring Boot Kubernetes Integration implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why Use @Async in Spring Boot?

In this section, we clarify Why Use @Async in Spring Boot? and summarize the key points you will apply in implementation.

• Non-Blocking Execution: Runs tasks asynchronously without blocking the main thread.
• Improved Performance: Executes independent tasks in parallel.
• Better Scalability: Frees up resources for other processes.
• Seamless Integration: Works with Spring Boot’s dependency injection and lifecycle management.

📋 Prerequisites

Ensure you have the following:

• ☕ Java Development Kit (JDK) 17+
• 📦 Maven or Gradle installed
• 🔤 A Java IDE (e.g., IntelliJ IDEA, Eclipse)

🛠️ Step 1: Add Dependencies

To enable async processing, include spring-boot-starter-web in your pom.xml or build.gradle file.

Maven:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

Gradle:

implementation 'org.springframework.boot:spring-boot-starter-web'

🛠️ Step 2: Enable Async in Your Application

Annotate your main application class with @EnableAsync to enable asynchronous execution.

Java

package com.example.async;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.scheduling.annotation.EnableAsync;

@SpringBootApplication
@EnableAsync
public class AsyncApplication {
    public static void main(String[] args) {
        SpringApplication.run(AsyncApplication.class, args);
    }
}

Kotlin

package com.example.async

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.scheduling.annotation.EnableAsync

@SpringBootApplication
@EnableAsync
class AsyncApplication

fun main(args: Array<String>) {
    runApplication<AsyncApplication>(*args)
}

🛠️ Step 3: Create an Async Task

Define an asynchronous method using @Async.

Java

package com.example.async;

import org.springframework.scheduling.annotation.Async;
import org.springframework.stereotype.Service;
import java.time.LocalTime;

@Service
public class AsyncTask {

    @Async
    public void runTask() {
        System.out.println("Async task executed at: " + LocalTime.now());
    }
}

Kotlin

package com.example.async

import org.springframework.scheduling.annotation.Async
import org.springframework.stereotype.Service
import java.time.LocalTime

@Service
class AsyncTask {

    @Async
    fun runTask() {
        println("Async task executed at: ${LocalTime.now()}")
    }
}

🛠️ Step 4: Create a Controller to Trigger Async Tasks

Create a REST controller to trigger the asynchronous task.

Java

package com.example.async;

import org.springframework.web.bind.annotation.*;
import lombok.RequiredArgsConstructor;

@RestController
@RequestMapping("/async")
@RequiredArgsConstructor
public class AsyncController {

    private final AsyncTask asyncTask;

    @GetMapping("/run")
    public String triggerAsyncTask() {
        asyncTask.runTask();
        return "Async task triggered!";
    }
}

Kotlin

package com.example.async

import org.springframework.web.bind.annotation.*

@RestController
@RequestMapping("/async")
class AsyncController(
    private val asyncTask: AsyncTask
) {

    @GetMapping("/run")
    fun triggerAsyncTask(): String {
        asyncTask.runTask()
        return "Async task triggered!"
    }
}

▶️ Running the Application

Run the Spring Boot application:

./mvnw spring-boot:run

Or using Gradle:

gradle bootRun

🧪 Testing the Async Task

In this section, we clarify Testing the Async Task and summarize the key points you will apply in implementation.

Trigger Async Task:

Call this endpoint to trigger the async workflow and observe execution flow in logs.

curl -X GET http://localhost:8080/async/run

Expected Console Output:

Compare your console logs with this output to quickly confirm the behavior is correct.

Async task executed at: 12:00:01

🏁 Conclusion

You now have a practical Spring Boot Async Tasks implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why Use @Scheduled in Spring Boot?

In this section, we clarify Why Use @Scheduled in Spring Boot? and summarize the key points you will apply in implementation.

• Automate Tasks: Run jobs periodically without human interaction.
• Efficient Resource Usage: Schedule tasks without blocking main threads.
• Supports Fixed Rate, Fixed Delay, and Cron Expressions.
• Seamless Integration: Works with Spring Boot’s dependency injection and lifecycle management.

📋 Prerequisites

Ensure you have the following:

• ☕ Java Development Kit (JDK) 17+
• 📦 Maven or Gradle installed
• 🔤 A Java IDE (e.g., IntelliJ IDEA, Eclipse)

🛠️ Step 1: Add Dependencies

To enable scheduling, you need to include spring-boot-starter-web in your pom.xml or build.gradle file.

Maven:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

Gradle:

implementation 'org.springframework.boot:spring-boot-starter-web'

Why spring-boot-starter-web? Spring Boot applications using @Scheduled need a running Spring Context. Including spring-boot-starter-web ensures that the application lifecycle is properly managed.

🛠️ Step 2: Enable Scheduling in Your Application

To enable scheduling, annotate your main application class with @EnableScheduling.

Java

package com.example.scheduled;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.scheduling.annotation.EnableScheduling;

@SpringBootApplication
@EnableScheduling
public class ScheduledApplication {
    public static void main(String[] args) {
        SpringApplication.run(ScheduledApplication.class, args);
    }
}

Kotlin

package com.example.scheduled

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.scheduling.annotation.EnableScheduling

@SpringBootApplication
@EnableScheduling
class ScheduledApplication

fun main(args: Array<String>) {
    runApplication<ScheduledApplication>(*args)
}

🛠️ Step 3: Create a Scheduled Task

Define a scheduled task using @Scheduled.

Java

package com.example.scheduled;

import org.springframework.scheduling.annotation.Scheduled;
import org.springframework.stereotype.Service;
import java.time.LocalTime;

@Service
public class ScheduledTask {

    @Scheduled(fixedRate = 5000)
    public void runTask() {
        System.out.println("Scheduled task executed at: " + LocalTime.now());
    }
}

Kotlin

package com.example.scheduled

import org.springframework.scheduling.annotation.Scheduled
import org.springframework.stereotype.Service
import java.time.LocalTime

@Service
class ScheduledTask {

    @Scheduled(fixedRate = 5000)
    fun runTask() {
        println("Scheduled task executed at: ${LocalTime.now()}")
    }
}

▶️ Running the Application

Run the Spring Boot application:

./mvnw spring-boot:run

Or using Gradle:

gradle bootRun

The scheduled task will execute every 5 seconds and print a timestamp.

🧪 Testing the Scheduled Task

In this section, we clarify Testing the Scheduled Task and summarize the key points you will apply in implementation.

Expected Console Output:

Compare your console logs with this output to quickly confirm the behavior is correct.

Scheduled task executed at: 12:00:01
Scheduled task executed at: 12:00:06
Scheduled task executed at: 12:00:11

🏁 Conclusion

You now have a practical Spring Boot Scheduled Tasks implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why Use Reactive Programming?

In this section, we clarify Why Use Reactive Programming? and summarize the key points you will apply in implementation.

• Asynchronous & Non-Blocking: Handle multiple requests efficiently without blocking threads.
• Better Scalability: Utilize fewer resources while handling more concurrent users.
• Event-Driven Model: Ideal for microservices, real-time applications, and streaming data.
• Built-in Backpressure: Prevents overwhelming the system with too many requests.

📋 Prerequisites

Ensure you have the following:

• ☕ Java Development Kit (JDK) 17+
• 📦 Maven or Gradle installed
• 🔤 A Java IDE (e.g., IntelliJ IDEA, Eclipse)

🛠️ Step 1: Add Dependencies

Add the necessary dependency for Spring WebFlux in your pom.xml or build.gradle file.

Maven:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
</dependency>

Gradle:

implementation 'org.springframework.boot:spring-boot-starter-webflux'

🛠️ Step 2: Create a Reactive REST Controller

Define a non-blocking REST endpoint using Mono and Flux to handle asynchronous processing.

Java

package com.example.reactive;

import org.springframework.web.bind.annotation.*;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

import java.time.Duration;
import java.util.List;

@RestController
@RequestMapping("/reactive")
public class ReactiveController {

    @GetMapping("/mono")
    public Mono<String> getMono() {
        return Mono.just("Hello from Reactive Mono!");
    }

    @GetMapping("/flux")
    public Flux<String> getFlux() {
        return Flux.fromIterable(List.of("Hello", "from", "Reactive", "Flux"))
                   .delayElements(Duration.ofSeconds(1));
    }
}

Kotlin

package com.example.reactive

import org.springframework.web.bind.annotation.*
import reactor.core.publisher.Flux
import reactor.core.publisher.Mono
import java.time.Duration

@RestController
@RequestMapping("/reactive")
class ReactiveController {

    @GetMapping("/mono")
    fun getMono(): Mono<String> {
        return Mono.just("Hello from Reactive Mono!")
    }

    @GetMapping("/flux")
    fun getFlux(): Flux<String> {
        return Flux.just("Hello", "from", "Reactive", "Flux")
            .delayElements(Duration.ofSeconds(1))
    }
}

▶️ Running the Application

Run the Spring Boot application:

./mvnw spring-boot:run

Or using Gradle:

gradle bootRun

🧪 Testing the API

In this section, we clarify Testing the API and summarize the key points you will apply in implementation.

Test Mono Endpoint:

Run this check to validate endpoint behavior and confirm the response matches expectations.

curl -X GET http://localhost:8080/reactive/mono

Expected output:

Hello from Reactive Mono!

Test Flux Endpoint:

Run this check to validate endpoint behavior and confirm the response matches expectations.

curl -X GET http://localhost:8080/reactive/flux

Expected output (delayed by 1 second per word):

Hello
from
Reactive
Flux

🏁 Conclusion

You now have a practical Spring Boot Reactive Programming implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why Build a Native Application with GraalVM?

In this section, we clarify Why Build a Native Application with GraalVM? and summarize the key points you will apply in implementation.

• Faster Startup Times: Native images start much faster compared to JVM-based applications.
• Reduced Resource Usage: Native images consume less memory, making them ideal for cloud and containerized environments.
• Enhanced Security: Smaller runtime and reduced attack surface.

📋 Prerequisites

Ensure you have the following:

• ☕ Java Development Kit (JDK) 17+
• 🛠 GraalVM installed with native-image support
• 🕝 Maven or Gradle
• 🐳 Docker for building container images (optional)

🛠️ Step 1: Add Dependencies

Add the GraalVM Native Build Tools plugin to your pom.xml or build.gradle file.

Maven:

<plugin>
    <groupId>org.graalvm.buildtools</groupId>
    <artifactId>native-maven-plugin</artifactId>
    <version>0.9.20</version>
</plugin>

Gradle:

plugins {
    id 'org.graalvm.buildtools.native' version '0.9.20'
}

🛠️ Step 2: Write a REST Controller

Create a simple REST endpoint to test the native image functionality.

Java

package com.example.graalvmnative;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
@RestController
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }

    @GetMapping("/greeting")
    public String greeting() {
        return "Hello from GraalVM Native!";
    }
}

Kotlin

package com.example.graalvmnative

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.RestController

@SpringBootApplication
@RestController
class MyApplication {

    @GetMapping("/greeting")
    fun greeting(): String = "Hello from GraalVM Native!"
}

fun main(args: Array<String>) {
    runApplication<MyApplication>(*args)
}

🛠️ Step 3: Build a Native Image

In this section, we clarify Step 3: Build a Native Image and summarize the key points you will apply in implementation.

Maven: Run the following command to create a native image:

mvn -Pnative package

Gradle: Run the following command:

gradle nativeCompile

🛠️ Step 4: Build a Docker Image

Spring Boot provides built-in support for creating Docker images with native executables.

Maven:

mvn -Pnative spring-boot:build-image

Gradle:

gradle bootBuildImage

The Docker image will be available locally and can be run using:

docker run --rm -p 8080:8080 myproject:0.0.1-SNAPSHOT

▶️ Running the Application

In this section, we clarify Running the Application and summarize the key points you will apply in implementation.

Running Locally

You can run the native image directly:

./target/myproject

Running in Docker

If you built the Docker image, run it using:

docker run --rm -p 8080:8080 myproject:0.0.1-SNAPSHOT

🧪 Testing the API

Test the REST endpoint using cURL or Postman:

curl -X GET http://localhost:8080/greeting

Expected output:

Hello from GraalVM Native!

🏁 Conclusion

You now have a practical Spring Boot GraalVM Native Application implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why Use Kafka?

In this section, we clarify Why Use Kafka? and summarize the key points you will apply in implementation.

• Scalable Messaging: Handle large volumes of data seamlessly.
• Fault Tolerance: Ensure data durability and high availability.
• Real-Time Processing: Process and analyze data in real time.
• Integration: Easily integrate Kafka with Spring Boot for efficient development.

📋 Prerequisites

🕊 Ensure you have the following:

• ☕ Java Development Kit (JDK) 17+
• 📦 Maven or Gradle installed
• 🔠 A Java IDE (e.g., IntelliJ IDEA, Eclipse)
• 🔠 Apache Kafka installed and running

🛠️ Step 1: Add Dependencies

To integrate Kafka into your Spring Boot project, add the following dependencies:

• Maven:

<dependency>
  <groupId>org.springframework.kafka</groupId>
  <artifactId>spring-kafka</artifactId>
</dependency>

• Gradle:

implementation 'org.springframework.kafka:spring-kafka'

🛠️ Step 2: Configure Kafka

Set up Kafka connection in your application.properties or application.yml file:

spring.kafka.bootstrap-servers=localhost:9092
spring.kafka.consumer.group-id=my-group
spring.kafka.consumer.auto-offset-reset=earliest
spring.kafka.producer.key-serializer=org.apache.kafka.common.serialization.StringSerializer
spring.kafka.producer.value-serializer=org.springframework.kafka.support.serializer.JsonSerializer
spring.kafka.consumer.value-deserializer=org.springframework.kafka.support.serializer.JsonDeserializer
spring.kafka.consumer.properties.spring.json.trusted.packages=*

🛠️ Step 3: Create a Model for JSON Messages

In this section, we clarify Step 3: Create a Model for JSON Messages and summarize the key points you will apply in implementation.

Model Class

This model defines the message contract shared across producer, consumer, and controller layers.

Java

package com.example.kafka.model;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@NoArgsConstructor
@AllArgsConstructor
public class Message {
    private String id;
    private String content;
}

Kotlin

package com.example.kafka.model

data class Message(
    val id: String,
    val content: String
)

🛠️ Step 4: Implement Kafka Producer and Consumer

In this section, we clarify Step 4: Implement Kafka Producer and Consumer and summarize the key points you will apply in implementation.

Producer Example

This producer example shows how to publish messages consistently to the target topic.

Java

package com.example.kafka.producer;

import com.example.kafka.model.Message;
import lombok.RequiredArgsConstructor;
import org.springframework.kafka.core.KafkaTemplate;
import org.springframework.stereotype.Service;

@Service
@RequiredArgsConstructor
public class KafkaProducer {

    private final KafkaTemplate<String, Message> kafkaTemplate;

    public void sendMessage(String topic, Message message) {
        kafkaTemplate.send(topic, message);
    }
}

Kotlin

package com.example.kafka.producer

import com.example.kafka.model.Message
import org.springframework.kafka.core.KafkaTemplate
import org.springframework.stereotype.Service

@Service
class KafkaProducer(private val kafkaTemplate: KafkaTemplate<String, Message>) {

    fun sendMessage(topic: String, message: Message) {
        kafkaTemplate.send(topic, message)
    }
}

Consumer Example

This consumer example demonstrates how incoming messages are read and processed.

Java

package com.example.kafka.consumer;

import com.example.kafka.model.Message;
import org.springframework.kafka.annotation.KafkaListener;
import org.springframework.stereotype.Service;

@Service
public class KafkaConsumer {

    @KafkaListener(topics = "my-topic", groupId = "my-group")
    public void consumeMessage(Message message) {
        System.out.println("Received message: " + message);
    }
}

Kotlin

package com.example.kafka.consumer

import com.example.kafka.model.Message
import org.springframework.kafka.annotation.KafkaListener
import org.springframework.stereotype.Service

@Service
class KafkaConsumer {

    @KafkaListener(topics = ["my-topic"], groupId = "my-group")
    fun consumeMessage(message: Message) {
        println("Received message: $message")
    }
}

Controller Example

This controller exposes a simple endpoint so you can trigger and verify messaging behavior.

Java

package com.example.kafka.controller;

import com.example.kafka.model.Message;
import com.example.kafka.producer.KafkaProducer;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/kafka")
@RequiredArgsConstructor
public class KafkaController {

    private final KafkaProducer kafkaProducer;

    @PostMapping("/publish")
    public String publishMessage(@RequestParam String topic, @RequestBody Message message) {
        kafkaProducer.sendMessage(topic, message);
        return "Message sent to topic: " + topic;
    }
}

Kotlin

package com.example.kafka.controller

import com.example.kafka.model.Message
import com.example.kafka.producer.KafkaProducer
import org.springframework.web.bind.annotation.*

@RestController
@RequestMapping("/kafka")
class KafkaController(private val kafkaProducer: KafkaProducer) {

    @PostMapping("/publish")
    fun publishMessage(@RequestParam topic: String, @RequestBody message: Message): String {
        kafkaProducer.sendMessage(topic, message)
        return "Message sent to topic: $topic"
    }
}

▶️ Running the Application

Run the application using the following command:

./mvnw spring-boot:run

🧪 Testing the API

You can test the Kafka Producer endpoint using cURL or Postman:

curl -X POST "http://localhost:8080/kafka/publish" \
-H "Content-Type: application/json" \
-d '{"id": "123", "content": "Hello Kafka!"}'

🏁 Conclusion

You now have a practical Spring Boot Kafka Integration implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why Use Redis?

In this section, we clarify Why Use Redis? and summarize the key points you will apply in implementation.

• High Performance: Redis provides extremely low latency for read and write operations.
• Versatile Data Structures: Supports strings, hashes, lists, sets, and more.
• Scalability: Ideal for distributed caching and real-time analytics.
• Integration: Easily integrates with Spring Boot for seamless development.

📋 Prerequisites

🗈 Ensure you have the following:

• ☕ Java Development Kit (JDK) 17+
• 📦 Maven or Gradle installed
• 🔤 A Java IDE (e.g., IntelliJ IDEA, Eclipse)
• 💠 Redis Server installed and running locally or accessible via a network

🛠️ Step 1: Add Dependencies

To integrate Redis into your Spring Boot project, add the following dependencies:

• Maven:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>

• Gradle:

implementation 'org.springframework.boot:spring-boot-starter-data-redis'

🛠️ Step 2: Configure Redis

Set up the Redis connection in your application.properties or application.yml file.

Example Configuration:

Use this configuration as a baseline and adjust values for your local or production environment.

spring.redis.host=localhost
spring.redis.port=6379

For advanced setups, such as password authentication or SSL, add these properties:

spring.redis.password=yourpassword
spring.redis.ssl=true

🛠️ Step 3: Enable Caching

Add the @EnableCaching annotation to your main application class to enable Spring's caching abstraction.

Java

package com.example.redis;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cache.annotation.EnableCaching;

@SpringBootApplication
@EnableCaching
public class RedisApplication {
  public static void main(String[] args) {
    SpringApplication.run(RedisApplication.class, args);
  }
}

Kotlin

package com.example.redis

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.cache.annotation.EnableCaching

@SpringBootApplication
@EnableCaching
class RedisApplication

fun main(args: Array<String>) {
  runApplication<RedisApplication>(*args)
}

🛠️ Step 4: Service Layer Example with Caching

Java

package com.example.redis.service;

import org.springframework.cache.annotation.Cacheable;
import org.springframework.stereotype.Service;

@Service
public class UserService {

  @Cacheable("users")
  public String getUserById(String id) {
    simulateSlowService();
    return "User with ID: " + id;
  }

  private void simulateSlowService() {
    try {
      Thread.sleep(3000L);
    } catch (InterruptedException e) {
      throw new IllegalStateException(e);
    }
  }
}

Kotlin

package com.example.redis.service

import org.springframework.cache.annotation.Cacheable
import org.springframework.stereotype.Service

@Service
class UserService {

  @Cacheable("users")
  fun getUserById(id: String): String {
    simulateSlowService()
    return "User with ID: $id"
  }

  private fun simulateSlowService() {
    Thread.sleep(3000L)
  }
}

Configuring TTL (Time-To-Live)

Set the cache expiration time in your application.properties file:

spring.cache.redis.time-to-live=600000

This sets the TTL to 10 minutes (600,000 milliseconds).

Controller Example

Create a REST controller to expose the caching functionality.

Java

package com.example.redis.controller;

import com.example.redis.service.UserService;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/users")
@RequiredArgsConstructor
public class UserController {

  private final UserService userService;

  @GetMapping("/{id}")
  public String getUser(@PathVariable String id) {
    return userService.getUserById(id);
  }
}

Kotlin

package com.example.redis.controller

import com.example.redis.service.UserService
import org.springframework.web.bind.annotation.*

@RestController
@RequestMapping("/users")
class UserController(
  private val userService: UserService
) {
  @GetMapping("/{id}")
  fun getUser(@PathVariable id: String): String = userService.getUserById(id)
}

▶️ Running the Application

Run the application using the following command:

./mvnw spring-boot:run

🧪 Testing the API

You can test the API using cURL or Postman:

• Fetch a User (cached):

curl -X GET http://localhost:8080/users/1

🏁 Conclusion

You now have a practical Spring Boot Redis Caching implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why Use OpenAPI?

In this section, we clarify Why Use OpenAPI? and summarize the key points you will apply in implementation.

• Interactive Documentation: Offers a user-friendly interface for exploring APIs.
• Standardized Format: Generates machine-readable API definitions.
• Ease of Testing: Provides built-in tools for testing endpoints.
• Client Code Generation: Allows automatic generation of client code for various programming languages.

📋 Prerequisites

📋 Ensure you have the following:

• ☕ Java Development Kit (JDK) 17+
• 📦 Maven or Gradle installed
• 🔤 A Java IDE (e.g., IntelliJ IDEA, Eclipse)

🛠️ Step 1: Add Dependencies

To integrate OpenAPI using SpringDoc, add the following dependency to your Spring Boot project:

• Maven:

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.1.0</version>
</dependency>

• Gradle:

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0'

🛠️ Step 2: Configure OpenAPI

SpringDoc requires minimal configuration. You can customize your OpenAPI documentation using the application.properties or application.yml file.

Example Configuration:

Use this configuration as a baseline and adjust values for your local or production environment.

springdoc.api-docs.path=/api-docs
springdoc.swagger-ui.path=/swagger-ui.html

🛠️ Step 3: Annotate Your REST Controllers

Add annotations to your REST controllers and models to generate OpenAPI documentation automatically.

Java

Controller Example

package com.example.openapi.controller;

import com.example.openapi.model.User;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/users")
public class UserController {

  @Operation(summary = "Get all users", description = "Retrieve a list of users")
  @ApiResponse(responseCode = "200", description = "Successful operation",
    content = @Content(mediaType = "application/json"))
  @GetMapping
  public List<User> getAllUsers() {
    return List.of(new User(1L, "John Doe", "john@example.com"));
  }

  @Operation(summary = "Create a new user", description = "Add a new user to the system")
  @ApiResponse(responseCode = "201", description = "User created successfully",
    content = @Content(mediaType = "application/json"))
  @PostMapping
  public User createUser(@RequestBody User user) {
    return user;
  }
}

User Model

package com.example.openapi.model;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@NoArgsConstructor
@AllArgsConstructor
public class User {

    private Long id;
    private String name;
    private String email;
}

Kotlin

Controller Example

package com.example.openapi.controller

import com.example.openapi.model.User
import io.swagger.v3.oas.annotations.*
import io.swagger.v3.oas.annotations.responses.*
import io.swagger.v3.oas.annotations.media.*
import org.springframework.web.bind.annotation.*

@RestController
@RequestMapping("/users")
class UserController {

    @Operation(summary = "Get all users", description = "Retrieve a list of users")
    @ApiResponse(responseCode = "200", description = "Successful operation",
                 content = [Content(mediaType = "application/json")])
    @GetMapping
    fun getAllUsers(): List<User> = listOf(User(1L, "John Doe", "john@example.com"))

    @Operation(summary = "Create a new user", description = "Add a new user to the system")
    @ApiResponse(responseCode = "201", description = "User created successfully",
                 content = [Content(mediaType = "application/json")])
    @PostMapping
    fun createUser(@RequestBody user: User): User = user
}

User Model

package com.example.openapi.model

data class User(
  val id: Long,
  val name: String,
  val email: String
)

▶️ Running the Application

Run the application using the following command:

./mvnw spring-boot:run

Access the OpenAPI documentation at:

• API Docs: http://localhost:8080/api-docs
• Swagger UI: http://localhost:8080/swagger-ui.html

🧪 Testing the API

You can test the generated API documentation by exploring the Swagger UI interface:

1. Navigate to http://localhost:8080/swagger-ui.html in your browser.
2. Test endpoints interactively by providing inputs and observing responses.

🏁 Conclusion

You now have a practical Spring Boot with OpenAPI implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why Focus on Clean Coding?

Adopting clean coding principles helps to:

• Improve code readability and maintainability.
• Reduce technical debt.
• Make onboarding new developers easier.
• Enhance scalability and debugging processes.

📋 Prerequisites

📋 Ensure you have the following:

• ☕ Java Development Kit (JDK) 17+
• 📦 Maven or Gradle installed
• 🔤 A Java IDE (e.g., IntelliJ IDEA, Eclipse)
• 🛠️ Familiarity with Spring Boot basics

🛠️ Step 1: Structure Your Project

Organize your Spring Boot project for better clarity:

• Controller Layer: Handles incoming HTTP requests.
• Service Layer: Contains business logic.
• Repository Layer: Interacts with the database.

Example Folder Structure:

This structure keeps layers separated and makes future refactoring safer as the project grows.

src/main/java/com/example/cleanproject
├── controller
├── service
├── repository
├── entity
└── dto

🛠️ Step 2: Use Lombok for Cleaner Java Code

Lombok reduces boilerplate code in Java, making your classes more concise and readable. Here's how to use Lombok effectively:

Add Lombok Dependency

Start by adding Lombok to your build so annotations are resolved correctly before refactoring your entities and DTOs.

• Maven:

<dependency>
  <groupId>org.projectlombok</groupId>
  <artifactId>lombok</artifactId>
  <scope>provided</scope>
</dependency>

• Gradle:

provided 'org.projectlombok:lombok'
annotationProcessor 'org.projectlombok:lombok'

Example: Entity with Lombok

The following example gives practical context for Example: Entity with Lombok and can be applied directly.

package com.example.cleanproject.entity;

import jakarta.persistence.*;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.AllArgsConstructor;

@Data
@NoArgsConstructor
@AllArgsConstructor
@Entity
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;

    private String email;
}

Benefits:

• @Data generates getters, setters, equals, hashCode, and toString methods.
• @NoArgsConstructor and @AllArgsConstructor create constructors.

🛠️ Step 3: Write Concise and Readable Code in Kotlin

Kotlin offers modern features that naturally lead to cleaner code:

Example: Entity in Kotlin

The following example gives practical context for Example: Entity in Kotlin and can be applied directly.

package com.example.cleanproject.entity

import jakarta.persistence.*

@Entity
data class User(
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    val id: Long = 0,
    var name: String,
    var email: String
)

Advantages of Kotlin:

• data class automatically generates toString, equals, and hashCode methods.
• Immutable properties (val) ensure better stability.

🛠️ Step 4: Follow Dependency Injection Principles

Use dependency injection to decouple components and improve testability.

Example: Service Layer with DI

The following example gives practical context for Example: Service Layer with DI and can be applied directly.

Java

package com.example.cleanproject.service;

import com.example.cleanproject.entity.User;
import com.example.cleanproject.repository.UserRepository;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;

import java.util.List;

@Service
@RequiredArgsConstructor
public class UserService {

    private final UserRepository userRepository;

    public List<User> getAllUsers() {
        return userRepository.findAll();
    }
}

Kotlin

package com.example.cleanproject.service

import com.example.cleanproject.entity.User
import com.example.cleanproject.repository.UserRepository
import org.springframework.stereotype.Service

@Service
class UserService(
    private val userRepository: UserRepository
) {
    fun getAllUsers(): List<User> = userRepository.findAll()
}

🛠️ Step 5: Use DTOs for Data Transfer

Data Transfer Objects (DTOs) separate your domain and API layers, promoting better encapsulation.

Example: DTO for User

The following example gives practical context for Example: DTO for User and can be applied directly.

Java

package com.example.cleanproject.dto;

import lombok.Data;

@Data
public class UserDTO {
    private String name;
    private String email;
}

Kotlin

package com.example.cleanproject.dto

data class UserDTO(
    val name: String,
    val email: String
)

Controller Layer

Implement a controller to handle HTTP requests and interact with the service layer.

Java

package com.example.cleanproject.controller;

import com.example.cleanproject.dto.UserDTO;
import com.example.cleanproject.service.UserService;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/api/users")
@RequiredArgsConstructor
public class UserController {

    private final UserService userService;

    @GetMapping
    public List<UserDTO> getAllUsers() {
        return userService.getAllUsers();
    }
}

Kotlin

package com.example.cleanproject.controller

import com.example.cleanproject.dto.UserDTO
import com.example.cleanproject.service.UserService
import org.springframework.web.bind.annotation.*

@RestController
@RequestMapping("/api/users")
class UserController(
    private val userService: UserService
) {

    @GetMapping
    fun getAllUsers(): List<UserDTO> = userService.getAllUsers()
}

▶️ Running the Application

Run the application using the following command:

./mvnw spring-boot:run

Test endpoints using a tool like Postman or cURL.

🧪 Testing the API

You can test the API using the following cURL command:

• Fetch all users:

curl -X GET http://localhost:8080/api/users

🏁 Conclusion

You now have a practical Clean Coding Practices in Spring Boot implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why Use Spring Boot DevTools?

Spring Boot DevTools provides features such as:

• Live Reload: Automatically reloads the application on code changes.
• Enhanced Caching: Disables template caching for faster iteration.
• Debugging Tools: Improves development-time debugging experience.

📋 Prerequisites

📋 Ensure you have the following:

• ☕ Java Development Kit (JDK) 17+
• 📦 Maven or Gradle installed
• 🔤 A Java IDE (e.g., IntelliJ IDEA, Eclipse)

🛠️ Step 1: Add Dependencies

To enable DevTools, add the following dependency to your Spring Boot project:

• Maven:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-devtools</artifactId>
  <scope>runtime</scope>
</dependency>

• Gradle:

runtimeOnly 'org.springframework.boot:spring-boot-devtools'

🛠️ Step 2: Configure DevTools

Spring Boot DevTools requires minimal configuration but offers some customization options. Here are some common configurations:

Enable Live Reload

Live reload is enabled by default when using DevTools with supported IDEs like IntelliJ IDEA or Eclipse.

Disable Caching

Disable caching for templates to see changes instantly:

spring.thymeleaf.cache=false
spring.freemarker.cache=false

Restart Exclusions

Exclude specific files or directories from triggering a restart:

spring.devtools.restart.exclude=static/**,public/**

🛠️ Step 3: Debugging Enhancements

Spring Boot DevTools improves debugging by:

• Automatic Restart: Restarts the application context when code changes are detected.
• Remote Debugging: Provides the ability to debug applications running on remote servers.

To enable remote debugging:

spring.devtools.remote.secret=mysecretkey

Use the following command to connect:

java -jar myapp.jar -Dspring.devtools.remote.secret=mysecretkey

▶️ Running the Application

Run the application using the following command:

./mvnw spring-boot:run

Make changes to your code, and observe live reload and application context restarts.

🧪 Test DevTools

You can test Spring Boot DevTools features as follows:

• Live Reload: Make a change in your controller or template and save the file. The application should reload automatically.
• Template Updates: Update a .html file and verify the changes without restarting the server.
• Debugging: Add breakpoints in your IDE and test remote debugging with DevTools enabled.

🏁 Conclusion

You now have a practical Spring Boot DevTools implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why Use Spring Boot Actuator?

Spring Boot Actuator allows developers to:

• Monitor application health
• Gather metrics and information
• Expose management endpoints for operational tasks

📋 Prerequisites

📋 Ensure you have the following:

• ☕ Java Development Kit (JDK) 17+
• 💼 Maven or Gradle installed
• 🄄 A Java IDE (e.g., IntelliJ IDEA, Eclipse)

🛠️ Step 1: Add Dependencies

To enable Actuator, add the following dependency to your Spring Boot project:

• Maven:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

• Gradle:

implementation 'org.springframework.boot:spring-boot-starter-actuator'

🛠️ Step 2: Enable Actuator Endpoints

By default, Actuator exposes several endpoints to provide application insights. You can enable these endpoints in your application.properties or application.yml file.

Configuration Example:

Use this configuration as a baseline and adjust values for your local or production environment.

management.endpoints.web.exposure.include=health,info,metrics
management.endpoint.health.show-details=always

🛠️ Step 3: Using Actuator Endpoints

Here are some commonly used Actuator endpoints:

• /actuator/health: Provides application health status.
• /actuator/info: Displays application metadata.
• /actuator/metrics: Offers application performance metrics.

You can access these endpoints via a browser or API tools like cURL.

Example:

curl -X GET http://localhost:8080/actuator/health

🛠️ Step 4: Customize Actuator Endpoints

You can customize Actuator endpoints to suit your needs. For example, you can define additional metadata in the application.properties file for the /actuator/info endpoint:

info.app.name=My Application
info.app.version=1.0.0
info.app.description=Spring Boot Actuator Example

🛠️ Step 5: Secure Actuator Endpoints

For production environments, it's essential to secure Actuator endpoints. Use Spring Security to restrict access.

Java

Example Security Configuration

package com.example.demo.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
public class SecurityConfig {

    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests()
                .requestMatchers("/actuator/**").hasRole("ADMIN")
                .anyRequest().authenticated()
            .and()
            .httpBasic();
        return http.build();
    }
}

Kotlin

Example Security Configuration

package com.example.demo.config

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

@Configuration
class SecurityConfig {

    @Bean
    fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
        http
            .authorizeHttpRequests()
                .requestMatchers("/actuator/**").hasRole("ADMIN")
                .anyRequest().authenticated()
            .and()
            .httpBasic()
        return http.build()
    }
}

▶️ Running the Application

Run the application using the following command:

./mvnw spring-boot:run

Access the Actuator endpoints at:

http://localhost:8080/actuator/health

🧪 Test the API

You can test the Actuator endpoints using cURL or browser:

• Health Endpoint:

curl -X GET http://localhost:8080/actuator/health

• Info Endpoint:

curl -X GET http://localhost:8080/actuator/info

🏁 Conclusion

You now have a practical Spring Boot Actuator implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why Use AOP?

AOP enables developers to separate concerns that affect multiple parts of an application, like logging or security, into reusable aspects. This approach promotes cleaner code, improved maintainability, and reduced redundancy.

📋 Prerequisites

📋 Ensure you have the following:

• ☕ Java Development Kit (JDK) 17+
• 📦 Maven or Gradle installed
• 🔤 A Java IDE (e.g., IntelliJ IDEA, Eclipse)

🛠️ Step 1: Add Dependencies

Include the following dependencies in your project:

Maven:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-aop</artifactId>
</dependency>

Gradle:

implementation 'org.springframework.boot:spring-boot-starter-aop'

🛠️ Step 2: Define a Service

Create a simple service to demonstrate AOP.

Java

Service

package com.example.demo.service;

import org.springframework.stereotype.Service;

@Service
public class UserService {

    public String getUserById(String id) {
        return "User with ID: " + id;
    }

    public String getAllUsers() {
        return "Fetching all users.";
    }
}

Kotlin

Service

package com.example.demo.service

import org.springframework.stereotype.Service

@Service
class UserService {

    fun getUserById(id: String): String {
        return "User with ID: $id"
    }

    fun getAllUsers(): String {
        return "Fetching all users."
    }
}

🛠️ Step 3: Create an Aspect

Define an aspect to log method execution details.

Java

Aspect

package com.example.demo.aspect;

import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Before;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;

@Aspect
@Component
public class LoggingAspect {

    private static final Logger logger = LoggerFactory.getLogger(LoggingAspect.class);

    @Before("execution(* com.example.demo.service.UserService.*(..))")
    public void logBefore() {
        logger.info("Method execution started.");
    }
}

Kotlin

Aspect

package com.example.demo.aspect

import org.aspectj.lang.annotation.Aspect
import org.aspectj.lang.annotation.Before
import org.slf4j.LoggerFactory
import org.springframework.stereotype.Component

@Aspect
@Component
class LoggingAspect {

    private val logger = LoggerFactory.getLogger(LoggingAspect::class.java)

    @Before("execution(* com.example.demo.service.UserService.*(..))")
    fun logBefore() {
        logger.info("Method execution started.")
    }
}

🛠️ Step 4: Create a Controller

Expose the service methods through a REST controller.

Java

Controller

package com.example.demo.controller;

import com.example.demo.service.UserService;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/users")
@RequiredArgsConstructor
public class UserController {

    private final UserService userService;

    @GetMapping("/{id}")
    public String getUserById(@PathVariable String id) {
        return userService.getUserById(id);
    }

    @GetMapping
    public String getAllUsers() {
        return userService.getAllUsers();
    }
}

Kotlin

Controller

package com.example.demo.controller

import com.example.demo.service.UserService
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.PathVariable
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController

@RestController
@RequestMapping("/api/users")
class UserController(
    private val userService: UserService
) {

    @GetMapping("/{id}")
    fun getUserById(@PathVariable id: String): String = userService.getUserById(id)

    @GetMapping
    fun getAllUsers(): String = userService.getAllUsers()
}

▶️ Running the Application

Run the application using the following commands:

Spring Boot (Java/Kotlin): Run the application with either stack to confirm the baseline setup is working before deeper tests.

./mvnw spring-boot:run

Access the API at http://localhost:8080/api/users.

🧪 Testing the API

You can test the API using the following cURL commands:

• Fetch all users:

curl -X GET http://localhost:8080/api/users

• Fetch a user by ID:

curl -X GET http://localhost:8080/api/users/1

🏁 Conclusion

You now have a practical Aspect-Oriented Programming in Spring Boot implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why Use Dependency Injection?

Dependency Injection allows developers to manage and inject dependencies into classes without manually instantiating them. This leads to:

• Better code modularity
• Simplified testing
• Easier maintenance

📋 Prerequisites

📋 Ensure you have the following:

• ☕ Java Development Kit (JDK) 17+
• 📦 Maven or Gradle installed
• 🔤 A Java IDE (e.g., IntelliJ IDEA, Eclipse)

🛠️ Step 1: Add Dependencies

Include the necessary Spring Boot dependencies:

Maven:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter</artifactId>
</dependency>

Gradle:

implementation 'org.springframework.boot:spring-boot-starter'

🛠️ Step 2: Create a Service

Define a simple service to demonstrate DI.

Java

Service

package com.example.demo.service;

import org.springframework.stereotype.Service;

@Service
public class UserService {

    public String getUserById(String id) {
        return "User with ID: " + id;
    }

    public String getAllUsers() {
        return "Fetching all users.";
    }
}

Kotlin

Service

package com.example.demo.service

import org.springframework.stereotype.Service

@Service
class UserService {

    fun getUserById(id: String): String {
        return "User with ID: $id"
    }

    fun getAllUsers(): String {
        return "Fetching all users."
    }
}

🛠️ Step 3: Inject Dependencies

Use annotations to inject the service into other components.

Java

Controller

package com.example.demo.controller;

import com.example.demo.service.UserService;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/users")
@RequiredArgsConstructor
public class UserController {

    private final UserService userService;

    @GetMapping("/{id}")
    public String getUserById(@PathVariable String id) {
        return userService.getUserById(id);
    }

    @GetMapping
    public String getAllUsers() {
        return userService.getAllUsers();
    }
}

Kotlin

Controller

package com.example.demo.controller

import com.example.demo.service.UserService
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.PathVariable
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController

@RestController
@RequestMapping("/api/users")
class UserController(
    private val userService: UserService
) {

    @GetMapping("/{id}")
    fun getUserById(@PathVariable id: String): String = userService.getUserById(id)

    @GetMapping
    fun getAllUsers(): String = userService.getAllUsers()
}

▶️ Running the Application

Run the application using the following commands:

Spring Boot (Java/Kotlin): Run the application with either stack to confirm the baseline setup is working before deeper tests.

./mvnw spring-boot:run

Access the API at http://localhost:8080/api/users.

🧪 Test the API

You can test the API using the following cURL commands:

Fetch all users

Use this request to verify the list endpoint and validate the default response shape.

curl -X GET http://localhost:8080/api/users

Fetch a user by ID

Use this request to validate path-variable handling and single-resource retrieval behavior.

curl -X GET http://localhost:8080/api/users/1

🏁 Conclusion

You now have a practical Dependency Injection in Spring Boot implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why Use ORM?

ORM bridges the gap between object-oriented programming and relational databases by mapping objects directly to database tables. This eliminates the need for manual SQL queries, reducing errors and increasing productivity for developers.

📋 Prerequisites

📋 Ensure you have the following:

• ☕ Java Development Kit (JDK) 17+
• 📦 Maven or Gradle installed
• 🖥️ A Java IDE
• 🐘 PostgreSQL installed and running

For Go:

• 🔧 Golang 1.17+ installed
• 🔄 go.mod initialized in your project

🛠️ Step 1: Add Dependencies

To set up a Spring Boot project and integrate ORM, follow these steps:

Add Dependencies

For Spring Boot projects, include the following dependencies in your project:

• Maven:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
  <groupId>org.postgresql</groupId>
  <artifactId>postgresql</artifactId>
</dependency>

• Gradle:

implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
implementation 'org.postgresql:postgresql'

Configure the Database

Set up your PostgreSQL connection in the application.properties or application.yml file:

spring.datasource.url=jdbc:postgresql://localhost:5432/demo
spring.datasource.username=your_username
spring.datasource.password=your_password
spring.jpa.hibernate.ddl-auto=update

Initialize the Project

If you haven't already, create your Spring Boot project using Spring Initializr:

1. Choose Spring Web, Spring Data JPA, and PostgreSQL Driver as dependencies.
2. Download the project and import it into your preferred IDE.

For Go projects:

• Install Gin Framework and GORM:

# Install the Gin framework
go get -u github.com/gin-gonic/gin

# Install the GORM PostgreSQL driver
go get -u gorm.io/driver/postgres

# Install the GORM ORM library
go get -u gorm.io/gorm

🛠️ Step 2: Define the Model and Implement the REST Controller

This step combines creating the entity/model, repository, and REST controllers.

Java

Entity

package com.example.demo.entity;

import jakarta.persistence.*;
import lombok.Data;

@Data
@Entity
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;

    private String email;
}

Repository

package com.example.demo.repository;

import com.example.demo.entity.User;
import org.springframework.data.jpa.repository.JpaRepository;

public interface UserRepository extends JpaRepository<User, Long> {
}

REST Controller

package com.example.demo.controller;

import com.example.demo.entity.User;
import com.example.demo.repository.UserRepository;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/api/users")
import lombok.RequiredArgsConstructor;

@RequiredArgsConstructor
public class UserController {

  private final UserRepository userRepository;

  @GetMapping
  public List<User> getAllUsers() {
    return userRepository.findAll();
  }

  @PostMapping
  public User createUser(@RequestBody User user) {
    return userRepository.save(user);
  }
}

Kotlin

Entity

package com.example.demo.entity

import jakarta.persistence.*

@Entity
class User(
  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  val id: Long = 0,

  var name: String,

  var email: String
)

Repository

package com.example.demo.repository

import com.example.demo.entity.User
import org.springframework.data.jpa.repository.JpaRepository

interface UserRepository : JpaRepository<User, Long>

REST Controller

package com.example.demo.controller

import com.example.demo.entity.User
import com.example.demo.repository.UserRepository
import org.springframework.web.bind.annotation.*

@RestController
@RequestMapping("/api/users")
class UserController(
  private val userRepository: UserRepository
) {

  @GetMapping
  fun getAllUsers(): List<User> = userRepository.findAll()

  @PostMapping
  fun createUser(@RequestBody user: User): User = userRepository.save(user)
}

Go

Model and Database Connection

package main

import (
	"gorm.io/driver/postgres"
	"gorm.io/gorm"
)

var DB *gorm.DB

func connectDatabase() {
	dsn := "host=localhost user=your_username password=your_password dbname=demo port=5432 sslmode=disable"
	db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{})
	if err != nil {
		panic("Failed to connect to database!")
	}

	DB = db
	DB.AutoMigrate(&User{})
}

type User struct {
	ID    uint   `json:"id" gorm:"primaryKey"`
	Name  string `json:"name"`
	Email string `json:"email"`
}

Handlers

package main

import (
	"github.com/gin-gonic/gin"
)

func getUsers(c *gin.Context) {
	var users []User
	DB.Find(&users)
	c.JSON(200, users)
}

func createUser(c *gin.Context) {
	var user User
	if err := c.ShouldBindJSON(&user); err != nil {
		c.JSON(400, gin.H{"error": err.Error()})
		return
	}
	DB.Create(&user)
	c.JSON(201, user)
}

func main() {
	r := gin.Default()
	connectDatabase()

	r.GET("/api/users", getUsers)
	r.POST("/api/users", createUser)

	r.Run() // Listen and serve on 0.0.0.0:8080
}

▶️ Running the Applications

In this section, we clarify Running the Applications and summarize the key points you will apply in implementation.

• Spring Boot:

  ./mvnw spring-boot:run
  

• Gin:

  go run main.go
  

🧪 Testing with cURL

You can test the API using the following cURL commands:

Fetch All Users:

curl -X GET http://localhost:8080/api/users

Create a New User:

curl -X POST http://localhost:8080/api/users \
-H "Content-Type: application/json" \
-d '{"name": "John Doe", "email": "johndoe@example.com"}'

🏁 Conclusion

You now have a practical Object-Relational Mapping implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why Validate Input?

Validation ensures the data sent to your API adheres to expected formats and prevents potential vulnerabilities like SQL Injection, XSS, and bad data entries.

📋 Prerequisites

Before implementing validation, make sure you have:

• Java 17+ for Spring Boot examples
• Go 1.21+ for Gin examples
• A running Spring Boot or Gin starter project
• Basic familiarity with DTOs, JSON payloads, and HTTP status codes

🧪 Step 1: Add Validation Dependencies

For Spring Boot projects, include the following dependencies:

• Maven:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

• Gradle:

implementation 'org.springframework.boot:spring-boot-starter-validation'

For Go projects with Gin, use the following:

# Install the Gin framework
go get -u github.com/gin-gonic/gin

# Install the validator package
go get -u github.com/go-playground/validator/v10

🧪 Step 2: Define a DTO with Validation Rules

Use annotations to define validation constraints on fields. Examples include @NotNull, @Size, and @Pattern.

Java

package com.example.demo.dto;

import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Size;
import lombok.Data;

@Data
public class TodoRequest {

    @NotNull(message = "Title is required")
    @Size(min = 3, max = 50, message = "Title must be between 3 and 50 characters")
    private String title;

    private boolean completed;
}

Kotlin

package com.example.demo.dto

import jakarta.validation.constraints.NotNull
import jakarta.validation.constraints.Size

data class TodoRequest(
    @field:NotNull(message = "Title is required")
    @field:Size(min = 3, max = 50, message = "Title must be between 3 and 50 characters")
    val title: String?,

    val completed: Boolean = false
)

Go

package dto

import (
    "github.com/go-playground/validator/v10"
)

type TodoRequest struct {
    Title     string `validate:"required,min=3,max=50"`
    Completed bool   `validate:""`
}

var validate = validator.New()

func ValidateTodoRequest(todo TodoRequest) error {
    return validate.Struct(todo)
}

🧪 Step 3: Create a Controller with Validation

Integrate validation into your REST endpoints.

Java

package com.example.demo.controller;

import com.example.demo.dto.TodoRequest;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/todos")
public class TodoController {

    @PostMapping
    public String createTodo(@Validated @RequestBody TodoRequest request) {
        return "Todo created: " + request.getTitle();
    }
}

Kotlin

package com.example.demo.controller

import com.example.demo.dto.TodoRequest
import org.springframework.validation.annotation.Validated
import org.springframework.web.bind.annotation.*

@RestController
@RequestMapping("/api/todos")
class TodoController {

    @PostMapping
    fun createTodo(@Validated @RequestBody request: TodoRequest): String {
        return "Todo created: ${request.title}"
    }
}

Go

package controller

import (
    "dto"
    "github.com/gin-gonic/gin"
    "net/http"
)

func CreateTodoHandler(c *gin.Context) {
    var todo dto.TodoRequest

    if err := c.ShouldBindJSON(&todo); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }

    if err := dto.ValidateTodoRequest(todo); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }

    c.JSON(http.StatusOK, gin.H{"message": "Todo created", "title": todo.Title})
}

🧪 Step 4: Handle Validation Errors

Customize error handling to return user-friendly responses.

Java

package com.example.demo.exception;

import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.bind.MethodArgumentNotValidException;

import java.util.HashMap;
import java.util.Map;

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Map<String, String> handleValidationExceptions(MethodArgumentNotValidException ex) {
        Map<String, String> errors = new HashMap<>();
        ex.getBindingResult().getFieldErrors().forEach(error -> errors.put(error.getField(), error.getDefaultMessage()));
        return errors;
    }
}

Kotlin

package com.example.demo.exception

import org.springframework.http.HttpStatus
import org.springframework.web.bind.annotation.ExceptionHandler
import org.springframework.web.bind.annotation.RestControllerAdvice
import org.springframework.web.bind.MethodArgumentNotValidException

@RestControllerAdvice
class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException::class)
    fun handleValidationExceptions(ex: MethodArgumentNotValidException): Map<String, String> {
        return ex.bindingResult.fieldErrors.associate { it.field to it.defaultMessage.orEmpty() }
    }
}

Go

package middleware

import (
    "github.com/gin-gonic/gin"
    "net/http"
)

func ErrorHandler() gin.HandlerFunc {
    return func(c *gin.Context) {
        c.Next()

        if len(c.Errors) > 0 {
            c.JSON(http.StatusBadRequest, gin.H{"errors": c.Errors.JSON()})
        }
    }
}

main.go Example

Here is an example of the main.go file for setting up a Gin application:

package main

import (
	"controller"
	"github.com/gin-gonic/gin"
)

func main() {
	r := gin.Default()

	r.POST("/api/todos", controller.CreateTodoHandler)

	r.Run() // Start the server on http://localhost:8080
}

▶️ Step 5: Run the Application

To run the application:

Spring Boot (Java/Kotlin): Run the Spring Boot application from your IDE or terminal:

./mvnw spring-boot:run # For Maven projects
./gradlew bootRun       # For Gradle projects

Access the API at http://localhost:8080/api/todos.

Gin (Go)

Run the Go application:

go run main.go

Access the API at http://localhost:8080/api/todos.

🧪 Testing with cURL

Here are some example cURL commands to test the API:

• POST a new Todo:

curl -X POST http://localhost:8080/api/todos \
-H "Content-Type: application/json" \
-d '{"title": "New Task", "completed": false}'

• GET all Todos:

curl -X GET http://localhost:8080/api/todos

• Handle Validation Errors:

Send an invalid request:

curl -X POST http://localhost:8080/api/todos \
-H "Content-Type: application/json" \
-d '{"title": ""}'

🏁 Conclusion

You now have a practical Input Validation in REST APIs implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 Why Use GraphQL?

GraphQL allows clients to request specific data, reducing over-fetching and under-fetching compared to REST. It also supports strong typing and facilitates efficient data fetching, making it a popular choice for modern APIs.

📋 Prerequisites

📋 Ensure you have the following:

• ☕ Java Development Kit (JDK) 17+
• 📦 Maven or Gradle installed
• 🔤 A Java IDE (e.g., IntelliJ IDEA, Eclipse)

🛠️ Step 1: Add Dependencies

Include the following dependencies in your project to enable Spring for GraphQL.

Maven:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-graphql</artifactId>
</dependency>

Gradle:

implementation 'org.springframework.boot:spring-boot-starter-graphql'

🛠️ Step 2: Define the GraphQL Schema

Create a schema file named schema.graphqls under the src/main/resources/graphql directory.

type Query {
  getUser(id: ID!): User
  getUsers: [User]
}

type User {
  id: ID!
  name: String!
  email: String!
}

🛠️ Step 3: Implement the Data Model and Services

Define the data model and service layer for handling queries.

Java

Entity

package com.example.demo.model;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@NoArgsConstructor
@AllArgsConstructor
public class User {
    private String id;
    private String name;
    private String email;
}

Service

package com.example.demo.service;

import com.example.demo.model.User;
import org.springframework.stereotype.Service;

import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;
import java.util.stream.Stream;

@Service
public class UserService {

    private final Map<String, User> userData = Stream.of(
        new User("1", "Alice", "alice@example.com"),
        new User("2", "Bob", "bob@example.com")
    ).collect(Collectors.toMap(User::getId, user -> user));

    public User getUser(String id) {
        return userData.get(id);
    }

    public List<User> getUsers() {
        return List.copyOf(userData.values());
    }
}

Kotlin

Entity

package com.example.demo.model

data class User(
    val id: String,
    val name: String,
    val email: String
)

Service

package com.example.demo.service

import com.example.demo.model.User
import org.springframework.stereotype.Service

@Service
class UserService {

    private val userData = mapOf(
        "1" to User("1", "Alice", "alice@example.com"),
        "2" to User("2", "Bob", "bob@example.com")
    )

    fun getUser(id: String): User? = userData[id]

    fun getUsers(): List<User> = userData.values.toList()
}

🛠️ Step 4: Implement GraphQL Controllers

Controllers handle GraphQL queries and mutations. Use the @Controller annotation in Spring for GraphQL.

Java

package com.example.demo.controller;

import com.example.demo.model.User;
import com.example.demo.service.UserService;
import lombok.RequiredArgsConstructor;
import org.springframework.graphql.data.method.annotation.QueryMapping;
import org.springframework.stereotype.Controller;

import java.util.List;

@Controller
@RequiredArgsConstructor
public class UserController {

    private final UserService userService;

    @QueryMapping
    public User getUser(String id) {
        return userService.getUser(id);
    }

    @QueryMapping
    public List<User> getUsers() {
        return userService.getUsers();
    }
}

Kotlin

package com.example.demo.controller

import com.example.demo.model.User
import com.example.demo.service.UserService
import org.springframework.graphql.data.method.annotation.QueryMapping
import org.springframework.stereotype.Controller

@Controller
class UserController(
    private val userService: UserService
) {

    @QueryMapping
    fun getUser(id: String): User? = userService.getUser(id)

    @QueryMapping
    fun getUsers(): List<User> = userService.getUsers()
}

▶️ Running the Application

Run the application using the following commands:

Spring Boot (Java/Kotlin): Run the application with either stack to confirm the baseline setup is working before deeper tests.

./mvnw spring-boot:run

Access the GraphQL Playground at http://localhost:8080/graphiql to test your API.

🧪 Testing the GraphQL API

Here are some example queries to test your API:

• Fetch a user by ID:

query {
  getUser(id: "1") {
    id
    name
    email
  }
}

• Fetch all users:

query {
  getUsers {
    id
    name
    email
  }
}

🏁 Conclusion

You now have a practical Building APIs with Spring for GraphQL implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 What you'll learn

In this section, we clarify What you'll learn and summarize the key points you will apply in implementation.

• How to initialize a minimal Gin project structure.
• How to build and expose your first JSON endpoint.
• How to run and validate the service locally before adding business logic.

📋 Prerequisites

📋 Before starting, ensure you have the following:

• 🔧 Golang 1.17+ installed
• 🗍 A text editor or IDE (e.g., Visual Studio Code, GoLand, or Vim)

🛠️ Step 1: Set Up Your Gin Project

You can set up your first Gin project by following these steps:

1. Initialize a Go Module

mkdir gin-first-app
cd gin-first-app
go mod init gin-first-app

2. Install Gin

go get -u github.com/gin-gonic/gin

🛠️ Step 2: Writing Your First Endpoint

Let’s write a simple endpoint to say hello:

Create a file named main.go with the following content:

package main

import (
	"github.com/gin-gonic/gin"
)

func main() {
	r := gin.Default()

	r.GET("/hello", func(c *gin.Context) {
		c.JSON(200, gin.H{
			"message": "Hello, Gin!",
		})
	})

	r.Run() // Listen and serve on 0.0.0.0:8080
}

▶️ Step 3: Run the Application

In this section, we clarify Step 3: Run the Application and summarize the key points you will apply in implementation.

1. Open a terminal in the project folder.
2. Execute the following command to run your application:

go run main.go

3. Access the endpoint at:

   http://localhost:8080/hello
   

Response:

{
  "message": "Hello, Gin!"
}

🏁 Conclusion

You now have a practical Gin - First Application implementation with a clear, production-friendly structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 What is a REST API?

REST (Representational State Transfer) is an architectural style for designing web services. It uses standard HTTP methods for communication between clients and servers.

HTTP Methods

In this subsection, we frame HTTP Methods with concise context so the next example is easier to follow.

📋 Prerequisites

Before you start, make sure the following are ready:

• Java 17+
• Maven or Gradle
• An IDE (IntelliJ IDEA, Eclipse, VS Code)
• Basic familiarity with HTTP methods and JSON payloads

🛠️ Step 1: Create a Project

You can create a Spring Boot project using Spring Initializr. Select the following settings:

• Project: Maven
• Language: Java or Kotlin
• Spring Boot Version: 3.0.0+
• Dependencies: Spring Web, Spring Boot DevTools, Lombok

Download the project, open it in your IDE, and get ready to run it.

🛠️ Step 2: Create a Model Class

Create a model class for a Todo object:

Java

package com.example.demo.model;

import lombok.Data;

@Data
public class Todo {
    private Long id;
    private String title;
    private boolean completed;
}

Kotlin

package com.example.demo.model

data class Todo(
    var id: Long,
    var title: String,
    var completed: Boolean
)

🛠️ Step 3: Create a Controller Class

Add a TodoController class to define CRUD operations as REST endpoints:

Java

package com.example.demo.controller;

import com.example.demo.model.Todo;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;

@RestController
@RequestMapping("/api/todos")
public class TodoController {

    private List<Todo> todos = new ArrayList<>();

    @GetMapping
    public List<Todo> getAllTodos() {
        return todos;
    }

    @PostMapping
    public Todo createTodo(@RequestBody Todo todo) {
        todo.setId((long) (todos.size() + 1));
        todos.add(todo);
        return todo;
    }

    @PutMapping("/{id}")
    public Todo updateTodo(@PathVariable Long id, @RequestBody Todo updatedTodo) {
        Todo todo = todos.stream().filter(t -> t.getId().equals(id)).findFirst().orElse(null);
        if (todo != null) {
            todo.setTitle(updatedTodo.getTitle());
            todo.setCompleted(updatedTodo.isCompleted());
        }
        return todo;
    }

    @DeleteMapping("/{id}")
    public void deleteTodo(@PathVariable Long id) {
        todos.removeIf(todo -> todo.getId().equals(id));
    }
}

Kotlin

package com.example.demo.controller

import com.example.demo.model.Todo
import org.springframework.web.bind.annotation.*

@RestController
@RequestMapping("/api/todos")
class TodoController {

    private val todos = mutableListOf<Todo>()

    @GetMapping
    fun getAllTodos(): List<Todo> = todos

    @PostMapping
    fun createTodo(@RequestBody todo: Todo): Todo {
        todo.id = (todos.size + 1).toLong()
        todos.add(todo)
        return todo
    }

    @PutMapping("/{id}")
    fun updateTodo(@PathVariable id: Long, @RequestBody updatedTodo: Todo): Todo? {
        val todo = todos.find { it.id == id }
        todo?.apply {
            title = updatedTodo.title
            completed = updatedTodo.completed
        }
        return todo
    }

    @DeleteMapping("/{id}")
    fun deleteTodo(@PathVariable id: Long) {
        todos.removeIf { it.id == id }
    }
}

🧪 Step 4: Test the API

Test your API using curl commands:

• GET All Todos:

curl -X GET http://localhost:8080/api/todos

• POST New Todo:

curl -X POST http://localhost:8080/api/todos -H "Content-Type: application/json" -d '{"title": "New Todo", "completed": false}'

• PUT Update Todo:

curl -X PUT http://localhost:8080/api/todos/1 -H "Content-Type: application/json" -d '{"title": "Updated Todo", "completed": true}'

• DELETE Delete Todo:

curl -X DELETE http://localhost:8080/api/todos/1

🏁 Conclusion

You now have a practical Building a REST API with Spring Boot implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.

🌟 What you'll learn

In this section, we clarify What you'll learn and summarize the key points you will apply in implementation.

• How to bootstrap a Spring Boot project with Java or Kotlin.
• How to expose your first HTTP endpoint and verify it quickly.
• How to run the app locally and prepare a clean base for the next features.

📋 Prerequisites

📋 Before starting, ensure you have the following:

• ☕ Java Development Kit (JDK) 17+ installed
• 📦 Maven or Gradle installed
• 🖥️ A Java IDE (e.g., IntelliJ IDEA, Eclipse, or Visual Studio Code)

🛠️ Step 1: Create a Spring Boot Project

You can create your first Spring Boot project in two ways:

1. Using Spring Initializr 🖱️

• Visit Spring Initializr.
• Configure the following:
  • 📂 Project: Maven
  • 👨‍💻 Language: Java or Kotlin
  • 🔄 Spring Boot Version: 3.0.0 (or the latest version).
  • 📜 Add dependencies: Spring Web
• Click Generate to download the project files.

2. Using IntelliJ IDEA 💻

• Open IntelliJ IDEA.
• Go to New Project > Spring Initializr.
• Configure similar parameters as mentioned above.

🛠️ Step 2: Writing Your First Endpoint

Let’s write a simple endpoint to say hello:

Java

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
@RestController
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }

    @GetMapping("/hello")
    public String sayHello() {
        return "Hello, Spring Boot!";
    }
}

Kotlin

package com.example.demo

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.RestController

@SpringBootApplication
@RestController
class DemoApplication

fun main(args: Array<String>) {
    runApplication<DemoApplication>(*args)
}

@GetMapping("/hello")
fun sayHello(): String {
    return "Hello, Spring Boot!"
}

▶️ Step 3: Run the Application

In this section, we clarify Step 3: Run the Application and summarize the key points you will apply in implementation.

1. Open a terminal in the project folder.
2. Execute the command to run your application:

./mvnw spring-boot:run

3. Access the endpoint at:

   http://localhost:8080/hello
   

Response:

Hello, Spring Boot!

🏁 Conclusion

You now have a practical Spring Boot - First Application implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.