Authentication Layer Implementation Guide

Version: 1.0.0 Date: 2025-10-09 Status: Production Ready

Overview

A comprehensive authentication layer has been integrated into the provisioning system to secure sensitive operations. The system uses nu_plugin_auth for JWT authentication with MFA support, providing enterprise-grade security with graceful user experience.

Key Features

✅ JWT Authentication

RS256 asymmetric signing
Access tokens (15min) + refresh tokens (7d)
OS keyring storage (macOS Keychain, Windows Credential Manager, Linux Secret Service)

✅ MFA Support

TOTP (Google Authenticator, Authy)
WebAuthn/FIDO2 (YubiKey, Touch ID)
Required for production and destructive operations

✅ Security Policies

Production environment: Requires authentication + MFA
Destructive operations: Requires authentication + MFA (delete, destroy)
Development/test: Requires authentication, allows skip with flag
Check mode: Always bypasses authentication (dry-run operations)

✅ Audit Logging

All authenticated operations logged
User, timestamp, operation details
MFA verification status
JSON format for easy parsing

✅ User-Friendly Error Messages

Clear instructions for login/MFA
Distinct error types (platform auth vs provider auth)
Helpful guidance for setup

Quick Start

# Interactive login (password prompt)
provisioning auth login <username>

# Save credentials to keyring
provisioning auth login <username> --save

# Custom control center URL
provisioning auth login admin --url http://control.example.com:9080

2. Enroll MFA (First Time)

# Enroll TOTP (Google Authenticator)
provisioning auth mfa enroll totp

# Scan QR code with authenticator app
# Or enter secret manually

3. Verify MFA (For Sensitive Operations)

# Get 6-digit code from authenticator app
provisioning auth mfa verify --code 123456

4. Check Authentication Status

# View current authentication status
provisioning auth status

# Verify token is valid
provisioning auth verify

Protected Operations

Server Operations

# ✅ CREATE - Requires auth (prod: +MFA)
provisioning server create web-01                    # Auth required
provisioning server create web-01 --check            # Auth skipped (check mode)

# ❌ DELETE - Requires auth + MFA
provisioning server delete web-01                    # Auth + MFA required
provisioning server delete web-01 --check            # Auth skipped (check mode)

# 📖 READ - No auth required
provisioning server list                             # No auth required
provisioning server ssh web-01                       # No auth required

Task Service Operations

# ✅ CREATE - Requires auth (prod: +MFA)
provisioning taskserv create kubernetes              # Auth required
provisioning taskserv create kubernetes --check      # Auth skipped

# ❌ DELETE - Requires auth + MFA
provisioning taskserv delete kubernetes              # Auth + MFA required

# 📖 READ - No auth required
provisioning taskserv list                           # No auth required

Cluster Operations

# ✅ CREATE - Requires auth (prod: +MFA)
provisioning cluster create buildkit                 # Auth required
provisioning cluster create buildkit --check         # Auth skipped

# ❌ DELETE - Requires auth + MFA
provisioning cluster delete buildkit                 # Auth + MFA required

Batch Workflows

# ✅ SUBMIT - Requires auth (prod: +MFA)
provisioning batch submit workflow.k                 # Auth required
provisioning batch submit workflow.k --skip-auth     # Auth skipped (if allowed)

# 📖 READ - No auth required
provisioning batch list                              # No auth required
provisioning batch status <task-id>                  # No auth required

Configuration

Security Settings (`config.defaults.toml`)

[security]
require_auth = true  # Enable authentication system
require_mfa_for_production = true  # MFA for prod environment
require_mfa_for_destructive = true  # MFA for delete operations
auth_timeout = 3600  # Token timeout (1 hour)
audit_log_path = "{{paths.base}}/logs/audit.log"

[security.bypass]
allow_skip_auth = false  # Allow PROVISIONING_SKIP_AUTH env var

[plugins]
auth_enabled = true  # Enable nu_plugin_auth

[platform.control_center]
url = "http://localhost:9080"  # Control center URL

Environment-Specific Configuration

# Development
[environments.dev]
security.bypass.allow_skip_auth = true  # Allow auth bypass in dev

# Production
[environments.prod]
security.bypass.allow_skip_auth = false  # Never allow bypass
security.require_mfa_for_production = true

Authentication Bypass (Dev/Test Only)

Environment Variable Method

# Export environment variable (dev/test only)
export PROVISIONING_SKIP_AUTH=true

