Oauth2 Authorization Server

by musabbozkurt

6 stars

416 downloads

Not rated

GitHub

Database

About

OAuth2 Authorization Server with MariaDB, Docker OpenTelemetry LGTM, and Redis Integrations with Spring Boot 4, Java 25 and Docker. Integration Tests with Testcontainers and unit Tests with Junit 5, and Mockito

Details

Author: musabbozkurt
GitHub stars: 6
Downloads: 416
Categories: Database

- OAuth2 authorization with Spring Boot 4 and Java 25
- Multiple authentication providers (LDAP, database, default users)
- Integration with Redis, MariaDB, and Ollama AI models
- Docker, GraalVM native images, and CRaC support
- Actuator endpoints and Grafana monitoring
- AI model testing via Docker Desktop Model Runner

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Oauth2 Authorization Server

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "oauth2 authorization server": {
            "oauth2-authorization-server": {
                "command": "docker",
                "args": [
                    "compose",
                    "--profile",
                    "start_application",
                    "up",
                    "-d",
                    "--build"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "oauth2 authorization server": {
            "oauth2-authorization-server": {
                "command": "docker",
                "args": [
                    "compose",
                    "--profile",
                    "start_application",
                    "up",
                    "-d",
                    "--build"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "oauth2 authorization server": {
            "oauth2-authorization-server": {
                "command": "docker",
                "args": [
                    "compose",
                    "--profile",
                    "start_application",
                    "up",
                    "-d",
                    "--build"
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "oauth2 authorization server": {
            "oauth2-authorization-server": {
                "command": "docker",
                "args": [
                    "compose",
                    "--profile",
                    "start_application",
                    "up",
                    "-d",
                    "--build"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "oauth2 authorization server": {
            "oauth2-authorization-server": {
                "command": "docker",
                "args": [
                    "compose",
                    "--profile",
                    "start_application",
                    "up",
                    "-d",
                    "--build"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "oauth2 authorization server": {
            "oauth2-authorization-server": {
                "command": "docker",
                "args": [
                    "compose",
                    "--profile",
                    "start_application",
                    "up",
                    "-d",
                    "--build"
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "oauth2 authorization server": {
            "oauth2-authorization-server": {
                "command": "docker",
                "args": [
                    "compose",
                    "--profile",
                    "start_application",
                    "up",
                    "-d",
                    "--build"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "oauth2 authorization server": {
            "oauth2-authorization-server": {
                "command": "docker",
                "args": [
                    "compose",
                    "--profile",
                    "start_application",
                    "up",
                    "-d",
                    "--build"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "oauth2 authorization server": {
            "oauth2-authorization-server": {
                "command": "docker",
                "args": [
                    "compose",
                    "--profile",
                    "start_application",
                    "up",
                    "-d",
                    "--build"
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "oauth2 authorization server": {
            "oauth2-authorization-server": {
                "command": "docker",
                "args": [
                    "compose",
                    "--profile",
                    "start_application",
                    "up",
                    "-d",
                    "--build"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "oauth2 authorization server": {
            "oauth2-authorization-server": {
                "command": "docker",
                "args": [
                    "compose",
                    "--profile",
                    "start_application",
                    "up",
                    "-d",
                    "--build"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "oauth2 authorization server": {
            "oauth2-authorization-server": {
                "command": "docker",
                "args": [
                    "compose",
                    "--profile",
                    "start_application",
                    "up",
                    "-d",
                    "--build"
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "oauth2 authorization server": {
            "oauth2-authorization-server": {
                "command": "docker",
                "args": [
                    "compose",
                    "--profile",
                    "start_application",
                    "up",
                    "-d",
                    "--build"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "oauth2 authorization server": {
            "oauth2-authorization-server": {
                "command": "docker",
                "args": [
                    "compose",
                    "--profile",
                    "start_application",
                    "up",
                    "-d",
                    "--build"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "oauth2 authorization server": {
            "oauth2-authorization-server": {
                "command": "docker",
                "args": [
                    "compose",
                    "--profile",
                    "start_application",
                    "up",
                    "-d",
                    "--build"
                ]
            }
        }
    }
}

From the repository

Install Java 25, Maven, and Docker. Set environment variables for AI model API keys (optional). Run tests with mvn clean verify. Start the application with docker compose --profile start_application up -d --build or using ./mvnw spring-boot:run after starting infrastructure services. Access Swagger UI at http://localhost:9000/swagger-ui/index.html with client ID client and secret secret, and login with default users (Developer/password, Admin/password, User/password).

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "oauth2 authorization server": {
            "oauth2-authorization-server": {
                "command": "docker",
                "args": [
                    "compose",
                    "--profile",
                    "start_application",
                    "up",
                    "-d",
                    "--build"
                ]
            }
        }
    }
}

McpServers

{
    "oauth2-authorization-server": {
        "command": "docker",
        "args": [
            "compose",
            "--profile",
            "start_application",
            "up",
            "-d",
            "--build"
        ]
    }
}

OAuth2 Authorization Server with Spring Boot 4 and Java 25

Prerequisites

- Java 25 should be installed --> export JAVA_HOME=$(/usr/libexec/java_home -v 25)
- Maven should be installed
- Docker should be installed
- Postman can be installed

How to Run and Test

- Run the following commands to set environment variables for AI model API keys
-

        export OPENAI_API_KEY=your_api_key_here

        export DEEPSEEK_API_KEY=your_api_key_here

        export ANTHROPIC_API_KEY=your_api_key_here      # Optional

        export GOOGLE_GENAI_API_KEY=your_api_key_here   # Optional

    cd oauth2-authorization-server

    

    # Run tests on the host (requires Docker for Testcontainers)

    mvn clean verify

    

    # Build and start the application together with all infrastructure services

    docker compose --profile start_application up -d --build

    

    # Start only infrastructure services (Redis, MariaDB, LDAP, Ollama, etc.)

    docker compose up -d

    

    # For local development without Docker (requires infrastructure services running via docker compose up -d)

    ./mvnw spring-boot:run   # or: mvn spring-boot:run

- Import the followings to test in Postman
- OAuth2 Authorization Server.postman_collection.json
- OAuth2 Authorization Server.postman_environment.json
- Swagger: http://localhost:9000/swagger-ui/index.html
- Click Authorize and enter the following credentials
- client_id: client
- client_secret: secret
- Use one of the following default values to log in http://localhost:9000/login
- username: Developer password: password
- username: Admin password: password
- username: User password: password
- Actuator: http://localhost:9000/actuator/
- Database credentials
- url: jdbc:mariadb://localhost:3306/oauth2_authorization_server
- username: mb_test
- password: test
- Redis
- host: localhost
- port: 6379
- Redis Insight: http://localhost:5540/
- Click Add Redis database
- Connection URL --> redis://default@host.docker.internal:6379
- Click Add Database
-
- Ollama
- http://localhost:3000/ sign up for an account for local environment
- Search for mxbai-embed-large and download it if it does not exist
- Search for mistral and download it if it does not exist
- Search for deepseek-r1:7b and download it if it does not exist
- Grafana UI
- http://localhost:3001/
- username: admin
- password: admin

Debugging Spring Boot Tests in IntelliJ IDEA

1. Run one of the below commands in the terminal
- mvn test -Dmaven.surefire.debug
- If port 5005 is already in use, you can specify a custom port
- mvn test -Dmaven.surefire.debug="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000"
2. Open IntelliJ IDEA
3. Go to Run > Attach to Process (or use shortcut)
- Windows/Linux: Ctrl + Alt + 5
- Mac: Cmd + Alt + 5
4. Select the Java process running your tests
5. The test will pause until you connect your debugger. Once connected, you can use breakpoints and step through your
code.

How to Run and Test with CDC(Class Data Sharing)

- Java 25+ should be installed
- Run ./mvnw clean install or./mvnw clean install -Paot or ./mvnw -Paot package command to build the application
with AOT
- Run docker-compose up -d command to run necessary services
- Run docker build -t oauth2-authorization-server -f DockerfileForAOTCache . command to build the image
- Run docker run -d --restart=always -p 9000:9000 oauth2-authorization-server:latest command to run the image

How to Run and Test Native Image with GraalVM

- Java 25 GraalVM edition should be installed
- Run docker-compose up -d command to run necessary services
- Run ./mvnw -Pnative native:compile or ./mvnw -Pnative native:compile -DskipTests command to build the native image
- Run ./target/oauth2-authorization-server command to run the native image
- Install Grype (OPTIONAL)
- Run native-image-inspect ./target/oauth2-authorization-server-0.0.1 | grype -v command to scan vulnerabilities
- Run native-image-inspect ./target/oauth2-authorization-server-0.0.1 >output.json command and open output.json or
visit http://localhost:9000/actuator/sbom/native-image to inspect all libraries, methods etc. used in the native image
- Run open ./target/oauth2-authorization-server-build-report.html to see build report
- Use Swagger UI to test the application

Spring Boot with CRaC(Coordinated Restore at Checkpoint) by Creating Ready to Restore Container Image.

- Warning: for real projects make sure to not leak sensitive data in CRaC files since they contain a snapshot of the
memory of the running JVM instance.
- Checkpoint
- Run
on demand checkpoint/restore of a running application
with: ./docs/scripts/checkpoint.sh
- Run
an automatic checkpoint/restore at startup
with: ./docs/scripts/checkpointOnRefresh.sh
- Restore
- Restore the application with: ./docs/scripts/restore.sh
- Use Swagger UI to test the application

How to Run and Test AI Models Locally with Docker Desktop Model Runner

- Requires: Docker Desktop 4.40 and later
- Run docker-compose up -d command to run necessary services
- Run docker model pull ai/gemma3:4B-Q4_K_M command to pull the model
- Run docker model run ai/gemma3:4B-Q4_K_M command to run the model to test it from the command line (OPTIONAL)
- Docker Desktop --> Settings --> Features in development --> Beta features --> Enable Docker Model Runner -->
Enable host-side TCP support --> Apply & Restart
-
- Run mvn test or mvn clean install or mvn clean package or ./mvnw clean install command to run all the tests
- Run mvn spring-boot:run command to run the application
- Use Swagger UI to test the application

Dependency Version Management

Dependency versions are managed via
the Maven Versions Plugin and a version-rules.xml filter
that excludes alpha/beta/RC/SNAPSHOT releases.

Local — using the helper script:

./docs/scripts/update-versions.sh check           # Show all outdated versions (parent + props + deps + plugins)
./docs/scripts/update-versions.sh update          # Auto-update everything and review with: git diff pom.xml
./docs/scripts/update-versions.sh update-props    # Update only <properties> versions (safest)
./docs/scripts/update-versions.sh update-parent   # Update only spring-boot-starter-parent
./docs/scripts/update-versions.sh revert          # Revert pom.xml from backup

CI/CD — automated PR creation:

The MB Dependency Version Update workflow runs every Monday (and on-demand),
checks for updates, verifies the build compiles, and creates a PR automatically.