Skip to main content

​
Environment Variables

The Authorization Service requires several environment variables to be configured before deployment. These variables control database connectivity, JWT security, and logging behavior.

​
Required Variables

​
Database Configuration

DB_NAME=autorization_db
DB_USERNAME=postgres
DB_PASSWORD=your_secure_password
The service uses PostgreSQL as its primary database. The connection string is automatically constructed as: 
jdbc:postgresql://localhost:5432/${DB_NAME}?options=-c%20TimeZone=America/Lima
Note: The timezone is set to America/Lima by default. Modify application.properties if you need a different timezone.

​
JWT Configuration

JWT_SECRET=your_base64_encoded_secret_key_at_least_256_bits_long
JWT_EXPIRATION_MS=3600000
  • JWT_SECRET: Must be a strong secret key. For HS256 algorithm, use at least 256 bits (32 bytes). Consider using a Base64-encoded random string.
  • JWT_EXPIRATION_MS: Token expiration time in milliseconds. Default is 3600000 (1 hour).
The JWT_SECRET is critical for security. Never commit this value to version control. Use environment-specific secrets management.

​
Setting Environment Variables

​
PowerShell (Windows)

$env:DB_NAME = 'autorization_db'
$env:DB_USERNAME = 'postgres'
$env:DB_PASSWORD = 'admin'
$env:JWT_SECRET = 'TU_SECRET_KEY_BASE64_MUY_LARGA_Y_SEGURA'
$env:JWT_EXPIRATION_MS = '3600000'

​
Bash (Linux/macOS)

export DB_NAME=autorization_db
export DB_USERNAME=postgres
export DB_PASSWORD=admin
export JWT_SECRET=TU_SECRET_KEY_BASE64_MUY_LARGA_Y_SEGURA
export JWT_EXPIRATION_MS=3600000

​
Docker Environment

version: '3.8'
services:
  authorization-service:
    image: authorization-service:latest
    environment:
      - DB_NAME=autorization_db
      - DB_USERNAME=postgres
      - DB_PASSWORD=${DB_PASSWORD}
      - JWT_SECRET=${JWT_SECRET}
      - JWT_EXPIRATION_MS=3600000
    ports:
      - "8080:8080"

​
Application Properties

The service uses application.properties for Spring Boot configuration. Key properties include:

​
Database Settings

spring.datasource.url=jdbc:postgresql://localhost:5432/${DB_NAME}?options=-c%20TimeZone=America/Lima
spring.datasource.username=${DB_USERNAME}
spring.datasource.password=${DB_PASSWORD}
spring.datasource.driver-class-name=org.postgresql.Driver

​
JPA/Hibernate Settings

spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true
  • ddl-auto=update: Automatically updates the database schema. For production, consider using validate or managing migrations with Flyway/Liquibase.
  • show-sql=true: Logs SQL statements. Disable in production for better performance.

​
Logging Configuration

app.logs.dir=logs
Specifies the directory where application logs are stored. The service uses a custom audit logging system that writes to this directory.

​
Database Setup

​
Prerequisites

  • PostgreSQL 12 or higher
  • Database user with CREATE, ALTER, and SELECT privileges

​
Initial Setup

  1. Create the database:
CREATE DATABASE autorization_db;
  1. Create a dedicated user (recommended for production):
CREATE USER auth_service WITH PASSWORD 'secure_password';
GRANT ALL PRIVILEGES ON DATABASE autorization_db TO auth_service;
  1. Configure timezone (if needed):
ALTER DATABASE autorization_db SET timezone TO 'America/Lima';

​
Schema Management

The application uses Hibernate’s ddl-auto=update mode, which automatically creates and updates tables based on JPA entities. On first run, the following tables will be created:
  • users - User accounts
  • roles - User roles (ADMIN, USER, etc.)
  • permissions - Fine-grained permissions
  • modules - System modules for permission grouping
  • user_roles - Many-to-many relationship
  • role_permissions - Many-to-many relationship
  • activity_logs - Audit trail

​
Security Configuration

The service implements Spring Security 6 with JWT-based authentication. Key security features:

​
Session Management

The application is stateless and does not use HTTP sessions: 
session.sessionCreationPolicy(SessionCreationPolicy.STATELESS)

​
Public Endpoints

The following endpoints are publicly accessible:
  • POST /api/users - User registration
  • POST /api/auth/** - Authentication endpoints (login, token refresh)
  • /swagger-ui/** - API documentation
  • /v3/api-docs/** - OpenAPI specification

​
Password Encoding

Passwords are hashed using BCrypt with default strength (10 rounds): 
@Bean
public PasswordEncoder passwordEncoder() {
    return new BCryptPasswordEncoder();
}

​
Running the Application

​
Development Mode

./mvnw spring-boot:run

​
Production Build

# Build without tests
./mvnw clean package -DskipTests

# Run the JAR
java -jar target/autorization-module-0.0.1-SNAPSHOT.jar

​
Verifying Configuration

After starting the service, verify the configuration:
  1. Check application logs for successful database connection
  2. Access Swagger UI at http://localhost:8080/swagger-ui.html
  3. Test the health endpoint (if configured)
  4. Verify JWT token generation by calling /api/auth/login

​
Troubleshooting

​
Database Connection Issues

Problem: Connection refused or Authentication failed Solution:
  • Verify PostgreSQL is running: pg_isready
  • Check database credentials in environment variables
  • Ensure PostgreSQL accepts connections on port 5432
  • Check pg_hba.conf for authentication settings

​
JWT Token Issues

Problem: Invalid JWT signature or JWT expired Solution:
  • Verify JWT_SECRET is set correctly and matches across all service instances
  • Ensure JWT_SECRET is at least 256 bits for HS256 algorithm
  • Check system time synchronization (JWT validation is time-sensitive)
  • Adjust JWT_EXPIRATION_MS if tokens expire too quickly

​
Schema Update Failures

Problem: Hibernate fails to update schema Solution:
  • Check database user has ALTER privileges
  • Review logs for specific SQL errors
  • Consider using validate mode and manual migrations for production

​
Performance Tuning

​
Database Connection Pool

For production deployments, configure HikariCP (default in Spring Boot): 
spring.datasource.hikari.maximum-pool-size=10
spring.datasource.hikari.minimum-idle=5
spring.datasource.hikari.connection-timeout=30000

​
JPA Optimization

spring.jpa.show-sql=false
spring.jpa.properties.hibernate.format_sql=false
spring.jpa.properties.hibernate.jdbc.batch_size=20

​
Next Steps

Security Best Practices

Learn about JWT secrets, password policies, and HTTPS configuration

Error Handling

Understand the error response format and common error scenarios

Build docs developers (and LLMs) love

Get started for freeTalk to us