Skip to content

AUTHENTICATION_SETUP.md

Latest commit

 

History

History
486 lines (366 loc) · 9.19 KB

AUTHENTICATION_SETUP.md

File metadata and controls

486 lines (366 loc) · 9.19 KB

Authentication & SSO Setup

Complete authentication system with admin user, resource gates, and SSO integration

Admin Credentials

Username: kobalt
Password: afr0PhyZknodFactauryz1
Role: admin
Email: kobalt@hypergraph.dev

Quick Start

1. Restart Deployment with Authentication

cd /home/kobalts71-n--1/hypergraph_meta_cluster_bundle

# Stop and restart with authentication
bash scripts/restart-with-auth.sh

2. Initialize Authentication Manually

# After services are running
bash scripts/init-auth.sh

3. Access Admin Panel

Factory Admin: http://localhost:3000/admin
Username: kobalt
Password: afr0PhyZknodFactauryz1

SSO Configuration

Endpoints

  • Factory URL: http://localhost:3000
  • Arquolab URL: http://localhost:3101
  • Auth Callback: http://localhost:3000/auth/callback
  • SSO Issuer: https://hypergraph.dev/auth

OAuth2 Configuration

Client ID: hypergraph-meta-cluster
Client Secret: afr0PhyZknodFactauryz1_oauth2_secret
Redirect URI: http://localhost:3000/auth/callback

JWT Configuration

JWT Secret: afr0PhyZknodFactauryz1_jwt_secret_key_2025
JWT Expiry: 24h
Refresh Token Expiry: 7d

Authentication Workflow

1. Local Authentication

# Login with username/password
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "kobalt",
    "password": "afr0PhyZknodFactauryz1"
  }'

# Response:
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "...",
  "user": {
    "username": "kobalt",
    "role": "admin",
    "permissions": ["admin:*", "user:*", "resource:*"]
  }
}

2. SSO Authentication

# Step 1: Initiate SSO login
# Redirect user to: http://localhost:3000/auth/sso?provider=factory

# Step 2: Callback handling
# User is redirected to: http://localhost:3000/auth/callback?code=...&state=...

# Step 3: Exchange code for token
curl -X POST http://localhost:8000/api/auth/sso/callback \
  -H "Content-Type: application/json" \
  -d '{
    "code": "authorization_code",
    "state": "csrf_token"
  }'

3. Use JWT Token

# Make authenticated requests
curl http://localhost:8000/api/protected/resource \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Resource Gates

API Gateway

{
  "enabled": true,
  "requireAuth": true,
  "allowedRoles": ["admin", "user"],
  "rateLimit": {
    "requests": 100,
    "window": 60
  }
}

Bitcoin Service

{
  "enabled": true,
  "requireAuth": true,
  "allowedRoles": ["admin"],
  "requireApproval": true
}

Image Builder

{
  "enabled": true,
  "requireAuth": true,
  "allowedRoles": ["admin", "builder"],
  "requireApproval": true,
  "daoGated": true
}

YubiKey Manager

{
  "enabled": true,
  "requireAuth": true,
  "allowedRoles": ["admin", "security"],
  "requireHardwareAuth": true
}

User Management

Create New User

# Via API (requires admin token)
curl -X POST http://localhost:8000/api/admin/users \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "password": "secure_password",
    "email": "user@example.com",
    "role": "user"
  }'

Update User Role

curl -X PUT http://localhost:8000/api/admin/users/newuser/role \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "builder"
  }'

List Users

curl http://localhost:8000/api/admin/users \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Roles & Permissions

Admin

Permissions:
- admin:* (full admin access)
- user:* (manage users)
- resource:* (access all resources)
- api:* (full API access)
- sso:* (manage SSO)

Builder

Permissions:
- image:build (build images)
- image:list (list builds)
- image:download (download images)
- api:read (read-only API access)

User

Permissions:
- api:read (read-only API access)
- resource:read (read resources)
- user:self (manage own account)

Security

Permissions:
- yubikey:* (manage YubiKey)
- security:* (security operations)
- admin:read (view admin info)

CORS Configuration

# Allowed Origins
CORS_ORIGIN=http://localhost:3000,http://localhost:3101,http://localhost:8443

# Settings
CORS_CREDENTIALS=true
CORS_METHODS=GET,POST,PUT,DELETE,OPTIONS
CORS_HEADERS=Content-Type,Authorization,X-Requested-With

Rate Limiting

# Default Rate Limits
Rate Limit: 100 requests per 60 seconds

# Per-Role Limits
Admin: 1000 requests/minute
User: 100 requests/minute
Anonymous: 10 requests/minute

Environment Variables

All authentication settings are configured in .env.dev:

# Admin User
ADMIN_USER=kobalt
ADMIN_PASSWORD=afr0PhyZknodFactauryz1
ADMIN_ROLE=admin
ADMIN_EMAIL=kobalt@hypergraph.dev

