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/token \
  -H "Content-Type: application/json" \
  -d '{"username": "analyst@soc.company.com", "password": "secure_password"}'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 86400
}

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 (24 hours by default)
iat	Issued-at timestamp

Using the Token

For non-browser clients, include the token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

For browser clients, AuroraSOC also sets an httpOnly access_token cookie on login and accepts cookie authentication on API + WebSocket paths.

AuroraSOC keeps a short-lived in-process cache for valid database-managed API keys so high-frequency service traffic does not hit PostgreSQL on every authenticated request. The cache TTL is intentionally short, and explicit key revocation clears the current process cache immediately.

For WebSocket connections, browser clients should rely on cookie authentication. Query-token auth is only intended for non-browser automation clients that cannot attach cookies:

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

Token Configuration

Environment Variable	Default	Description
JWT_SECRET_KEY	(required)	HS256 signing secret (min 32 chars)
JWT_EXPIRY_HOURS	24	Token lifetime in hours

Secret Management

The JWT_SECRET_KEY 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 $TOKEN_WITH_USERS_MANAGE" \
  -d '{"service_name": "SIEM Integration", "expires_in_days": 90}'

Response:

{
  "api_key": "aurora_a1b2c3d4e5f6...",
  "service_name": "SIEM Integration",
  "key_prefix": "ak_3a9f2d4c7b11",
  "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.

The returned key_prefix is a management label for audits and rotation workflows. It is not derived from the raw API key bytes.

Using API Keys

Include in the X-API-Key header:

X-API-Key: aurora_a1b2c3d4e5f6...

API Key Lifecycle

Action	Endpoint	Permission Required
Create	POST /api/v1/auth/api-keys	users:manage
List	GET /api/v1/auth/api-keys	users:manage
Revoke	DELETE /api/v1/auth/api-keys/{id}	users:manage

Security Best Practices

1. Rotate JWT secrets periodically (at least quarterly)
2. Use short-lived tokens — 24 hours is the default; reduce lifetime 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 on login endpoints
7. Expect short cache overlap on multi-process deploys — DB-backed API key revocation is immediate in the local process and bounded by the short auth-cache TTL in other workers