# Authentication Layer Implementation Guide\n\n**Version**: 1.0.0\n**Date**: 2025-10-09\n**Status**: Production Ready\n\n---\n\n## Overview\n\nA comprehensive authentication layer has been integrated into the provisioning system to\nsecure sensitive operations. The system uses `nu_plugin_auth` for JWT authentication with\nMFA support, providing enterprise-grade security with graceful user experience.\n\n---\n\n## Key Features\n\n### ✅ **JWT Authentication**\n\n- RS256 asymmetric signing\n- Access tokens (15 min) + refresh tokens (7 d)\n- OS keyring storage (macOS Keychain, Windows Credential Manager, Linux Secret Service)\n\n### ✅ **MFA Support**\n\n- TOTP (Google Authenticator, Authy)\n- WebAuthn/FIDO2 (YubiKey, Touch ID)\n- Required for production and destructive operations\n\n### ✅ **Security Policies**\n\n- **Production environment**: Requires authentication + MFA\n- **Destructive operations**: Requires authentication + MFA (delete, destroy)\n- **Development/test**: Requires authentication, allows skip with flag\n- **Check mode**: Always bypasses authentication (dry-run operations)\n\n### ✅ **Audit Logging**\n\n- All authenticated operations logged\n- User, timestamp, operation details\n- MFA verification status\n- JSON format for easy parsing\n\n### ✅ **User-Friendly Error Messages**\n\n- Clear instructions for login/MFA\n- Distinct error types (platform auth vs provider auth)\n- Helpful guidance for setup\n\n---\n\n## Quick Start\n\n### 1. Login to Platform\n\n```\n# Interactive login (password prompt)\nprovisioning auth login <username>\n\n# Save credentials to keyring\nprovisioning auth login <username> --save\n\n# Custom control center URL\nprovisioning auth login admin --url http://control.example.com:9080\n```\n\n### 2. Enroll MFA (First Time)\n\n```\n# Enroll TOTP (Google Authenticator)\nprovisioning auth mfa enroll totp\n\n# Scan QR code with authenticator app\n# Or enter secret manually\n```\n\n### 3. Verify MFA (For Sensitive Operations)\n\n```\n# Get 6-digit code from authenticator app\nprovisioning auth mfa verify --code 123456\n```\n\n### 4. Check Authentication Status\n\n```\n# View current authentication status\nprovisioning auth status\n\n# Verify token is valid\nprovisioning auth verify\n```\n\n---\n\n## Protected Operations\n\n### Server Operations\n\n```\n# ✅ CREATE - Requires auth (prod: +MFA)\nprovisioning server create web-01                    # Auth required\nprovisioning server create web-01 --check            # Auth skipped (check mode)\n\n# ❌ DELETE - Requires auth + MFA\nprovisioning server delete web-01                    # Auth + MFA required\nprovisioning server delete web-01 --check            # Auth skipped (check mode)\n\n# 📖 READ - No auth required\nprovisioning server list                             # No auth required\nprovisioning server ssh web-01                       # No auth required\n```\n\n### Task Service Operations\n\n```\n# ✅ CREATE - Requires auth (prod: +MFA)\nprovisioning taskserv create kubernetes              # Auth required\nprovisioning taskserv create kubernetes --check      # Auth skipped\n\n# ❌ DELETE - Requires auth + MFA\nprovisioning taskserv delete kubernetes              # Auth + MFA required\n\n# 📖 READ - No auth required\nprovisioning taskserv list                           # No auth required\n```\n\n### Cluster Operations\n\n```\n# ✅ CREATE - Requires auth (prod: +MFA)\nprovisioning cluster create buildkit                 # Auth required\nprovisioning cluster create buildkit --check         # Auth skipped\n\n# ❌ DELETE - Requires auth + MFA\nprovisioning cluster delete buildkit                 # Auth + MFA required\n```\n\n### Batch Workflows\n\n```\n# ✅ SUBMIT - Requires auth (prod: +MFA)\nprovisioning batch submit workflow.ncl               # Auth required\nprovisioning batch submit workflow.ncl --skip-auth   # Auth skipped (if allowed)\n\n# 📖 READ - No auth required\nprovisioning batch list                              # No auth required\nprovisioning batch status <task-id>                  # No auth required\n```\n\n---\n\n## Configuration\n\n### Security Settings (`config.defaults.toml`)\n\n```\n[security]\nrequire_auth = true  # Enable authentication system\nrequire_mfa_for_production = true  # MFA for prod environment\nrequire_mfa_for_destructive = true  # MFA for delete operations\nauth_timeout = 3600  # Token timeout (1 hour)\naudit_log_path = "{{paths.base}}/logs/audit.log"\n\n[security.bypass]\nallow_skip_auth = false  # Allow PROVISIONING_SKIP_AUTH env var\n\n[plugins]\nauth_enabled = true  # Enable nu_plugin_auth\n\n[platform.control_center]\nurl = "http://localhost:9080"  # Control center URL\n```\n\n### Environment-Specific Configuration\n\n```\n# Development\n[environments.dev]\nsecurity.bypass.allow_skip_auth = true  # Allow auth bypass in dev\n\n# Production\n[environments.prod]\nsecurity.bypass.allow_skip_auth = false  # Never allow bypass\nsecurity.require_mfa_for_production = true\n```\n\n---\n\n## Authentication Bypass (Dev/Test Only)\n\n### Environment Variable Method\n\n```\n# Export environment variable (dev/test only)\nexport PROVISIONING_SKIP_AUTH=true\n\n# Run operations without authentication\nprovisioning server create web-01\n\n# Unset when done\nunset PROVISIONING_SKIP_AUTH\n```\n\n### Per-Command Flag\n\n```\n# Some commands support --skip-auth flag\nprovisioning batch submit workflow.ncl --skip-auth\n```\n\n### Check Mode (Always Bypasses Auth)\n\n```\n# Check mode is always allowed without auth\nprovisioning server create web-01 --check\nprovisioning taskserv create kubernetes --check\n```\n\n⚠️ **WARNING**: Auth bypass is ONLY for development/testing. Production systems must have\n`security.bypass.allow_skip_auth = false`.\n\n---\n\n## Error Messages\n\n### Not Authenticated\n\n```\n❌ Authentication Required\n\nOperation: server create web-01\nYou must be logged in to perform this operation.\n\nTo login:\n   provisioning auth login <username>\n\nNote: Your credentials will be securely stored in the system keyring.\n```\n\n**Solution**: Run `provisioning auth login <username>`\n\n---\n\n### MFA Required\n\n```\n❌ MFA Verification Required\n\nOperation: server delete web-01\nReason: destructive operation (delete/destroy)\n\nTo verify MFA:\n   1. Get code from your authenticator app\n   2. Run: provisioning auth mfa verify --code <6-digit-code>\n\nDon't have MFA set up?\n   Run: provisioning auth mfa enroll totp\n```\n\n**Solution**: Run `provisioning auth mfa verify --code 123456`\n\n---\n\n### Token Expired\n\n```\n❌ Authentication Required\n\nOperation: server create web-02\nYou must be logged in to perform this operation.\n\nError: Token verification failed\n```\n\n**Solution**: Token expired, re-login with `provisioning auth login <username>`\n\n---\n\n## Audit Logging\n\nAll authenticated operations are logged to the audit log file with the following information:\n\n```\n{\n  "timestamp": "2025-10-09 14:32:15",\n  "user": "admin",\n  "operation": "server_create",\n  "details": {\n    "hostname": "web-01",\n    "infra": "production",\n    "environment": "prod",\n    "orchestrated": false\n  },\n  "mfa_verified": true\n}\n```\n\n### Viewing Audit Logs\n\n```\n# View raw audit log\ncat provisioning/logs/audit.log\n\n# Filter by user\ncat provisioning/logs/audit.log | jq '. | select(.user == "admin")'\n\n# Filter by operation type\ncat provisioning/logs/audit.log | jq '. | select(.operation == "server_create")'\n\n# Filter by date\ncat provisioning/logs/audit.log | jq '. | select(.timestamp | startswith("2025-10-09"))'\n```\n\n---\n\n## Integration with Control Center\n\nThe authentication system integrates with the provisioning platform's control center REST API:\n\n- **POST /api/auth/login** - Login with credentials\n- **POST /api/auth/logout** - Revoke tokens\n- **POST /api/auth/verify** - Verify token validity\n- **GET /api/auth/sessions** - List active sessions\n- **POST /api/mfa/enroll** - Enroll MFA device\n- **POST /api/mfa/verify** - Verify MFA code\n\n### Starting Control Center\n\n```\n# Start control center (required for authentication)\ncd provisioning/platform/control-center\ncargo run --release\n```\n\nOr use the orchestrator which includes control center:\n\n```\ncd provisioning/platform/orchestrator\n./scripts/start-orchestrator.nu --background\n```\n\n---\n\n## Testing Authentication\n\n### Manual Testing\n\n```\n# 1. Start control center\ncd provisioning/platform/control-center\ncargo run --release &\n\n# 2. Login\nprovisioning auth login admin\n\n# 3. Try creating server (should succeed if authenticated)\nprovisioning server create test-server --check\n\n# 4. Logout\nprovisioning auth logout\n\n# 5. Try creating server (should fail - not authenticated)\nprovisioning server create test-server --check\n```\n\n### Automated Testing\n\n```\n# Run authentication tests\nnu provisioning/core/nulib/lib_provisioning/plugins/auth_test.nu\n```\n\n---\n\n## Troubleshooting\n\n### Plugin Not Available\n\n**Error**: `Authentication plugin not available`\n\n**Solution**:\n\n1. Check plugin is built: `ls provisioning/core/plugins/nushell-plugins/nu_plugin_auth/target/release/`\n2. Register plugin: `plugin add target/release/nu_plugin_auth`\n3. Use plugin: `plugin use auth`\n4. Verify: `which auth`\n\n---\n\n### Control Center Not Running\n\n**Error**: `Cannot connect to control center`\n\n**Solution**:\n\n1. Start control center: `cd provisioning/platform/control-center && cargo run --release`\n2. Or use orchestrator: `cd provisioning/platform/orchestrator && ./scripts/start-orchestrator.nu --background`\n3. Check URL is correct in config: `provisioning config get platform.control_center.url`\n\n---\n\n### MFA Not Working\n\n**Error**: `Invalid MFA code`\n\n**Solutions**:\n\n- Ensure time is synchronized (TOTP codes are time-based)\n- Code expires every 30 seconds, get fresh code\n- Verify you're using the correct authenticator app entry\n- Re-enroll if needed: `provisioning auth mfa enroll totp`\n\n---\n\n### Keyring Access Issues\n\n**Error**: `Keyring storage unavailable`\n\n**macOS**: Grant Keychain access to Terminal/iTerm2 in System Preferences → Security & Privacy\n\n**Linux**: Ensure `gnome-keyring` or `kwallet` is running\n\n**Windows**: Check Windows Credential Manager is accessible\n\n---\n\n## Architecture\n\n### Authentication Flow\n\n```\n┌─────────────┐\n│ User Command│\n└──────┬──────┘\n       │\n       ▼\n┌─────────────────────────────────┐\n│ Infrastructure Command Handler  │\n│ (infrastructure.nu)             │\n└──────┬──────────────────────────┘\n       │\n       ▼\n┌─────────────────────────────────┐\n│ Auth Check                       │\n│ - Determine operation type       │\n│ - Check if auth required         │\n│ - Check environment (prod/dev)   │\n└──────┬──────────────────────────┘\n       │\n       ▼\n┌─────────────────────────────────┐\n│ Auth Plugin Wrapper              │\n│ (auth.nu)                        │\n│ - Call plugin or HTTP fallback   │\n│ - Verify token validity          │\n│ - Check MFA if required          │\n└──────┬──────────────────────────┘\n       │\n       ▼\n┌─────────────────────────────────┐\n│ nu_plugin_auth                   │\n│ - JWT verification (RS256)       │\n│ - Keyring token storage          │\n│ - MFA verification               │\n└──────┬──────────────────────────┘\n       │\n       ▼\n┌─────────────────────────────────┐\n│ Control Center API               │\n│ - /api/auth/verify               │\n│ - /api/mfa/verify                │\n└──────┬──────────────────────────┘\n       │\n       ▼\n┌─────────────────────────────────┐\n│ Operation Execution              │\n│ (servers/create.nu, etc.)        │\n└──────┬──────────────────────────┘\n       │\n       ▼\n┌─────────────────────────────────┐\n│ Audit Logging                    │\n│ - Log to audit.log               │\n│ - Include user, timestamp, MFA   │\n└─────────────────────────────────┘\n```\n\n### File Structure\n\n```\nprovisioning/\n├── config/\n│   └── config.defaults.toml           # Security configuration\n├── core/nulib/\n│   ├── lib_provisioning/plugins/\n│   │   └── auth.nu                    # Auth wrapper (550 lines)\n│   ├── servers/\n│   │   └── create.nu                  # Server ops with auth\n│   ├── workflows/\n│   │   └── batch.nu                   # Batch workflows with auth\n│   └── main_provisioning/commands/\n│       └── infrastructure.nu          # Infrastructure commands with auth\n├── core/plugins/nushell-plugins/\n│   └── nu_plugin_auth/                # Native Rust plugin\n│       ├── src/\n│       │   ├── main.rs                # Plugin implementation\n│       │   └── helpers.rs             # Helper functions\n│       └── README.md                  # Plugin documentation\n├── platform/control-center/           # Control Center (Rust)\n│   └── src/auth/                      # JWT auth implementation\n└── logs/\n    └── audit.log                       # Audit trail\n```\n\n---\n\n## Related Documentation\n\n- **Security System Overview**: `docs/architecture/adr-009-security-system-complete.md`\n- **JWT Authentication**: `docs/architecture/JWT_AUTH_IMPLEMENTATION.md`\n- **MFA Implementation**: `docs/architecture/MFA_IMPLEMENTATION_SUMMARY.md`\n- **Plugin README**: `provisioning/core/plugins/nushell-plugins/nu_plugin_auth/README.md`\n- **Control Center**: `provisioning/platform/control-center/README.md`\n\n---\n\n## Summary of Changes\n\n| File | Changes | Lines Added |\n| ------ | --------- | ------------- |\n| `lib_provisioning/plugins/auth.nu` | Added security policy enforcement functions | +260 |\n| `config/config.defaults.toml` | Added security configuration section | +19 |\n| `servers/create.nu` | Added auth check for server creation | +25 |\n| `workflows/batch.nu` | Added auth check for batch workflow submission | +43 |\n| `main_provisioning/commands/infrastructure.nu` | Added auth checks for all infrastructure commands | +90 |\n| `lib_provisioning/providers/interface.nu` | Added authentication guidelines for providers | +65 |\n| **Total** | **6 files modified** | **~500 lines** |\n\n---\n\n## Best Practices\n\n### For Users\n\n1. **Always login**: Keep your session active to avoid interruptions\n2. **Use keyring**: Save credentials with `--save` flag for persistence\n3. **Enable MFA**: Use MFA for production operations\n4. **Check mode first**: Always test with `--check` before actual operations\n5. **Monitor audit logs**: Review audit logs regularly for security\n\n### For Developers\n\n1. **Check auth early**: Verify authentication before expensive operations\n2. **Log operations**: Always log authenticated operations for audit\n3. **Clear error messages**: Provide helpful guidance for auth failures\n4. **Respect check mode**: Always skip auth in check/dry-run mode\n5. **Test both paths**: Test with and without authentication\n\n### For Operators\n\n1. **Production hardening**: Set `allow_skip_auth = false` in production\n2. **MFA enforcement**: Require MFA for all production environments\n3. **Monitor audit logs**: Set up log monitoring and alerts\n4. **Token rotation**: Configure short token timeouts (15 min default)\n5. **Backup authentication**: Ensure multiple admins have MFA enrolled\n\n---\n\n## License\n\nMIT License - See LICENSE file for details\n\n---\n\n## Quick Reference\n\n**Version**: 1.0.0\n**Last Updated**: 2025-10-09\n\n---\n\n### Quick Commands\n\n#### Login\n\n```\nprovisioning auth login <username>              # Interactive password\nprovisioning auth login <username> --save       # Save to keyring\n```\n\n#### MFA\n\n```\nprovisioning auth mfa enroll totp               # Enroll TOTP\nprovisioning auth mfa verify --code 123456      # Verify code\n```\n\n#### Status\n\n```\nprovisioning auth status                        # Show auth status\nprovisioning auth verify                        # Verify token\n```\n\n#### Logout\n\n```\nprovisioning auth logout                        # Logout current session\nprovisioning auth logout --all                  # Logout all sessions\n```\n\n---\n\n### Protected Operations\n\n| Operation | Auth | MFA (Prod) | MFA (Delete) | Check Mode |\n| ----------- | ------ | ------------ | -------------- | ------------ |\n| `server create` | ✅ | ✅ | ❌ | Skip |\n| `server delete` | ✅ | ✅ | ✅ | Skip |\n| `server list` | ❌ | ❌ | ❌ | - |\n| `taskserv create` | ✅ | ✅ | ❌ | Skip |\n| `taskserv delete` | ✅ | ✅ | ✅ | Skip |\n| `cluster create` | ✅ | ✅ | ❌ | Skip |\n| `cluster delete` | ✅ | ✅ | ✅ | Skip |\n| `batch submit` | ✅ | ✅ | ❌ | - |\n\n---\n\n### Bypass Authentication (Dev/Test Only)\n\n#### Environment Variable\n\n```\nexport PROVISIONING_SKIP_AUTH=true\nprovisioning server create test\nunset PROVISIONING_SKIP_AUTH\n```\n\n#### Check Mode (Always Allowed)\n\n```\nprovisioning server create prod --check\nprovisioning taskserv delete k8s --check\n```\n\n#### Config Flag\n\n```\n[security.bypass]\nallow_skip_auth = true  # Only in dev/test\n```\n\n---\n\n### Configuration\n\n#### Security Settings\n\n```\n[security]\nrequire_auth = true\nrequire_mfa_for_production = true\nrequire_mfa_for_destructive = true\nauth_timeout = 3600\n\n[security.bypass]\nallow_skip_auth = false  # true in dev only\n\n[plugins]\nauth_enabled = true\n\n[platform.control_center]\nurl = "http://localhost:3000"\n```\n\n---\n\n### Error Messages\n\n#### Not Authenticated\n\n```\n❌ Authentication Required\nOperation: server create web-01\nTo login: provisioning auth login <username>\n```\n\n**Fix**: `provisioning auth login <username>`\n\n#### MFA Required\n\n```\n❌ MFA Verification Required\nOperation: server delete web-01\nReason: destructive operation\n```\n\n**Fix**: `provisioning auth mfa verify --code <code>`\n\n#### Token Expired\n\n```\nError: Token verification failed\n```\n\n**Fix**: Re-login: `provisioning auth login <username>`\n\n---\n\n### Troubleshooting\n\n| Error | Solution |\n| ------- | ---------- |\n| Plugin not available | `plugin add target/release/nu_plugin_auth` |\n| Control center offline | Start: `cd provisioning/platform/control-center && cargo run` |\n| Invalid MFA code | Get fresh code (expires in 30s) |\n| Token expired | Re-login: `provisioning auth login <username>` |\n| Keyring access denied | Grant app access in system settings |\n\n---\n\n### Audit Logs\n\n```\n# View audit log\ncat provisioning/logs/audit.log\n\n# Filter by user\ncat provisioning/logs/audit.log | jq '. | select(.user == "admin")'\n\n# Filter by operation\ncat provisioning/logs/audit.log | jq '. | select(.operation == "server_create")'\n```\n\n---\n\n### CI/CD Integration\n\n#### Option 1: Skip Auth (Dev/Test Only)\n\n```\nexport PROVISIONING_SKIP_AUTH=true\nprovisioning server create ci-server\n```\n\n#### Option 2: Check Mode\n\n```\nprovisioning server create ci-server --check\n```\n\n#### Option 3: Service Account (Future)\n\n```\nexport PROVISIONING_AUTH_TOKEN="<token>"\nprovisioning server create ci-server\n```\n\n---\n\n### Performance\n\n| Operation | Auth Overhead |\n| ----------- | --------------- |\n| Server create | ~20 ms |\n| Taskserv create | ~20 ms |\n| Batch submit | ~20 ms |\n| Check mode | 0 ms (skipped) |\n\n---\n\n### Related Docs\n\n- **Full Guide**: `docs/user/AUTHENTICATION_LAYER_GUIDE.md`\n- **Implementation**: `AUTHENTICATION_LAYER_IMPLEMENTATION_SUMMARY.md`\n- **Security ADR**: `docs/architecture/adr-009-security-system-complete.md`\n\n---\n\n**Quick Help**: `provisioning help auth` or `provisioning auth --help`\n\n---\n\n**Last Updated**: 2025-10-09\n**Maintained By**: Security Team\n\n---\n\n## Setup Guide\n\n### Complete Authentication Setup Guide\n\nCurrent Settings (from your config)\n\n```\n[security]\nrequire_auth = true                    # ✅ Auth is REQUIRED\nallow_skip_auth = false                # ❌ Cannot skip with env var\nauth_timeout = 3600                    # Token valid for 1 hour\n\n[platform.control_center]\nurl = "http://localhost:3000"          # Control Center endpoint\n```\n\n### STEP 1: Start Control Center\n\nThe Control Center is the authentication backend:\n\n```\n# Check if it's already running\ncurl http://localhost:3000/health\n\n# If not running, start it\ncd /Users/Akasha/project-provisioning/provisioning/platform/control-center\ncargo run --release &\n\n# Wait for it to start (may take 30-60 seconds)\nsleep 30\ncurl http://localhost:3000/health\n```\n\nExpected Output:\n\n```\n{"status": "healthy"}\n```\n\n### STEP 2: Find Default Credentials\n\nCheck for default user setup:\n\n```\n# Look for initialization scripts\nls -la /Users/Akasha/project-provisioning/provisioning/platform/control-center/\n\n# Check for README or setup instructions\ncat /Users/Akasha/project-provisioning/provisioning/platform/control-center/README.md\n\n# Or check for default config\ncat /Users/Akasha/project-provisioning/provisioning/platform/control-center/config.toml 2>/dev/null || echo "Config not found"\n```\n\n### STEP 3: Log In\n\nOnce you have credentials (usually admin / password from setup):\n\n```\n# Interactive login - will prompt for password\nprovisioning auth login\n\n# Or with username\nprovisioning auth login admin\n\n# Verify you're logged in\nprovisioning auth status\n```\n\nExpected Success Output:\n\n```\n✓ Login successful!\n\nUser:       admin\nRole:       admin\nExpires:    2025-10-22T14:30:00Z\nMFA:        false\n\nSession active and ready\n```\n\n### STEP 4: Now Create Your Server\n\nOnce authenticated:\n\n```\n# Try server creation again\nprovisioning server create sgoyol --check\n\n# Or with full details\nprovisioning server create sgoyol --infra workspace_librecloud --check\n```\n\n### 🛠️ Alternative: Skip Auth for Development\n\nIf you want to bypass authentication temporarily for testing:\n\n#### Option A: Edit config to allow skip\n\n```\n# You would need to parse and modify TOML - easier to do next option\n```\n\n#### Option B: Use environment variable (if allowed by config)\n\n```\nexport PROVISIONING_SKIP_AUTH=true\nprovisioning server create sgoyol\nunset PROVISIONING_SKIP_AUTH\n```\n\n#### Option C: Use check mode (always works, no auth needed)\n\n```\nprovisioning server create sgoyol --check\n```\n\n#### Option D: Modify config.defaults.toml (permanent for dev)\n\nEdit: `provisioning/config/config.defaults.toml`\n\nChange line 193 to:\n\n```\nallow_skip_auth = true\n```\n\n### 🔍 Troubleshooting\n\n| Problem                    | Solution                                                              |\n| -------------------------- | --------------------------------------------------------------------- |\n| Control Center won't start | Check port 3000 not in use: `lsof -i :3000`                           |\n| "No token found" error     | Login with: `provisioning auth login`                                 |\n| Login fails                | Verify Control Center is running: `curl http://localhost:3000/health` |\n| Token expired              | Re-login: `provisioning auth login`                                   |\n| Plugin not available       | Using HTTP fallback - this is OK, works without plugin                |
