Interacting with data through natural language is quickly becoming a mainstream expectation in modern applications. Whether it's asking for "all orders over $50" or "products added last week", enabling users to query systems in natural language can dramatically improve accessibility and productivity of users.

Motivation

Why Elasticsearch?

Relational databases like PostgreSQL are great for storing structured, transactional data. However, when it comes to searching large datasets with flexible, full-text queries, they can be limiting and complicated. To solve this pattern, we can use the CQRS pattern.

CQRS

CQRS (Command Query Responsibility Segregation) is a design pattern that separates read operations (queries) from write operations (commands). Instead of using the same model to update and read data, you use two distinct models:

• Commands modify data (like "PlaceOrder" or "UpdateOrder")

• Queries fetch data (like "GetOrderDetails" or "ListOrders")

This separation makes systems more scalable, maintainable, and can help optimize each side individually. You could implement this various ways, e.g.: single database with a Command module & Query module interfacing with it in the application side, or in this example, using a relational database (Postgresql) for writes and a fast NoSQL (Elasticsearch) for reads. For more information, you can read Martin Fowler’s Essay on this topic.

How does Elasticsearch fit the bill?

Elasticsearch complements PostgreSQL by enabling powerful, fast, and fuzzy search capabilities over the same data. By syncing PostgreSQL to Elasticsearch (using kafka connectors), you get the best of both worlds: reliable data storage and advanced search. This proves useful for applications like Semantic search, RAG & many other search related use cases.

Complexity of querying

Traditionally, search in applications is implemented using static queries—hardcoded SQL / Query DSL with strict filters or limited parameters (complexity that grows as the users ask to query more fields). But users rarely think in ‘columns’, they want to answers to questions like:

• “Show all orders over $50 from last month”

• “Find customers who bought greater than 7 items”

Supporting these kind of dynamic, user-generated queries is tough with static scripts or code alone. It either leads to overly complex query builders or brittle pattern matching logic with limited flexibility. Using Spring AI with Elasticsearch powered by an LLM (OpenAI), we can now interpret & translate the queries it into dynamically generated DSL making it easier to query the system, in turn making it much more user-friendly and accessible.

In this post, we will:

• Build an infrastructure pipeline with PostgreSQL, Kafka, and Elasticsearch enabling near real-time searchability

• Use Spring AI to handle natural language query interpretation

• Run and test the system with real examples

Setting Up and Running the Project

Prerequisites

Before getting started, make sure the following tools are installed:

• Java 21 using SDKMAN

• Docker & Docker Compose

• OpenAI API Key

• Your favorite text editor (I’m using Intellij for Java & VSCode for React)

• Optional: If running the UI helper application, you need Node (v22.12.0+ preferred)

Using WSL?
If you're using WSL like I am, the same steps would work for you as well. Just open your favorite terminal editor (I prefer Powershell), & login to WSL.

Now you can follow along with the commands described in the post.

Note: If you have any trouble following any of the steps, you can check the application README.md in Github for troubleshooting steps

1. Clone the Repository & Start Infrastructure

You can find the code here: https://github.com/arunbalachandran/QueryElasticUsingSpringAI

git clone https://github.com/arunbalachandran/QueryElasticUsingSpringAI
cd QueryElasticUsingSpringAI
docker compose up -d

[+] Building 0.0s (0/0)
[+] Running 9/9
 ✔ Network queryelasticusingspringai_dockernet             Create...                                               0.1s
 ✔ Container queryelasticusingspringai-postgres-1          Sta...                                                  0.9s
 ✔ Container queryelasticusingspringai-zookeeper-1         St...                                                   0.8s
 ✔ Container queryelasticusingspringai-elasticsearch-1     Started                                                 0.7s
 ✔ Container queryelasticusingspringai-kibana-1            Start...                                                1.0s
 ✔ Container queryelasticusingspringai-kafka-1             Starte...                                               1.2s
 ✔ Container queryelasticusingspringai-akhq-1              Started                                                 1.6s
 ✔ Container queryelasticusingspringai-debezium-connect-1  Started                                                 1.7s
 ✔ Container queryelasticusingspringai-kafka-connect-1     Started                                                 1.7s

