🔐 CONDOR Authentication & Authorization

Last updated: March 2026 Applies to: Server v2.x with Entra ID SSO support

---

Table of Contents

• Overview
• Architecture Diagram
• Authentication Methods
  • 1. Entra ID Single Sign-On (SSO)
  • 2. Username / Password Login
  • 3. API Key Bearer Token
• Auth Resolution Order
• CSRF Protection
• Session Lifecycle & Redis Storage
• Token Bootstrap Flow (Entra SSO)
• JWT Validation Pipeline
• Error Handling
• API Endpoints Reference
• Configuration Reference
• Infrastructure & Secrets Management
• Security Design Decisions

---

Overview

CONDOR supports three authentication methods, resolved in priority order on every request:

Priority	Method	Credential	Use Case
1	Entra ID (SSO)	JWT via ?token= URL param → session cookie	Users arriving from the Original App
2	Session Cookie	session httpOnly cookie	Browser sessions (login or SSO)
3	API Key Bearer	Authorization: Bearer <key> header	Machine-to-machine / scripts

All three methods ultimately resolve to either a Session or EntraUser object that routes consume via Depends(SessionService.require_session).

---

Architecture Diagram

---

Authentication Methods

1. Entra ID Single Sign-On (SSO)

The primary authentication method for users accessing CONDOR from the Original App.

How It Works

1. User clicks "CONDOR" in the Original App
2. Original App redirects to https://condor.example.com/?token=<JWT>
3. CONDOR validates the JWT once (signature, expiry, issuer, audience, azp, roles)
4. Validated EntraUser + raw JWT cached in Redis with TTL matching JWT exp
5. Session cookie set on a 302 redirect to / (clean URL)
6. All subsequent requests use the session cookie → cached EntraUser loaded from Redis
7. No JWT re-validation on API calls — Redis TTL handles expiry

JWT Claims Used

Claim	Purpose	Example
aud	Must match ENTRA_CLIENT_ID	6999a97c-c1cf-4809-b14c-05bc596bb0c5
iss	Must match tenant issuer URL	https://{tenant}.ciamlogin.com/{tenant}/v2.0
azp	Must be in ENTRA_ALLOWED_CLIENT_IDS	64abed69-d2d8-402e-9a04-e83c2cc8bde2
exp	Token expiry → session cookie TTL	Unix timestamp
roles	RBAC — must include Condor.Write	["Condor.Write", "Camera.Operate"]
oid	User's Object ID in Azure AD	UUID
name	Display name	Sharath Gaddameedi
preferred_username	Email	user@live.com
tid	Tenant ID	UUID

Role Enforcement

• Condor.Write — Required at bootstrap time to create a session. Without this role, the user sees an error on the login page.
• Route-level roles — Individual routes can enforce additional roles using EntraAuthService.require_roles("RoleName").

---

2. Username / Password Login

Traditional form-based login for direct access without SSO.

Session Cookie Properties

Property	Value	Reason
httpOnly	true	Prevents JavaScript access (XSS protection)
secure	true	HTTPS only (localhost exempt in browsers)
samesite	lax	CSRF protection for cross-origin requests
max_age	Not set (session cookie)	Dies with browser tab

---

3. API Key Bearer Token

For machine-to-machine access (scripts, automated exports, health checks).

• Stateless — No Redis session; a new Session object is created per request
• No CSRF — Bearer tokens are not vulnerable to CSRF
• No TTL refresh — No session to extend
• Key format: SESSION_API_KEYS='{"api-key-value": "username"}'

---

Auth Resolution Order

Every protected route uses Depends(SessionService.require_session), which calls get_session() internally:

Key insight: Entra-bootstrapped sessions (via /?token=JWT) resolve through the cookie path on subsequent requests. The cookie is looked up in Redis, which returns the cached EntraUser — no JWT re-validation occurs. Redis TTL auto-expires the cached user when the JWT would have expired.

---

CSRF Protection

CONDOR uses the Signed Double-Submit Cookie pattern:

CSRF Token = random_value | HMAC-SHA256(SESSION_CSRF_SECRET, session_id:random_value)

When enforced: POST, PUT, DELETE, PATCH requests using cookie-based auth only.
Not enforced: Bearer token requests (API keys, direct Entra JWT) — not vulnerable to CSRF.

