Identity Access Service - Run Book

Application Overview

The Identity Access Service is a Spring Boot application that provides:

• User authentication and authorization with JWT tokens
• User management with role-based access control
• Avatar generation and management
• gRPC and REST API endpoints
• PostgreSQL database integration

Prerequisites

System Requirements

• Java 17 or higher
• PostgreSQL 12+ running
• Maven 3.6+ (if building from source)
• Minimum 2GB RAM
• Minimum 5GB disk space

Environment Setup

1. Database Setup

   CREATE DATABASE identityaccess;
   CREATE USER postgres WITH PASSWORD 'YourNewSecurePassword123!';
   GRANT ALL PRIVILEGES ON DATABASE identityaccess TO postgres;
   

2. Environment Variables

   export JWT_SECRET=your_secure_jwt_secret_key_at_least_32_chars
   export ENCRYPTION_KEY=QR6MuXQaiWQk2EWsBDMUv9SaBAzP8Oe6bj/V+WVD9Ic=
   export DB_HOST=localhost
   export DB_PORT=5432
   export DB_NAME=identityaccess
   export DB_USERNAME=postgres
   export DB_PASSWORD=YourNewSecurePassword123!
   export HTTP_PORT=8080
   export GRPC_PORT=9090
   

Configuration Files

Application Profiles

The application supports multiple profiles:

• Default: application.yml - Main configuration
• Development: application-dev.yml - Development settings with debug logging
• Production: application-prod.yml - Production optimized settings
• Test: application-test.yml.bak - Test environment with H2 in-memory database

Key Configuration Settings

Database Configuration

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/identityaccess
    username: postgres
    password: YourNewSecurePassword123!
    driver-class-name: org.postgresql.Driver

Security Configuration

jwt:
  secret: ${JWT_SECRET:your_secure_jwt_secret_key_at_least_32_chars}
  expiration: 3600000  # 1 hour
  issuer: identity-access

encryption:
  key: QR6MuXQaiWQk2EWsBDMUv9SaBAzP8Oe6bj/V+WVD9Ic=

Avatar Configuration

avatar:
  storage:
    path: file:src/main/resources/static/avatars/
  static:
    path: /static/avatars/
  default:
    type: CARTOON
    engine: UNITY

Running the Application

Development Mode

# Using Maven
./mvnw spring-boot:run -Dspring-boot.run.profiles=dev

# Using Java
java -jar -Dspring.profiles.active=dev target/identity-access-service.jar

Production Mode

# Set required environment variables first
export JWT_SECRET=your_production_secret
export DB_PASSWORD=your_production_password

# Run application
java -jar -Dspring.profiles.active=prod target/identity-access-service.jar

Database Management

Schema Initialization

The application uses Flyway for database migrations. Migrations are located in:

• src/main/resources/db/migration/
• src/main/resources/com/wizdevtech/identityaccess/repository/db/migration/

Initial Schema

The schema.sql file creates:

• users table with email, password, enabled status
• roles table with role names
• user_roles join table for many-to-many relationship
• Default roles: ROLE_USER and ROLE_ADMIN

Service Health Checks

Health Endpoint

• URL: http://localhost:8080/actuator/health
• Response: JSON with application status

Database Connection

-- Check database connectivity
SELECT version();
SELECT * FROM pg_stat_activity WHERE datname = 'identityaccess';

Monitoring & Logging

Log Files

• Console output by default
• Production logs to: /var/log/identityaccess/application.log
• Log rotation: max 10MB per file, 7 days retention

Key Log Levels

logging:
  level:
    root: INFO
    com.wizdevtech: DEBUG
    org.springframework.security: INFO

Common Issues & Troubleshooting

Application Won't Start

1. Port Already in Use

   # Check what's using the port
   lsof -i :8080
   # Kill the process or change the port
   export HTTP_PORT=8081
   

2. Database Connection Failed

   • Verify PostgreSQL is running
   • Check connection credentials
   • Verify database exists
   • Check network connectivity

3. JWT Secret Missing

   export JWT_SECRET=a_very_long_and_secure_secret_key_here
   

Database Issues

1. Migration Failures

   # Check Flyway status
   ./mvnw flyway:info
   # Repair if needed
   ./mvnw flyway:repair
   

2. Schema Validation Errors

   • Ensure Flyway migrations are up to date
   • Check for manual schema changes
   • Verify table structure matches entity definitions

Avatar Generation Issues

1. Avatar Storage Path Not Found

   • Verify avatar.storage.path configuration
   • Ensure directory exists and is writable
   • Check file permissions

2. Avatar Upload Failures

   • Check file size limits (max 2MB)
   • Verify allowed file types (images only)
   • Ensure sufficient disk space

Security Considerations

JWT Token Management

• Tokens expire in 1 hour by default
• Store securely on client side (HttpOnly cookies recommended)
• Implement token refresh mechanism

Password Security

• Passwords are hashed using Spring Security's BCrypt
• Minimum password requirements should be enforced client-side

CORS Configuration

Update SecurityConfig.java to allow frontend domains:

.cors(cors -> cors.configurationSource(corsConfigurationSource()))

Backup & Recovery

Database Backup

# Create backup
pg_dump -h localhost -U postgres identityaccess > backup.sql

# Restore from backup
psql -h localhost -U postgres -d identityaccess < backup.sql

Configuration Backup

• Backup all .yml files
• Backup environment variable configurations
• Document any custom settings

Performance Tuning

Database Connection Pool

spring:
  datasource:
    hikari:
      maximum-pool-size: 10
      minimum-idle: 5
      idle-timeout: 30000

JVM Tuning

java -Xmx2g -Xms1g -XX:+UseG1GC -jar app.jar

Deployment Checklist

• All environment variables set
• Database accessible and configured
• JWT secret configured
• Encryption key set
• Avatar storage directory created
• Log directory created (production)
• Network security configured
• Health endpoints accessible
• SSL/TLS configured (production)

Contact Information

• Development Team: [team-email]
• Operations Team: [ops-email]
• Documentation: [wiki-link]
• Issue Tracking: [jira-link]