2. Open querybackend

Open the querybackend project in your favorite text editor. I’ve used Intellij:

3. Set Your Environment for Java

export OPENAI_API_KEY=your-api-key-here

Or, if you're using IntelliJ, you can set it in your run configuration.

4. Initialize Elasticsearch Mapping

Create the order index:

Note: If using Postman, import the collection included in the repository into Postman & you can follow along using the endpoints mentioned here.

curl -X PUT "http://localhost:9200/order" \
-H "Content-Type: application/json" \
-d '{
    "mappings": {
    "properties": {
        "id": {
        "type": "keyword"
        },
        "product_name": {
        "type": "text",
        "fields": {
            "keyword": {
            "type": "keyword",
            "ignore_above": 256
            }
        }
        },
        "product_qty": {
        "type": "integer"
        },
        "product_price": {
        "type": "double"
        },
        "product_description": {
        "type": "text"
        },
        "created_time": {
        "type": "date"
        },
        "updated_time": {
        "type": "date"
        }
    }
    }
}'

5. Start the Application

./gradlew bootRun

Or, if using Intellij, run the ‘bootRun’ gradle task

Data Flow: PostgreSQL ➝ Kafka ➝ Elasticsearch

To get data flowing from your relational DB to Elasticsearch:

1. Set Up Kafka Connectors

# PostgreSQL to Kafka (Debezium)
curl -X POST http://localhost:8084/connectors -H "Content-Type: application/json" -d '{
    "name": "postgres-to-kafka-connector",
    "config": {
        "connector.class": "io.debezium.connector.postgresql.PostgresConnector",
        "database.hostname": "postgres",
        "database.port": "5432",
        "database.user": "postgres",
        "database.password": "password",
        "database.dbname" : "querybackend",
        "topic.prefix": "connector",
        "tasks.max": "1",
        "schemas.enable": "false",
        "schema.include.list": "public",
        "table.include.list": "public.orders",
        "signal.data.collection": "public.debezium_signal",
        "key.converter": "org.apache.kafka.connect.json.JsonConverter",
        "key.converter.schemas.enable": false,
        "value.converter": "org.apache.kafka.connect.json.JsonConverter",
        "value.converter.schemas.enable": false,
        "auto.register.schemas": true,
        "topic.creation.default.replication.factor": 1,
        "topic.creation.default.partitions": 1,
        "transforms": "extractlatest",
        "transforms.extractlatest.type": "org.apache.kafka.connect.transforms.ExtractField$Value",
        "transforms.extractlatest.field": "after",
        "time.precision.mode": "connect",
        "decimal.handling.mode": "double",
        "heartbeat.interval.ms": "1800000",
        "snapshot.mode": "initial",
        "plugin.name": "pgoutput",
        "slot.name" : "query_slot_orders_01"
    }
}'

# Kafka to Elasticsearch (Confluent Sink)
curl -X POST http://localhost:8084/connectors -H "Content-Type: application/json" -d '{
  "name": "elasticsearch-sink-connector",
  "config": {
    "connector.class": "io.confluent.connect.elasticsearch.ElasticsearchSinkConnector",
    "tasks.max": "1",
    "topics": "connector.public.orders",
    "schemas.enable": false,
    "schema.ignore": true,
    "key.converter": "org.apache.kafka.connect.json.JsonConverter",
    "key.converter.schemas.enable": false,    
    "value.converter": "org.apache.kafka.connect.json.JsonConverter",
    "value.converter.schemas.enable": false,
    "type.name": "_doc",
    "key.ignore": false,
    "index": "orders",
    "connection.url": "http://elasticsearch:9200",
    "transforms": "InsertKey,ExtractId",
    "transforms.InsertKey.type": "org.apache.kafka.connect.transforms.ValueToKey",
    "transforms.InsertKey.fields": "id",
    "transforms.ExtractId.type": "org.apache.kafka.connect.transforms.ExtractField$Key",
    "transforms.ExtractId.field": "id",
    "transforms.unwrap.drop.tombstones": "false",
    "transforms.unwrap.drop.deletes": "false",
    "behavior.on.null.values": "delete"
  }
}'

