Skip to main content
Get your Authorization Service running and generate your first JWT token in under 5 minutes.

​
Prerequisites

Before you begin, ensure you have:
  • JDK 21 installed and configured
  • PostgreSQL running on port 5432
  • Maven (or use the included Maven wrapper)

​
Quick Setup

1

Clone and Navigate

Clone the repository and navigate to the project directory:
cd authorization-service
2

Create Database

Create a PostgreSQL database for the service:
CREATE DATABASE autorization_db;
3

Configure Environment Variables

Set up the required environment variables:
export SPRING_DATASOURCE_URL="jdbc:postgresql://localhost:5432/autorization_db"
export SPRING_DATASOURCE_USERNAME="postgres"
export SPRING_DATASOURCE_PASSWORD="your_password"
export JWT_SECRET="your-base64-encoded-secret-key-at-least-256-bits-long"
export JWT_EXPIRATION_MS="86400000"
The JWT_SECRET must be a Base64-encoded string of at least 256 bits. The JWT_EXPIRATION_MS is in milliseconds (86400000 = 24 hours).
4

Build and Run

Build and start the service:
./mvnw spring-boot:run
The service will start on http://localhost:8080
5

Verify Installation

Check that the service is running by accessing the Swagger UI:
http://localhost:8080/swagger-ui.html
You should see the interactive API documentation.

​
Get Your First JWT Token

Now that the service is running, let’s authenticate and get a JWT token.
On first run with spring.jpa.hibernate.ddl-auto=update, the database schema will be created automatically. You may need to insert a test user into the database or use your database initialization script.

​
Login Request

Send a POST request to the login endpoint:
cURL
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@empresa.com",
    "password": "password123"
  }'

​
Response

You’ll receive a JWT token in the response: 
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

​
Use the Token

Include the token in subsequent requests: 
curl -X GET http://localhost:8080/api/users \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Next Steps

Installation Guide

Detailed setup instructions including database initialization and production configuration

API Reference

Complete API documentation for all endpoints

Authentication

Learn about JWT tokens, roles, and permissions

Architecture

Understand the hexagonal architecture and project structure

​
Common Issues

Ensure PostgreSQL is running:
# Check if PostgreSQL is running
sudo systemctl status postgresql

# Start PostgreSQL if needed
sudo systemctl start postgresql
Verify your connection settings match your PostgreSQL configuration.
If you see errors related to JWT secret key strength:
  • The key must be Base64-encoded
  • Minimum length: 256 bits (32 bytes)
  • Generate a secure key:
openssl rand -base64 32
This typically means:
  • Invalid credentials
  • User account is inactive
  • User doesn’t exist in the database
Check the application logs for details and verify the user exists with:
SELECT email, status FROM users;

​
What’s Happening Under the Hood

When you start the service:
  1. Database Schema Creation: Hibernate creates the required tables based on JPA entities
  2. Security Configuration: Spring Security filters are initialized with JWT authentication
  3. API Documentation: Swagger UI is configured at /swagger-ui.html
  4. Audit System: AOP aspects are registered for automatic activity logging
The service uses a Hexagonal Architecture (Ports & Adapters) pattern, separating:
  • Domain: Pure business logic with no framework dependencies
  • Application: Use case implementations and DTOs
  • Adapters: REST controllers (in) and JPA repositories (out)

Build docs developers (and LLMs) love

Get started for freeTalk to us