# JWT Configuration
JWT_SECRET=afr0PhyZknodFactauryz1_jwt_secret_key_2025
JWT_REFRESH_SECRET=afr0PhyZknodFactauryz1_refresh_secret_key_2025
JWT_EXPIRY=24h
JWT_REFRESH_EXPIRY=7d

# SSO Configuration
SSO_ENABLED=true
SSO_ISSUER=https://hypergraph.dev/auth
SSO_CALLBACK_URL=http://localhost:3000/auth/callback
SSO_FACTORY_URL=http://localhost:3000
SSO_HYPERGRAPH_URL=http://localhost:8000
SSO_ARQUOLAB_URL=http://localhost:3101

# OAuth2 Configuration
OAUTH2_CLIENT_ID=hypergraph-meta-cluster
OAUTH2_CLIENT_SECRET=afr0PhyZknodFactauryz1_oauth2_secret
OAUTH2_REDIRECT_URI=http://localhost:3000/auth/callback

# Resource Gates
ENABLE_RESOURCE_GATES=true
ENABLE_API_AUTH=true
ENABLE_RATE_LIMITING=true
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=60

# CORS
CORS_ORIGIN=http://localhost:3000,http://localhost:3101,http://localhost:8443
CORS_CREDENTIALS=true

Troubleshooting

Authentication Fails

# Check if services are running
docker ps | grep deploy_

# Check API Gateway logs
docker logs deploy_api-gateway_1

# Verify environment variables
docker exec deploy_api-gateway_1 env | grep -E "ADMIN|JWT|SSO"

# Test direct MongoDB connection
mongosh "mongodb://factory_app:179646f5633bfbc74d372fffd3ddcbbb@localhost:27017/factory"

SSO Not Working

# Verify SSO configuration
cat config/auth/sso-config.json

# Check callback URL
curl -v http://localhost:3000/auth/callback

# Verify OAuth2 credentials
grep OAUTH2 .env.dev

Resource Gate Errors

# Check resource gates configuration
cat /tmp/resource-gates.json

# Test with admin token
TOKEN=$(cat /tmp/hypergraph-admin-token.txt)
curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/protected/resource

Security Best Practices

  1. Change Default Passwords

    # Update admin password in .env.dev
ADMIN_PASSWORD=<strong_password>

  2. Use HTTPS in Production

    # Update callback URLs to use HTTPS
SSO_CALLBACK_URL=https://hypergraph.dev/auth/callback

  3. Rotate Secrets Regularly

    # Generate new JWT secrets
JWT_SECRET=$(openssl rand -hex 32)
JWT_REFRESH_SECRET=$(openssl rand -hex 32)

  4. Enable YubiKey Authentication

    # Require hardware authentication for admin
REQUIRE_HARDWARE_AUTH=true

  5. Monitor Authentication Logs

    docker logs -f deploy_api-gateway_1 | grep "auth"

API Endpoints

Authentication

POST   /api/auth/register          - Register new user
POST   /api/auth/login             - Login with username/password
POST   /api/auth/logout            - Logout
POST   /api/auth/refresh           - Refresh JWT token
GET    /api/auth/me                - Get current user info
POST   /api/auth/password/change   - Change password
POST   /api/auth/password/reset    - Reset password

SSO

GET    /api/auth/sso?provider=factory    - Initiate SSO login
POST   /api/auth/sso/callback            - SSO callback handler
GET    /api/auth/sso/status              - Check SSO status
POST   /api/auth/sso/logout              - SSO logout

Admin

GET    /api/admin/users               - List all users
POST   /api/admin/users               - Create user
PUT    /api/admin/users/:id           - Update user
DELETE /api/admin/users/:id           - Delete user
PUT    /api/admin/users/:id/role      - Update user role
GET    /api/admin/stats               - Get system stats

Quick Commands

# Restart with authentication
bash scripts/restart-with-auth.sh

# Initialize authentication only
bash scripts/init-auth.sh

# Stop deployment
ENV_PROFILE=dev docker-compose -f deploy/docker-compose.hypergraph.yml down

# View logs
docker-compose -f deploy/docker-compose.hypergraph.yml logs -f api-gateway

# Get admin token
cat /tmp/hypergraph-admin-token.txt

# Test authentication
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"kobalt","password":"afr0PhyZknodFactauryz1"}'

Status

  • ✅ Admin user configured
  • ✅ JWT authentication enabled
  • ✅ SSO to Factory and Arquolab
  • ✅ Resource gates configured
  • ✅ Rate limiting enabled
  • ✅ CORS protection enabled
  • ✅ Role-based access control

Last Updated: 2025-01-29 Version: 1.0.0

Built with ❤️ for the Hypergraph Meta-Cluster