Querying with Natural Language

Once everything is up and running, it's time to test the actual use case: converting plain English queries into Elasticsearch queries using Spring AI.

Testing the Backend API

Add Test Data

curl -X POST http://localhost:8080/api/v1/orders -H "Content-Type: application/json" -d '{
  "productName": "Peaches",
  "productQty": 8,
  "productPrice": 12,
  "productDescription": "Peaches"
}'

Try a Natural Language Query

The moment of truth! We will harness the power of OpenAI’s API to parse our queries & fetch the data from our database.

Note: I’ve already added a few sample records in the database.

curl -X POST http://localhost:8080/api/v1/elastic/query \
-H "Content-Type: application/json" \
-d '{
    "query": "Get me all the orders with quantity greater than 5"
}'

# Response
[
    {
        "id": "bfacba9b-66bb-480f-b63c-eeb1f0381a21",
        "productName": "Orange",
        "productQty": 6,
        "productPrice": 10.0,
        "productDescription": "California Oranges",
        "createdTime": "2025-05-20T07:52:59.54",
        "updatedTime": "2025-05-20T07:52:59.541"
    },
    {
        "id": "4c3e65ec-8684-480a-a9b0-50925209146d",
        "productName": "Mangoes",
        "productQty": 12,
        "productPrice": 15.0,
        "productDescription": "Alphonso Mangoes",
        "createdTime": "2025-05-20T07:53:30.606",
        "updatedTime": "2025-05-20T07:53:30.606"
    },
    {
        "id": "7f1838cf-577a-42bd-b4a2-d58d3a70cedd",
        "productName": "Apple",
        "productQty": 8,
        "productPrice": 10.0,
        "productDescription": "Apples",
        "createdTime": "2025-05-20T07:52:46.101",
        "updatedTime": "2025-05-20T07:52:46.101"
    },
    {
        "id": "6fa9a0f8-b2c8-4c1c-86a5-b5344d2f2a58",
        "productName": "Peaches",
        "productQty": 7,
        "productPrice": 12.0,
        "productDescription": "Peaches",
        "createdTime": "2025-05-20T07:54:01.823",
        "updatedTime": "2025-05-20T07:54:01.823"
    }
]

Behind the scenes, Spring AI uses the OpenAI API to interpret the query and translate it into a DSL that Elasticsearch understands. The system is designed to be extensible, so you can add more context, prompt templates, or user data as needed.

Seeing it in action

I’ve included a sample React based UI app, that we can use to see the API in action in the context of a Real World Application

Run UI Code

Navigate to the queryui folder & run the following commands:

cd queryui
# install dependencies if you haven't already
npm install
# run the application
npm run dev
# Application starts on port 5173

Navigate to the application on http://localhost:5173 & you should see a UI that looks like this:

Run a query & you should see the results update in the screen:

Under the Hood

The connector

• There are 2 connectors at play here. The Debezium connector & the Confluent connector.

• The debezium connector is responsible for relaying the data from Postgres to Kafka

• While, the confluent connector is responsible for relaying the data from Kafka to Elasticsearch.

• 💡Note: It may be possible to use Debezium to stream the data both as the source & the sink connectors, but is a bit more cumbersome to setup. This is left as an exercise to the reader.

Spring AI integration

Let’s take a closer look at the PromptService class. This is where the magic happens. It’s responsible for turning user-written natural language queries into structured Elasticsearch queries with the help of Spring AI, which provides us a wrapper to the Open AI Large Language Model (LLM).

Purpose of the Service

The PromptService serves as the bridge between user intent and machine-readable queries. When a user enters a question like “Show me all orders above $50 from last month”, this service constructs a prompt and uses an LLM to generate a precise Elasticsearch query based on the structure of the index.

Key Components

ChatModel

• Injects the LLM backend provided by Spring AI. Here configured to use OpenAI (gpt-4o).

• This is the model responsible for converting natural language into JSON-based Elasticsearch queries.

ElasticSearchService

• A helper service to interact with the Elasticsearch index, get mappings, and perform searches.

Prompt Initialization (@PostConstruct)

