SSO Settings

Azure Government Cloud Entra ID (Azure AD) single sign-on configuration with OIDC Authorization Code flow, PKCE, MFA enforcement, and role mapping.

Overview

Federal and enterprise customers require SSO integration with their identity provider. The ThreatOps SSO module implements OIDC Authorization Code flow with PKCE targeting Azure Government Cloud (login.microsoftonline.us). This is critical for FedRAMP compliance, as it ensures centralized identity governance, MFA enforcement via the amr claim, and Just-In-Time (JIT) user provisioning. The SSO Settings page allows administrators to view configuration, test connectivity, manage allowed email domains, and map Azure AD groups to ThreatOps roles.

What Was Proposed

Azure Government Cloud OIDC/Entra ID SSO with PKCE
MFA enforcement via amr claim inspection
JIT user provisioning from Azure AD claims
Azure AD group to ThreatOps role mapping
Domain-restricted email allowlisting
Connection testing endpoint
External tenant detection with auto customer_viewer role
Federated logout support

What's Built Complete

Full OIDC Authorization Code flow with PKCE (S256 code challenge)
Azure Government Cloud authority: login.microsoftonline.us
ID token validation: RS256 signature (JWKS), issuer, audience, exp, nbf, nonce
MFA enforcement via amr claim ("mfa" in authentication methods references)
JIT user provisioning: creates/updates local User on SSO login
5 role mappings: ThreatOps-SuperAdmins, ThreatOps-Admins, ThreatOps-Analysts, ThreatOps-Viewers, ReportViewers
External tenant auto-detection: users from non-internal tenants get customer_viewer role
Global Administrator wids detection for super_admin assignment
OIDC discovery metadata caching with 1-hour TTL
PKCE state management with 10-minute expiry and automatic cleanup
Connection test endpoint to verify Azure Gov Cloud reachability
Allowed domains configuration with add/remove
Role mapping CRUD with admin save
Recent SSO login attempts audit table
Federated logout via Azure AD end_session_endpoint
Full permission matrix for 5 roles across 12 capability areas

Architecture

OIDC Authentication Flow

The SSO flow begins when the frontend redirects to /api/v1/sso/auth/login. The backend generates a PKCE code verifier/challenge and nonce, then redirects to Azure Gov Cloud's authorization endpoint. After user authentication and MFA, Azure returns an authorization code to /api/v1/sso/auth/callback. The backend exchanges the code for tokens, validates the ID token against JWKS, checks MFA status, provisions the user via JIT, and issues a local JWT session token.

1. Browser -> /api/v1/sso/auth/login
2. API generates PKCE (code_verifier + S256 challenge) + state + nonce
3. Redirect -> login.microsoftonline.us/{tenant}/oauth2/v2.0/authorize
4. User authenticates + MFA at Azure Gov Cloud
5. Azure redirects -> /api/v1/sso/auth/callback?code=...&state=...
6. API exchanges code for tokens (POST to token_endpoint with code_verifier)
7. Validate ID token: RS256 signature, issuer, audience, exp, nbf, nonce
8. Check amr claim for MFA completion
9. JIT provision/update user in local DB
10. Map Azure AD groups/roles to ThreatOps roles
11. Issue local JWT with permissions
12. Redirect to frontend /auth/callback?token=...&mfa=true

Routing

Frontend Route

/sso-settings

API Prefix

/api/v1/sso

Prerequisites

Azure Government Cloud tenant (Entra ID)
App registration with OIDC redirect URI configured
Client ID and optional Client Secret
Environment variables: SSO_ENABLED, AZURE_GOV_CLOUD, AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, SSO_REDIRECT_URI, SSO_ALLOWED_DOMAINS

Data Model

SSO Settings Response

Field	Type	Description
sso_enabled	boolean	Whether SSO is active
gov_cloud	boolean	Azure Government Cloud mode
tenant_id	string	Azure AD tenant ID
client_id	string	App registration client ID
allowed_domains	string[]	Allowed email domains for SSO login
role_mappings	dict	Azure AD group name -> ThreatOps role

Role Mapping Defaults

Azure AD Group	ThreatOps Role
ThreatOps-SuperAdmins	super_admin
ThreatOps-Admins	admin
ThreatOps-Analysts	analyst
ThreatOps-Viewers	viewer
ReportViewers	customer_viewer
(External tenant)	customer_viewer (auto)
(Global Admin wid)	super_admin (auto)

API Endpoints

Method	Endpoint	Description
GET	/auth/login	Initiate SSO login (redirect to Azure)
GET	/auth/callback	Handle OIDC callback, exchange code, provision user
POST	/auth/token	Programmatic code exchange (API-based flow)
GET	/auth/logout	Federated logout from Azure AD
GET	/auth/metadata	SSO/OIDC metadata for frontend
GET	/auth/status	Check current SSO session status
GET	/settings	Get SSO settings (admin only)
POST	/settings/role-mappings	Update role mappings (admin only)
GET	/connection-test	Test Azure Gov Cloud connectivity

UI Description

The page header shows "SSO Settings" with two status badges: "Azure Gov Cloud" (blue) and "FedRAMP High" (green).

SSO Configuration Card

Displays Enabled/Disabled status badge, Azure Tenant ID, Client ID, Authority (login.microsoftonline.us), and Cloud Environment in a 2-column grid with monospace font for IDs.

Connection Test Card

A "Test Connection" orange button triggers an OIDC discovery endpoint check. Results show connected/failed status with issuer information or error details.

Allowed Email Domains

An input field with "Add" button allows adding new domains. Existing domains appear in a list with trash icons for removal. Empty state says "No domain restrictions configured."

Role Mappings

A form to add new group-to-role mappings (input + role selector + Add button). Existing mappings appear in a table with group name, color-coded role badge (purple=super_admin, orange=admin, blue=analyst, grey=viewer), and delete button. A "Save Mappings" orange button persists changes.

Recent SSO Login Attempts

A table showing email, timestamp, success/failed badge, MFA verification status, and error details for recent login attempts.

Source Files

Component	Path
API Router	platform/api/app/routers/sso.py
SSO Service	platform/api/app/services/sso_service.py
Frontend Page	platform/frontend/src/app/sso-settings/page.tsx