---

Session Lifecycle & Redis Storage

Redis Key Layout

For a session with ID abc123:

Key	Value	TTL
session:abc123	Interaction count (int)	SESSION_LIFETIME_SECONDS or JWT exp
session:abc123:entra_user	Serialized EntraUser JSON	JWT exp
session:abc123:entra_token	Raw JWT string	JWT exp

Expiry Behavior

Session Type	TTL Source	Refreshed on Activity?
Username/Password	SESSION_LIFETIME_SECONDS (default: 7 days)	Yes — each interaction refreshes TTL
Entra SSO	JWT exp claim (typically 60-90 min)	No — fixed lifetime, expires with JWT
API Key	N/A (stateless)	N/A

---

Token Bootstrap Flow (Entra SSO)

Detailed step-by-step of what happens when a user arrives at /?token=JWT:

---

JWT Validation Pipeline

What EntraAuthService.validate_token() checks, in order:

Security: Fail-closed on missing ENTRA_ALLOWED_CLIENT_IDS
If ENTRA_ALLOWED_CLIENT_IDS is empty or not set, all tokens are rejected with a 403 error. This prevents misconfiguration from accidentally allowing any client app's token.

---

Error Handling

When token bootstrap fails, users are redirected to /?error=<code> which displays a human-readable message:

Error Code	Message	Cause
not_enabled	Single sign-on is not configured on this server.	ENTRA_ENABLED=false or missing tenant/client config
expired	Your session has expired. Please sign in again from the application.	JWT exp is in the past
invalid_audience	This token was not issued for this application.	JWT aud ≠ ENTRA_CLIENT_ID
invalid_issuer	This token was issued by an untrusted authority.	JWT iss ≠ expected tenant issuer
invalid_signature	The token signature could not be verified.	JWKS key mismatch or tampered token
invalid_token	The authentication token is invalid.	Malformed JWT or non-JWT string
unauthorized_app	Access is only allowed from an authorized application.	JWT azp ∉ ENTRA_ALLOWED_CLIENT_IDS
missing_role	Your account does not have the required 'Condor.Write' role. Contact your administrator.	roles claim missing Condor.Write

The error message is injected into the login page's existing #login-error element, and the ?error= param is cleaned from the URL via history.replaceState.

---

API Endpoints Reference

Endpoint	Method	Auth Required	Description
/	GET	Optional	Serves login page (public) or SPA (authenticated)
/?token=<JWT>	GET	JWT in URL	Entra SSO token bootstrap
/api/login	POST	None (form data)	Username/password authentication
/api/logout	POST	Session cookie	Clear session and cookies
/api/me	GET	Any auth	Returns current user info
/api/camera	GET	require_session	List cameras
/api/camera/event	GET	require_session	List camera events
/api/event/{id}	GET	require_session	Get event details
/api/event/{id}/annotate	POST	require_session + CSRF	Annotate an event

/api/me Response Shapes

Entra-authenticated user:

{
  "auth_method": "entra",
  "oid": "1bd08d5e-dd0f-4cda-b2be-36f1cf1e91f2",
  "name": "Sharath Gaddameedi",
  "email": "sharathgoud@live.com",
  "roles": ["Condor.Write", "Camera.Operate"]
}

Session-authenticated user:

{
  "auth_method": "session",
  "interaction_count": 42
}

---

Configuration Reference

Entra ID Settings (ENTRA_ prefix)

Variable	Required	Default	Description
ENTRA_ENABLED	Yes	false	Enable Entra ID authentication
ENTRA_TENANT_ID	If enabled	""	Azure AD tenant ID
ENTRA_CLIENT_ID	If enabled	""	CONDOR's App Registration client ID (JWT aud)
ENTRA_ALLOWED_CLIENT_IDS	If enabled	""	Comma-separated client IDs allowed to call CONDOR (JWT azp). Empty = reject all (fail-closed)
ENTRA_CIAM	No	false	Use CIAM tenant ({tenant}.ciamlogin.com instead of login.microsoftonline.com)

Session Settings (SESSION_ prefix)