@PostConstruct
public void init() {
    String mapping = elasticsearchService.getOrderMapping();
    this.basePrompt = """
        I need you to convert natural language user queries into elasticsearch queries...
        ...
        """.formatted(mapping);
}

• On application startup, we retrieve the Elasticsearch mapping for the Order index.

• This mapping is embedded into the basePrompt. It gives the LLM context about what fields exist (e.g., productName, productPrice, createdTime).

• The prompt instructs the LLM how to behave, e.g., “don't use markdown”, “output the mapping without formatting,” and “understand the semantics of what’s being asked.”

Processing the User Query

public List<OrderDTO> processPrompt(String userQuery) {
    String fullPrompt = basePrompt + "\nUser query: " + userQuery;
    ...
}

1. The userQuery (e.g., “Get me all the orders with quantity greater than 5”) is appended to the basePrompt.

2. This becomes a single, complete prompt that’s fed to the LLM.

public List<OrderDTO> processPrompt(String userQuery) {
    String fullPrompt = basePrompt + "\nUser query: " + userQuery;
    log.info("Prompt being used: {}", fullPrompt);
    ChatResponse chatResponse = chatModel.call(
            new Prompt(
                    fullPrompt,
                    OpenAiChatOptions.builder()
                            .model("gpt-4o")
                            .temperature(1.0)
                            .build()
            )
    );
    String elasticQuery = chatResponse.getResult().getOutput().getText();
    log.info("Elastic query: {}", elasticQuery);
    Map<String, Object> response = elasticsearchService.search(elasticQuery);
    return ElasticMapper.mapToOrderDTO(response);
}

3. The prompt is sent to the LLM (chatModel.call()), and we expect a raw JSON Elasticsearch query in return.

String elasticQuery = chatResponse.getResult().getOutput().getText();

4. The LLM's output is extracted as a string. This is the dynamically generated Elasticsearch DSL query.

Map<String, Object> response = elasticsearchService.search(elasticQuery);
return ElasticMapper.mapToOrderDTO(response);

5. The generated query is executed via elasticsearchService.search().

6. The raw search results are then mapped to OrderDTO objects for use in the API.

Why This Matters

This pattern allows your application to understand and interpret human-friendly input without rigid UI constraints or static filters. It unlocks a much more intuitive experiences, especially valuable for user-facing search interfaces & dashboards.

It also abstracts the complexity of search syntax away from the user while still allowing them to perform advanced, flexible queries based on their intent.

Sequence Diagram

To better illustrate the flow, here’s a sequence diagram, showing the order of events in the application:

Wrapping it up

In this post, I’ve demonstrated how we can:

• Set up a full-stack data ingestion pipeline & search stack using PostgreSQL, Kafka, and Elasticsearch

• Use Spring AI and OpenAI's LLMs to handle natural language queries

• Automatically translate plain English into structured Elasticsearch queries

Future Use Cases

Here are a few ideas for extending this:

• Add user roles and access filters to contextualize results

• Enable conversational memory with a chat-style interface allowing users to ask follow up questions

• Use RAG (Retrieval-Augmented Generation) for more dynamic query understanding

• Integrate Kibana dashboards that go along with the generated results

This foundation gives you a practical starting point for building intelligent, search-driven interfaces. If you're exploring ways to make data more accessible, this is a compelling approach worth trying!

Got ideas or questions? Drop them in the comments! 💬

In today’s modern microservice based applications, policy-based control has become essential for enforcing access rules, managing compliance, and ensuring secure behavior across services. One powerful tool that helps developers build these rules declaratively is a framework called Open Policy Agent (OPA).

If you haven’t heard of OPA before, it’s allows you to decouple policy from code, enabling better manageability, auditing, and testing of rules. In this post, we’ll dive into:

• What is OPA, Really?

• How to write your first policy with Rego

• And how to integrate OPA with a real-world Spring Boot application

• How it works under the hood?

What is OPA, Really?

OPA (Open Policy Agent) is a powerful policy engine and framework that lets you decouple rules from your application logic. Instead of hardcoding authorization, filtering, or validation logic, you define these rules in a separate, declarative format using OPA's policy language, Rego.

Why does that matter? Because it gives you flexibility. You can modify policies on the fly — no need to restart or redeploy your application.

