Authentication

AuroraSOC supports two authentication methods: JWT (JSON Web Tokens) for interactive users and API Keys for programmatic access. Both methods are enforced on every API endpoint and WebSocket connection.

Authentication Flow

JWT Authentication

Login

curl -X POST /api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "analyst@soc.company.com", "password": "secure_password"}'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 28800,
  "role": "analyst"
}

Token Structure

The JWT payload contains:

{
  "sub": "analyst@soc.company.com",
  "role": "analyst",
  "exp": 1705430400,
  "iat": 1705401600
}

Field	Description
sub	User identifier (username/email)
role	Assigned role (admin, analyst, viewer, operator, api_service)
exp	Expiration timestamp (8 hours from issuance)
iat	Issued-at timestamp

Using the Token

Include the token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

For WebSocket connections, pass the token as a query parameter:

ws://aurora:8000/api/v1/ws/alerts?token=eyJhbGciOiJIUzI1NiIs...

Token Configuration

Environment Variable	Default	Description
AURORA_JWT_SECRET	(required)	HS256 signing secret (min 32 chars)
AURORA_JWT_ALGORITHM	HS256	JWT signing algorithm
AURORA_JWT_EXPIRATION	28800	Token lifetime in seconds (8 hours)

Secret Management

The AURORA_JWT_SECRET must be a cryptographically random string of at least 32 characters. Never commit it to version control. Use HashiCorp Vault or environment variables from a secrets manager.

API Key Authentication

For service-to-service communication and automation scripts:

Creating API Keys

curl -X POST /api/v1/auth/api-keys \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -d '{"name": "SIEM Integration", "role": "api_service"}'

Response:

{
  "key": "aurora_key_a1b2c3d4e5f6...",
  "name": "SIEM Integration",
  "role": "api_service",
  "created_at": "2024-01-15T10:00:00Z"
}

One-Time Display

The API key is only shown once at creation. Store it securely immediately. AuroraSOC stores only the SHA-256 hash of the key.

Using API Keys

Include in the X-API-Key header:

X-API-Key: aurora_key_a1b2c3d4e5f6...

API Key Lifecycle

Action	Endpoint	Permission Required
Create	POST /api/v1/auth/api-keys	admin role
List	GET /api/v1/auth/api-keys	admin role
Revoke	DELETE /api/v1/auth/api-keys/{id}	admin role

Security Best Practices

1. Rotate JWT secrets periodically (at least quarterly)
2. Use short-lived tokens — 8 hours is the default; consider shorter for high-security environments
3. Revoke API keys immediately when the associated service is decommissioned
4. Monitor auth failures — AuroraSOC logs all failed authentication attempts to the audit stream
5. Use HTTPS — Always deploy behind a TLS-terminating reverse proxy
6. Rate limit authentication — Built-in rate limiting prevents brute-force attacks (200 requests/minute per IP)