# Run operations without authentication
provisioning server create web-01

# Unset when done
unset PROVISIONING_SKIP_AUTH

Per-Command Flag

# Some commands support --skip-auth flag
provisioning batch submit workflow.k --skip-auth

Check Mode (Always Bypasses Auth)

# Check mode is always allowed without auth
provisioning server create web-01 --check
provisioning taskserv create kubernetes --check

⚠️ WARNING: Auth bypass should ONLY be used in development/testing environments. Production systems should have security.bypass.allow_skip_auth = false.

Error Messages

Not Authenticated

❌ Authentication Required

Operation: server create web-01
You must be logged in to perform this operation.

To login:
   provisioning auth login <username>

Note: Your credentials will be securely stored in the system keyring.

Solution: Run provisioning auth login <username>

MFA Required

❌ MFA Verification Required

Operation: server delete web-01
Reason: destructive operation (delete/destroy)

To verify MFA:
   1. Get code from your authenticator app
   2. Run: provisioning auth mfa verify --code <6-digit-code>

Don't have MFA set up?
   Run: provisioning auth mfa enroll totp

Solution: Run provisioning auth mfa verify --code 123456

Token Expired

❌ Authentication Required

Operation: server create web-02
You must be logged in to perform this operation.

Error: Token verification failed

Solution: Token expired, re-login with provisioning auth login <username>

Audit Logging

All authenticated operations are logged to the audit log file with the following information:

{
  "timestamp": "2025-10-09 14:32:15",
  "user": "admin",
  "operation": "server_create",
  "details": {
    "hostname": "web-01",
    "infra": "production",
    "environment": "prod",
    "orchestrated": false
  },
  "mfa_verified": true
}

Viewing Audit Logs

# View raw audit log
cat provisioning/logs/audit.log

# Filter by user
cat provisioning/logs/audit.log | jq '. | select(.user == "admin")'

# Filter by operation type
cat provisioning/logs/audit.log | jq '. | select(.operation == "server_create")'

# Filter by date
cat provisioning/logs/audit.log | jq '. | select(.timestamp | startswith("2025-10-09"))'

Integration with Control Center

The authentication system integrates with the provisioning platform’s control center REST API:

POST /api/auth/login - Login with credentials
POST /api/auth/logout - Revoke tokens
POST /api/auth/verify - Verify token validity
GET /api/auth/sessions - List active sessions
POST /api/mfa/enroll - Enroll MFA device
POST /api/mfa/verify - Verify MFA code

Starting Control Center

# Start control center (required for authentication)
cd provisioning/platform/control-center
cargo run --release

Or use the orchestrator which includes control center:

cd provisioning/platform/orchestrator
./scripts/start-orchestrator.nu --background

Testing Authentication

Manual Testing

# 1. Start control center
cd provisioning/platform/control-center
cargo run --release &

# 2. Login
provisioning auth login admin

# 3. Try creating server (should succeed if authenticated)
provisioning server create test-server --check

# 4. Logout
provisioning auth logout

# 5. Try creating server (should fail - not authenticated)
provisioning server create test-server --check

Automated Testing

# Run authentication tests
nu provisioning/core/nulib/lib_provisioning/plugins/auth_test.nu

Troubleshooting

Plugin Not Available

Error: Authentication plugin not available

Solution:

Check plugin is built: ls provisioning/core/plugins/nushell-plugins/nu_plugin_auth/target/release/
Register plugin: plugin add target/release/nu_plugin_auth
Use plugin: plugin use auth
Verify: which auth

Control Center Not Running

Error: Cannot connect to control center

Solution:

Start control center: cd provisioning/platform/control-center && cargo run --release
Or use orchestrator: cd provisioning/platform/orchestrator && ./scripts/start-orchestrator.nu --background
Check URL is correct in config: provisioning config get platform.control_center.url

MFA Not Working

Error: Invalid MFA code

Solutions:

Ensure time is synchronized (TOTP codes are time-based)
Code expires every 30 seconds, get fresh code
Verify you’re using the correct authenticator app entry
Re-enroll if needed: provisioning auth mfa enroll totp

Keyring Access Issues

Error: Keyring storage unavailable

macOS: Grant Keychain access to Terminal/iTerm2 in System Preferences → Security & Privacy

Linux: Ensure gnome-keyring or kwallet is running

Windows: Check Windows Credential Manager is accessible

Architecture

Authentication Flow