💡 Imagine the possibilities:

• Zero-downtime feature toggles

• Real-time adjustments for system load

• Rapid adaptation to evolving business rules

And that’s just scratching the surface! With OPA, your system becomes more dynamic, adaptable, and maintainable.

Getting Hands-On with OPA

Prerequisites

Before diving into OPA + Spring Boot, make sure your local environment is set up with the following:

• Java 17
  The project uses Java 17 as the target JDK for compiling and running the Spring Boot application.

• Docker
  Required for running the OPA, PostgreSQL, and Redis containers.

Setup Resources

• Install Java 17 using SDKMAN (my preferred option) or you can install Java directly using ‘apt’

• Install docker & docker compose

Using WSL?
If you're using WSL like I am, the same steps would work for you as well. Just open your favorite terminal editor (I prefer Powershell), & login to WSL.

Now you can follow along with the commands described in the post.

1. Writing Your First OPA Policy

OPA uses a language called Rego for writing policies. Here's a super simple rule that checks if a user is an admin:

package auth            # this defines the namespace that your OPA policy will be part of

default allow = false   # variable used to track our policy result, with a default value

allow {
  input.role == "admin" # this is the check our policy executes & if true, allow will be set to true
}

Let’s break this policy down, into its different components:

package auth

Every Rego policy belongs to a package — think of it like a namespace.
This line says: "All the rules in this file belong to the auth package."
You’ll refer to this package name when querying OPA, like:
/v1/data/auth

default allow = false

This sets the default value for the allow rule to false (i.e., deny by default).
If no other rule matches, OPA will return false.
Secure by default — always a good policy principle.

allow { input.role == "admin" }

This is the rule logic. It says:

“Allow access only if the input role is admin.”

OPA evaluates the input JSON sent by your application — for example:

{
  "role": "admin"
}

If the condition matches, allow becomes true, and access is granted.

TL;DR: This policy enforces admin-only access, is easy to tweak, with just a few lines of Rego.

2. Playing Around in the Rego Playground

The OPA Playground is a web-based tool where you can:

• Write and test Rego policies

• Provide input JSON

• See decision outputs in real-time

Here’s how the Rego Playground looks like:

You can use the section on the left to add your policy and the section on the right to add inputs for the policy.
Let’s start by taking the previously discussed example & testing that policy on the OPA playground. Copy the given example policy and it’s inputs to the page. Click the Evaluate button to run the evaluate the inputs against the policy.

Sample policy:

package auth

default allow = false

allow {
  input.role == "admin"
}

Example input:

{
  "role": "admin"
}

Example output:

{
    "allow": true
}

The policy sends a response with ‘allow’ as ‘true’ if the user has a role : ‘admin’, else it will return ‘false’.

Now we can build on this to create a simple end to end application.

💡 Tip: Experiment with different values for the role & check the outputs returned. Also, what if you changed ‘allow’ to be called a different name? How does the output change?

3. Integrating OPA in a Spring Boot Application

Let’s implement a simple policy-based authorization mechanism in a Spring Boot app.
For this, I’ve already implemented a simple real world application that has a login page & a simple GET Users endpoint that fetches all the users in the system.

Here’s the sample application that we will be using today: https://github.com/arunbalachandran/OpaPolicySpringBoot

Clone the application & navigate to the folder using your favorite terminal.
If you’re running Windows like me - you can clone this inside WSL.

Step 1: Understand the Architecture

Before we dive in, here’s a quick overview of the key layers in the application:

Core Components

• Security Layer 🔐
  Handles JWT parsing, Spring Security configuration, and exception handling.

  • JWTAuthenticationFilter, JWTService, SecurityConfiguration

• Authorization Layer ✅
  Intercepts API requests and checks them with OPA before allowing access.

  • OpaService, CustomAuthorizationManager, MethodSecurityConfig

• Data Layer 🗄️
  Backed by PostgreSQL (user data) and Redis (caching/session).

  • JPA Repositories for persistence

• API Layer 🌐
  Controllers exposing endpoints for authentication and user management.

  • Annotated with @PreAuthorize to enforce OPA checks

