pos-system/services/iam-service/docs/QUICK_START.md

Quick Start Guide

🚀 Getting Started

1. Install Dependencies

pnpm install

2. Setup Environment

cp env.local.example .env.local
# Edit .env.local with your configuration

3. Setup Database

# Generate Prisma Client
pnpm prisma:generate

# Run migrations
pnpm prisma:migrate

# Seed database (creates admin user)
pnpm prisma:seed

4. Start Development Server

pnpm dev

Service will start on http://localhost:3001

📝 Default Credentials

After seeding:

• Admin: admin@goodgo.com / admin123
• Test User: test@goodgo.com / test123

🔑 API Testing

The IAM Service provides 50+ endpoints across 10 modules. Here are quick examples for the main modules:

Authentication Module

curl -X POST http://localhost:3001/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!"
  }'

Login

curl -X POST http://localhost:3001/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@goodgo.com",
    "password": "admin123"
  }'

Get Current User

curl -X GET http://localhost:3001/api/v1/auth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Check Permissions

curl -X GET "http://localhost:3001/api/v1/rbac/permissions/check?resource=users&action=read&scope=all" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Identity Management Module

Manage users, profiles, organizations, and groups:

# List users
curl -X GET http://localhost:3001/api/v1/identity/users \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Get user profile
curl -X GET http://localhost:3001/api/v1/identity/users/{userId}/profile \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Access Management Module

Handle access requests, reviews, and analytics:

# Create access request
curl -X POST http://localhost:3001/api/v1/access/requests \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "users",
    "action": "write",
    "scope": "all",
    "reason": "Need access to manage users"
  }'

# List access requests
curl -X GET http://localhost:3001/api/v1/access/requests \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Governance & Compliance Module

Compliance reporting, risk management, and policy templates:

# Get risk scores
curl -X GET http://localhost:3001/api/v1/governance/risk/scores \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# List compliance reports
curl -X GET http://localhost:3001/api/v1/governance/compliance/reports \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

For complete API documentation, see API Reference.

🔐 Social Login Setup

Google OAuth

1. Go to Google Cloud Console
2. Create OAuth 2.0 credentials
3. Add to .env.local:

   GOOGLE_CLIENT_ID=your-client-id
   GOOGLE_CLIENT_SECRET=your-client-secret
   GOOGLE_REDIRECT_URI=http://localhost:3001/api/v1/auth/google/callback
   

Facebook OAuth

1. Go to Facebook Developers
2. Create App and get credentials
3. Add to .env.local:

   FACEBOOK_APP_ID=your-app-id
   FACEBOOK_APP_SECRET=your-app-secret
   FACEBOOK_REDIRECT_URI=http://localhost:3001/api/v1/auth/facebook/callback
   

GitHub OAuth

1. Go to GitHub Settings > Developer settings > OAuth Apps
2. Create new OAuth App
3. Add to .env.local:

   GITHUB_CLIENT_ID=your-client-id
   GITHUB_CLIENT_SECRET=your-client-secret
   GITHUB_REDIRECT_URI=http://localhost:3001/api/v1/auth/github/callback
   

🔒 MFA Setup

Enable TOTP

1. Call POST /api/v1/mfa/totp/enable to get QR code
2. Scan QR code with authenticator app (Google Authenticator, Authy, etc.)
3. Call POST /api/v1/mfa/totp/verify with token from app

📊 Health Checks

• GET /health - Basic health check
• GET /health/ready - Readiness probe (checks database)
• GET /health/live - Liveness probe

🐳 Docker Deployment

cd ../../deployments/local
docker-compose up -d iam-service

📚 Documentation

• See README.md for full documentation
• See IMPLEMENTATION.md for implementation details
• API docs available at /api-docs when running

🛠️ Troubleshooting

Database Connection Issues

• Check DATABASE_URL in .env.local
• Ensure database is running
• Run pnpm prisma:generate if schema changed

Redis Connection Issues

• Check REDIS_URL in .env.local
• Ensure Redis is running
• Default: redis://localhost:6379

JWT Errors

• Ensure JWT_SECRET is set in .env.local
• Use strong, random secrets in production
• Never commit secrets to git