┌─────────────┐
│ User Command│
└──────┬──────┘
       │
       ▼
┌─────────────────────────────────┐
│ Infrastructure Command Handler  │
│ (infrastructure.nu)             │
└──────┬──────────────────────────┘
       │
       ▼
┌─────────────────────────────────┐
│ Auth Check                       │
│ - Determine operation type       │
│ - Check if auth required         │
│ - Check environment (prod/dev)   │
└──────┬──────────────────────────┘
       │
       ▼
┌─────────────────────────────────┐
│ Auth Plugin Wrapper              │
│ (auth.nu)                        │
│ - Call plugin or HTTP fallback   │
│ - Verify token validity          │
│ - Check MFA if required          │
└──────┬──────────────────────────┘
       │
       ▼
┌─────────────────────────────────┐
│ nu_plugin_auth                   │
│ - JWT verification (RS256)       │
│ - Keyring token storage          │
│ - MFA verification               │
└──────┬──────────────────────────┘
       │
       ▼
┌─────────────────────────────────┐
│ Control Center API               │
│ - /api/auth/verify               │
│ - /api/mfa/verify                │
└──────┬──────────────────────────┘
       │
       ▼
┌─────────────────────────────────┐
│ Operation Execution              │
│ (servers/create.nu, etc.)        │
└──────┬──────────────────────────┘
       │
       ▼
┌─────────────────────────────────┐
│ Audit Logging                    │
│ - Log to audit.log               │
│ - Include user, timestamp, MFA   │
└─────────────────────────────────┘

File Structure

provisioning/
├── config/
│   └── config.defaults.toml           # Security configuration
├── core/nulib/
│   ├── lib_provisioning/plugins/
│   │   └── auth.nu                    # Auth wrapper (550 lines)
│   ├── servers/
│   │   └── create.nu                  # Server ops with auth
│   ├── workflows/
│   │   └── batch.nu                   # Batch workflows with auth
│   └── main_provisioning/commands/
│       └── infrastructure.nu          # Infrastructure commands with auth
├── core/plugins/nushell-plugins/
│   └── nu_plugin_auth/                # Native Rust plugin
│       ├── src/
│       │   ├── main.rs                # Plugin implementation
│       │   └── helpers.rs             # Helper functions
│       └── README.md                  # Plugin documentation
├── platform/control-center/           # Control Center (Rust)
│   └── src/auth/                      # JWT auth implementation
└── logs/
    └── audit.log                       # Audit trail

Security System Overview: docs/architecture/ADR-009-security-system-complete.md
JWT Authentication: docs/architecture/JWT_AUTH_IMPLEMENTATION.md
MFA Implementation: docs/architecture/MFA_IMPLEMENTATION_SUMMARY.md
Plugin README: provisioning/core/plugins/nushell-plugins/nu_plugin_auth/README.md
Control Center: provisioning/platform/control-center/README.md

Summary of Changes

File	Changes	Lines Added
`lib_provisioning/plugins/auth.nu`	Added security policy enforcement functions	+260
`config/config.defaults.toml`	Added security configuration section	+19
`servers/create.nu`	Added auth check for server creation	+25
`workflows/batch.nu`	Added auth check for batch workflow submission	+43
`main_provisioning/commands/infrastructure.nu`	Added auth checks for all infrastructure commands	+90
`lib_provisioning/providers/interface.nu`	Added authentication guidelines for providers	+65
Total	6 files modified	~500 lines

Best Practices

For Users

Always login: Keep your session active to avoid interruptions
Use keyring: Save credentials with --save flag for persistence
Enable MFA: Use MFA for production operations
Check mode first: Always test with --check before actual operations
Monitor audit logs: Review audit logs regularly for security

For Developers

Check auth early: Verify authentication before expensive operations
Log operations: Always log authenticated operations for audit
Clear error messages: Provide helpful guidance for auth failures
Respect check mode: Always skip auth in check/dry-run mode
Test both paths: Test with and without authentication

For Operators

Production hardening: Set allow_skip_auth = false in production
MFA enforcement: Require MFA for all production environments
Monitor audit logs: Set up log monitoring and alerts
Token rotation: Configure short token timeouts (15min default)
Backup authentication: Ensure multiple admins have MFA enrolled

License

MIT License - See LICENSE file for details

Last Updated: 2025-10-09 Maintained By: Security Team

Keyboard shortcuts

Provisioning Platform Documentation