Step 2: Bring Up the System with Docker Compose & Setup the Database

Let’s bring up the containers:

arunbala@ArunRazer:~/OpaPolicySpringBoot$ docker compose up -d
[+] Building 0.0s (0/0)
[+] Running 4/4
 ✔ Network opapolicyspringboot_default       Created                                                               0.2s
 ✔ Container opapolicyspringboot-redis-1     Started                                                               1.1s
 ✔ Container opapolicyspringboot-opa-1       Started                                                               1.2s
 ✔ Container opapolicyspringboot-postgres-1  Started                                                               1.2s
arunbala@ArunRazer:~/OpaPolicySpringBoot$ docker ps
CONTAINER ID   IMAGE                        COMMAND                  CREATED         STATUS         PORTS                                         NAMES
e988e2324495   redis:latest                 "docker-entrypoint.s…"   7 seconds ago   Up 6 seconds   0.0.0.0:6379->6379/tcp, [::]:6379->6379/tcp   opapolicyspringboot-redis-1
775d30d9fdbf   postgres:14.17               "docker-entrypoint.s…"   7 seconds ago   Up 6 seconds   0.0.0.0:5432->5432/tcp, [::]:5432->5432/tcp   opapolicyspringboot-postgres-1
82eec0a4c6ad   openpolicyagent/opa:latest   "/opa run --server -…"   7 seconds ago   Up 6 seconds   0.0.0.0:8181->8181/tcp, [::]:8181->8181/tcp   opapolicyspringboot-opa-1

What’s Running?

If you look at the docker-compose file, these are the services running underneath the hood:

• opa: The Open Policy Agent server on port 8181 — responsible for evaluating policy decisions.

• postgres: Stores user data for the app.

• redis: Handles token-related caching and quick lookups.

The Spring Boot app will connect to these services using configurations defined in application.yml.

You can also connect to the database using any database tool of your choice. I prefer using DBeaver.

Step 3: Open the Project in Intellij

Once the Docker containers are up and running, open the project in IntelliJ IDEA.

Make sure you do the following configuration:

Configure Gradle JVM to Java 17

1. Go to File > Project Structure

2. Under Project SDK, select Java 17

3. Then, go to Settings > Build, Execution, Deployment > Build Tools > Gradle

4. Set Gradle JVM to the same Java 17 SDK

Note: If you don't set Java 17, you may run into class incompatibility or build failures (e.g., Unsupported class file major version 61).

📸 IntelliJ Gradle settings with Java 17

Once this is set up, you can run the Spring Boot app using the Gradle Task

Or if using the terminal:

./gradlew bootRun

The application should start on http://localhost:8080.

Step 3: Upload Your First Policy to OPA

We’ll upload a simple policy where only users with the ADMIN role are allowed using the ‘Create a new Policy’ API

Note: If using Postman, import the collection included in the repository into Postman & you can follow along using the endpoints mentioned here.

# Create a new policy
curl --location --request PUT 'http://localhost:8181/v1/policies/auth' \
--header 'Content-Type: text/plain' \
--data 'package auth

default allow = false

allow if {
  input.role == "ADMIN"
}'

# output
200 OK

You should get ‘200 OK’ response that indicates that the policy was uploaded successfully.

Note: This policy will be queried inside your app via the OpaService, which sends input (e.g., user role) to OPA and receives an allow/deny response.

Step 4: Verify the Policy with a Sample Input

Run the ‘Evaluate auth’ API to verify that the uploaded policy works by passing in a sample input:

# Evaluate auth
curl --location --request POST 'http://localhost:8181/v1/data/auth/allow' \
--header 'Content-Type: application/json' \
--data-raw '{
  "input": {
    "role": "REG_USER"
  }
}'

# output
{
    "result": {
        "allow": true
    }
}

This is what happens internally when you hit a protected endpoint — the user’s role is passed to OPA via OpaService.

Step 5: Register a New User

Let’s create a new user through the /signup endpoint:

# Signup
curl --location 'http://localhost:8080/api/v1/signup' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "Arun",
  "email": "arun@test.com",
  "password": "test1234"
}'