Variable	Required	Description
SESSION_USERNAME	Yes	Login username for password auth
SESSION_PASSWORD	Yes	Login password for password auth
SESSION_API_KEYS	Yes	JSON map of API keys to usernames: {"key": "username"}
SESSION_CSRF_SECRET	Yes	HMAC secret for CSRF token signing
SESSION_LIFETIME_SECONDS	Yes	Session TTL in seconds (default: 604800 = 7 days)

---

Infrastructure & Secrets Management

Secrets Flow

Key Vault Secrets (ai4gl-condor-uat-kv)

These secrets are written at deploy time for backup, audit, and rotation:

Secret Name	Source Parameter
session-username	SERVER_SESSION_USERNAME
session-password	SERVER_SESSION_PASSWORD
session-api-keys	SERVER_SESSION_API_KEYS
session-csrf-secret	SERVER_SESSION_CSRF_SECRET
entra-allowed-client-ids	SERVER_ENTRA_ALLOWED_CLIENT_IDS
postgres-password	POSTGRES_PASSWORD
redis-password	REDIS_PASSWORD
vm-username	vmUsername
vm-password	vmPassword

VM Bootstrap: write_env_file

The vm-post-setup.sh script strips the SERVER_ prefix when writing to server/.env:

SERVER_ENTRA_ENABLED=true    →    ENTRA_ENABLED=true
SERVER_ENTRA_TENANT_ID=...   →    ENTRA_TENANT_ID=...
SERVER_SESSION_USERNAME=...  →    SESSION_USERNAME=...

---

Security Design Decisions

Why store the JWT server-side instead of in the browser?

Approach	Risk	CONDOR's Choice
JWT in sessionStorage	XSS can steal it; lost on tab close; visible in DevTools	✗ Removed
JWT in localStorage	XSS can steal it; persists indefinitely	✗ Never used
JWT in httpOnly cookie	Cookie too large (>4KB); sent on every request	✗ Not used
JWT in Redis, session cookie as handle	Cookie is opaque, small, httpOnly; JWT never in browser	✓ Current design

Why validate the JWT only once (at bootstrap)?

• Performance: JWKS fetch + RSA signature verification on every request adds ~50-200ms latency
• Reliability: JWKS endpoint downtime would break all requests
• Correctness: Redis TTL mirrors JWT exp — the cached EntraUser expires at exactly the same time the JWT would
• Trade-off: A revoked role takes effect only after the JWT (and thus the cached session) expires (typically 60-90 min)

Why fail-closed on empty ENTRA_ALLOWED_CLIENT_IDS?

If ENTRA_ALLOWED_CLIENT_IDS is not configured:

• Old behavior: The azp check was skipped, meaning any Entra app's token was accepted
• New behavior: All tokens are rejected with 403 Server misconfiguration
• Rationale: Defense-in-depth — misconfiguration should deny access, not grant it

Why redirect instead of inline serving after bootstrap?

After successful /?token=JWT validation:

• Old approach: Serve the private SPA HTML directly with cookies set on the same response
• Problem: Browsers handle Set-Cookie on HTML responses inconsistently; the JWT token remained visible in the URL bar
• New approach: 302 Redirect to / with cookies on the redirect response → browser stores cookies, follows redirect, sends cookies on the second request → clean URL, reliable cookie storage

---

File Reference

File	Purpose
server/services/entra_auth_service.py	JWT validation, JWKS client, RBAC dependency factories
server/services/session_service.py	Auth resolution (get_session, require_session), login/logout, CSRF
server/routers/files_router.py	Token bootstrap (/?token=), error display, SPA serving
server/routers/session_router.py	/api/login, /api/logout, /api/me endpoints
server/database/redis_session_database.py	Redis session storage, Entra user caching
server/models/entra_user.py	EntraUser Pydantic model with role helpers
server/settings/entra_settings.py	EntraSettings — tenant, client, CIAM, JWKS URI
server/settings/session_settings.py	SessionSettings — username, password, API keys, CSRF secret
server/tests/test_entra_auth.py	Unit tests for JWT validation, RBAC, token extraction
azure/infrastructure/main.bicep	Infrastructure — passes Entra params to modules
azure/infrastructure/modules/keyvault.bicep	Stores secrets in Key Vault at deploy time
azure/infrastructure/scripts/vm-post-setup.sh	Writes server/.env from deploy params