# output
{
    "id": "273aef4d-7f95-44d6-be4b-09788c8cdc71",
    "name": "Arun",
    "email": "arun@test.com",
    "role": "REG_USER"
}

The user is stored in PostgreSQL with the default role: REG_USER.

📸 User with REG_USER role in the database:

Step 6: Log In and Get Tokens

Authenticate with the new user to get JWT tokens:

curl --location 'http://localhost:8080/api/v1/auth/login' --header 'Content-Type: application/json' --data-raw '{
    "email": "arun@test.com",
    "password": "test1234"
}' -v
# output body
{
    "id": "c1340964-029a-4a08-aa4b-b08c786b59e8",
    "name": "Arun",
    "email": "arun@test.com",
    "role": "REG_USER"
}

# output headers
{
  ...
  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJyb2xlIjpbIlJFR19VU0VSIl0sInN1YiI6ImFydW5AdGVzdC5jb20iLCJpYXQiOjE3NDYzODQzMzYsImV4cCI6MTc0NjM4NDQ1Nn0.8xL0BQO3HJ5E0US4LqnZach3mRrAVADeluIF4ZXp0IM",
  "refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJyb2xlIjpbIlJFR19VU0VSIl0sInN1YiI6ImFydW5AdGVzdC5jb20iLCJpYXQiOjE3NDYzODQzMzYsImV4cCI6MTc0Njk4OTEzNn0.wW_9MH6Dtw2j3pHUTYuBhgQJLdAfcjrn1zO8s0N-rtA"
  ...
}

The JWTAuthenticationFilter parses this token and sets the user's identity in the security context.

Copy the ‘access_token’ from this step in the headers section as we will use it for the next section. This token will be used for the authorization checks.

Step 7: Try Accessing a Protected Endpoint

Now try hitting /api/v1/users with your access token:

curl --location 'http://localhost:8080/api/v1/users' \
--header 'Authorization: Bearer <your_access_token>'

Because you're a REG_USER, and our policy only allows ADMIN, you’ll get an error like:

{
  "message": "Access Denied"
}

Note: The CustomAuthorizationManager kicks in here and uses OpaService to verify authorization before continuing to the service method called by the controller.

Step 8: Update the Policy to Allow REG_USER

Let’s update the policy on-the-fly to allow users with the REG_USER role:

curl --location --request PUT 'http://localhost:8181/v1/policies/auth' \
--header 'Content-Type: text/plain' \
--data 'package auth

default allow = false

allow if {
  input.role == "REG_USER"
}'

No need to restart the app — OPA will now respond with true for REG_USER!

Step 9: Retry the /users Endpoint

Use your same access token again:

curl --location 'http://localhost:8080/api/v1/users' \
--header 'Authorization: Bearer <your_access_token>'

# output
[
    {
        "id": "c1340964-029a-4a08-aa4b-b08c786b59e8",
        "name": "Arun",
        "email": "arun@test.com",
        "role": "REG_USER"
    }
]

Now you should get a list of users!

📸 Postman screenshot:

Under the Hood: Custom Method-Level Authorization with OPA

In our application, we've implemented fine-grained, OPA-backed authorization at the method level using custom Spring Security expressions. Let’s break down the two key players:

CustomMethodSecurityExpressionRoot

public class CustomMethodSecurityExpressionRoot extends SecurityExpressionRoot implements MethodSecurityExpressionOperations {
    ...
    ...

    public boolean hasAuthorization(String authToken) {
        return opaService.checkPermission(authToken);
    }
}

This class is where custom logic for method security is injected. Specifically, it defines the method hasAuthorization, which is used in @PreAuthorize annotations like:

@PreAuthorize("hasAuthorization(#authToken)")
@GetMapping(produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<List<UserDTO>> findAll(
        @RequestHeader(Constants.AUTHORIZATION_HEADER) String authToken
) {
    List<User> users = userService.findAll();
    return new ResponseEntity<>(users.stream().map(UserDTO::mapToDto).toList(), HttpStatus.OK);
}

What this does:

• hasAuthorization(...) receives the bearer token from the incoming request.

• It delegates the actual permission check to the OpaService, which calls OPA to make a decision.

So this is your entry point into the OPA ecosystem for each protected endpoint.

OpaService: The Policy Decision Interface

@Service
@Slf4j
public class OpaService {
    ...
    public boolean checkPermission(String token) {
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        Map<String, Object> input = new HashMap<>();
        input.put(OPA_INPUT, Map.of(ROLE, jwtService.extractClaim(preParseToken(token), val -> val.get(ROLE, List.class)).get(0)));
        HttpEntity<Map<String, Object>> request = new HttpEntity<>(input, headers);
        ResponseEntity<Map> response = restTemplate.postForEntity(
            opaUrl + "/v1/data/auth",
            request,
            Map.class
        );

        if (response.getStatusCode() == HttpStatus.OK && response.getBody() != null) {
            return Boolean.TRUE.equals(((Map<String, String>)response.getBody().get(RESULT)).get(ALLOW));
        }
        return false;
    }
}

This service acts as the communication bridge between your Spring Boot app and the OPA server.

Let’s walk through what happens inside checkPermission(...) step by step:

Step 1: Clean the Token

private String preParseToken(String token) {
    return token.replace(BEARER_PREFIX, "");
}

Since bearer tokens often look like Bearer <JWT>, this method trims off the "Bearer " prefix so we get the raw JWT string.

Step 2: Extract the Role from JWT

jwtService.extractClaim(preParseToken(token), val -> val.get(ROLE, List.class)).get(0)

We:

• Decode the JWT using JWTService

• Pull out the role claim (which might be a list, like ["ADMIN"])

• Use only the first role for now (could be extended later)

This extracted role becomes part of the input sent to OPA.

Step 3: Build the OPA Input Payload

{
  "input": {
    "role": "ADMIN"
  }
}

This input is what the OPA policy will evaluate. It’s wrapped in a JSON map and sent with the request.

Step 4: Make the OPA Call

ResponseEntity<Map> response = restTemplate.postForEntity(
    opaUrl + "/v1/data/auth",
    request,
    Map.class
);

We POST the input to the OPA /v1/data/auth endpoint and wait for a decision.

Step 5: Interpret the Response

return Boolean.TRUE.equals(((Map<String, String>)response.getBody().get(RESULT)).get(ALLOW));

OPA responds with something like:

{
  "result": {
    "allow": true
  }
}

If "allow" is true, we return true — access granted.
If not, access is denied.

Connecting It All

Here’s how the flow works in practice:

1. User sends a request with a Bearer token.

2. Controller method is protected with @PreAuthorize("hasAuthorization(#authToken)")

3. CustomMethodSecurityExpressionRoot.hasAuthorization(...) is triggered.

4. OpaService.checkPermission(...) builds the input, queries OPA, and returns the result.

5. Based on the response, Spring either allows or blocks the request.

Flowchart

To better illustrate the flow, here's a visual representation of the authorization process:

sequenceDiagram
    participant User
    participant Controller
    participant CustomMethodSecurityExpressionRoot
    participant OpaService
    participant OPA

    User->>Controller: Sends request with Bearer token
    Controller->>CustomMethodSecurityExpressionRoot: @PreAuthorize("hasAuthorization(#authToken)")
    CustomMethodSecurityExpressionRoot->>OpaService: checkPermission(authToken)
    OpaService->>JWTService: extractClaim(token)
    JWTService-->>OpaService: role(s)
    OpaService->>OPA: POST /v1/data/auth with input.role
    OPA-->>OpaService: { "result": { "allow": true/false } }
    OpaService-->>CustomMethodSecurityExpressionRoot: true/false
    CustomMethodSecurityExpressionRoot-->>Controller: true/false
    Controller-->>User: Access granted/denied

This flowchart demonstrates the sequence of interactions between the components involved in the authorization process.

Wrapping It Up

You’ve now seen how to:

• Launch an OPA-backed system using Docker integrated with SpringBoot

• Write a Policy based authorization flow

• Update policies on the fly without downtime

Next up: Try writing more advanced policies that check for multiple roles, query database-backed attributes, or using policies to drive feature flags!

You can externalize and evolve policies without changing your code!

Got ideas or questions? Drop them in the comments! 💬