ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.
Enterprise Single Sign-On (SSO) Integration & Setup Guide
This document provides a comprehensive guide for configuring and utilizing Enterprise Multi-Tenant SSO (SAML 2.0 & OpenID Connect) in the ARES Platform, covering both end-user workflows and administrative setup.
PART 1 - End-User Authentication Guide
When to Use Direct Local "Sign in" vs. "Or continue with SSO"
| Login Method | When to Use | Credentials |
|---|---|---|
| Direct Local "Sign in" | For local operator accounts and development/lab environments (e.g., the bootstrap superuser admin or dedicated local accounts created via POST /auth/register). |
Local username and password stored in the ARES database (hashed via bcrypt). |
| "Or continue with SSO" | When your organization manages identities centrally via an Identity Provider (IdP) such as Okta, Microsoft Entra ID (Azure AD), Google Workspace, Ping Identity, or Keycloak. | Your corporate/organization credentials entered on your IdP's official sign-in page. |
[!NOTE] Federated Account Lockdown: If your account has been provisioned or migrated to SSO (
auth_provider = 'saml'or'oidc'), your account is strictly prohibited from authenticating with a local password. You must authenticate using the "Or continue with SSO" workflow.
Understanding: "SSO is not configured for this organization. Contact your administrator."
If you click "Or continue with SSO" and an inline warning appears:
[!WARNING] SSO is not configured for this organization. Contact your administrator.
What this means:
- SSO federation (SAML 2.0 or OIDC) has not yet been registered for the target organization, or the configuration is currently disabled (
is_enabled = 0). - The ARES backend fail-closed policy rejected the request because no valid IdP endpoints, x.509 certificate, or client credentials were found.
Action Required:
- Do not attempt to guess local passwords.
- Contact your ARES Administrator or Security Operations (SecOps) team to complete the identity federation setup outlined in Part 2.
PART 2 - Administrator Guide: Organization SSO Setup
1. Prerequisite: ARES_ENCRYPTION_KEY Environment Variable
ARES enforces application-level encryption for sensitive secrets at rest using the DataEncryptor module (AES-256-GCM AEAD: PBKDF2-HMAC-SHA256 with 600,000 iterations + per-record cryptographically secure random 16-byte salt and 12-byte nonce). All SAML certificates and OIDC client secrets are encrypted before database persistence.
The application strictly requires ARES_ENCRYPTION_KEY to be at least 32 characters long. If unset or shorter than 32 characters, ARES will fail fast at startup with an explicit error.
Generate an Encryption Key:
Run the 256-bit AES key generator:
python -c "import secrets; print(secrets.token_urlsafe(32))"
Example output: 16R2yRp-PWlbNT49xq6sZzp39ArxJJ7Tlap1MqYWp3w=
Set the Environment Variable:
- In
.envfile (Recommended):ARES_ENCRYPTION_KEY=16R2yRp-PWlbNT49xq6sZzp39ArxJJ7Tlap1MqYWp3w= - In Linux / macOS (Terminal):
export ARES_ENCRYPTION_KEY="16R2yRp-PWlbNT49xq6sZzp39ArxJJ7Tlap1MqYWp3w=" - In Windows (PowerShell):
$env:ARES_ENCRYPTION_KEY="16R2yRp-PWlbNT49xq6sZzp39ArxJJ7Tlap1MqYWp3w="
2. Registering an SSO Configuration in ARES
SSO federation can be configured via the REST API Admin Endpoints (requires the team_lead role, the highest tier in ARES's role hierarchy: team_lead > operator > recon > reporter; the bootstrap user admin holds the team_lead role) or directly in the database.
[!IMPORTANT] Architecture Policy: SP-Initiated SSO Only
ARES strictly supports SP-initiated SSO. Users must always begin their sign-in flow from the ARES login interface (by clicking "Or continue with SSO"), rather than launching the application from an IdP app portal (such as Okta Dashboard or Microsoft Entra ID / Azure AD My Apps).
Communicate this requirement explicitly to your organization's IT/IAM team during onboarding, as this differs from common SaaS defaults. ARES purposefully rejects unsolicited SAML assertions without an activeInResponseTorecord and OIDC callbacks without a registeredstateparameter to eliminate replay attacks and session-fixation risks.
Option A: Via REST API (Recommended)
ARES provides dedicated configuration management endpoints for team_lead users:
GET /auth/sso/config/{org_slug}: Retrieve existing SSO status and metadata.POST /auth/sso/config/{org_slug}: Create or update organization SSO settings.
Request payload for POST /auth/sso/config/{org_slug}:
{
"protocol": "saml", // or "oidc"
"issuer_or_entity_id": "https://idp.example.com/entityid",
"sso_url": "https://idp.example.com/sso/endpoint",
"idp_certificate": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----",
"client_id": "",
"client_secret": "",
"jwks_uri": "",
"default_role": "reporter",
"role_mapping": {
"SecurityAdmins": "team_lead",
"RedTeam": "operator",
"Auditors": "reporter"
},
"is_enabled": true
}
Note: The backend automatically encrypts idp_certificate and client_secret via DataEncryptor before persisting to sso_configurations.
Option B: Direct SQL Database Insertion
ARES automatically manages and provisions the required multi-tenant SSO tables (organizations, sso_configurations, sso_flow_states, and JIT federated user attributes) across both supported storage backends:
- SQLite (
ares.dbfor local development and single-operator red team deployments) - Enterprise PostgreSQL (
postgresql+asyncpg://orpostgresql://for high-concurrency multi-tenant team server deployments)
If provisioning directly via SQL:
- Ensure the organization exists in the
organizationstable:INSERT INTO organizations (id, slug, name, is_active) VALUES ('org-corp-01', 'corp', 'ACME Corp', 1) ON CONFLICT (slug) DO NOTHING; - Encrypt certificates or client secrets using the ARES CLI helper:
python -c "from ares.core.config import get_settings; from ares.core.sso import encrypt_sso_secret; print(encrypt_sso_secret('YOUR_SECRET_HERE', get_settings()))" - Insert into
sso_configurations:- For SQLite:
INSERT INTO sso_configurations ( id, org_id, protocol, is_enabled, issuer_or_entity_id, sso_url, idp_certificate_enc, default_role, role_mapping_json ) VALUES ( 'sso-cfg-01', 'org-corp-01', 'saml', 1, 'https://idp.example.com/entityid', 'https://idp.example.com/sso', '<ENCRYPTED_VALUE>', 'reporter', '{"SecAdmins": "team_lead"}' ) ON CONFLICT(org_id, protocol) DO UPDATE SET is_enabled=excluded.is_enabled, issuer_or_entity_id=excluded.issuer_or_entity_id, sso_url=excluded.sso_url, idp_certificate_enc=excluded.idp_certificate_enc, updated_at=datetime('now'); - For PostgreSQL:
INSERT INTO sso_configurations ( id, org_id, protocol, is_enabled, issuer_or_entity_id, sso_url, idp_certificate_enc, default_role, role_mapping_json ) VALUES ( 'sso-cfg-01', 'org-corp-01', 'saml', 1, 'https://idp.example.com/entityid', 'https://idp.example.com/sso', '<ENCRYPTED_VALUE>', 'reporter', '{"SecAdmins": "team_lead"}' ) ON CONFLICT (org_id, protocol) DO UPDATE SET is_enabled=EXCLUDED.is_enabled, issuer_or_entity_id=EXCLUDED.issuer_or_entity_id, sso_url=EXCLUDED.sso_url, idp_certificate_enc=EXCLUDED.idp_certificate_enc, updated_at=now();
- For SQLite:
3. SAML 2.0 Integration Specifications
A. Required Parameters from the Organization's IdP:
- IdP Entity ID: Unique URI identifying the IdP (e.g.
https://sts.windows.net/<tenant-uuid>/orhttp://www.okta.com/exk123). - Single Sign-On Service URL (SSO URL): IdP HTTP-Redirect or HTTP-POST endpoint where user AuthnRequests are sent.
- IdP x.509 Certificate: IdP public signing certificate in PEM format to verify digital signatures on SAML assertions.
B. SP Parameters Provided by ARES to the IdP:
- Assertion Consumer Service (ACS) URL:
(Binding: HTTP-POST)POST https://<ares-domain>/auth/sso/saml/acs - Service Provider (SP) Entity ID / Audience:
https://<ares-domain>/auth/sso/saml/metadata - NameID Format: Email Address (
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress) or Persistent (urn:oasis:names:tc:SAML:2.0:nameid-format:persistent).
4. OpenID Connect (OIDC) Integration Specifications
A. Required Parameters from the Organization's IdP:
- Issuer URL: Base URL of the provider (e.g.
https://accounts.google.comorhttps://login.microsoftonline.com/{tenant}/v2.0). - Client ID & Client Secret: OAuth2 client credentials generated in the IdP app console.
- JWKS URI (Optional / Recommended): Public key set endpoint (e.g.
https://idp.example.com/.well-known/jwks.json) for cryptographic ID Token verification. - Authorization & Token Endpoints: IdP OAuth2 authorization and token URLs.
B. Parameters Provided by ARES to the IdP:
- Callback / Redirect URI:
GET https://<ares-domain>/auth/sso/oidc/callback - Grant Type: Authorization Code (
response_type=code). - Scopes:
openid email profile.
5. Verification & Testing Workflow
After saving the configuration, verify the setup without opening database tables:
Verify Initiation Endpoint: Query the initialization endpoint via cURL:
curl -i "http://127.0.0.1:8080/auth/sso/init?org=default"Expected Result: HTTP
200 OKwith JSON response:{ "configured": true, "protocol": "saml", // or "oidc" "redirect_url": "https://idp.example.com/...", "flow_id": "..." }Verify End-to-End via ARES Dashboard UI:
- Navigate to
http://127.0.0.1:5173/dashboard/login. - Click "Or continue with SSO".
- Your browser will seamlessly redirect to your corporate IdP login screen.
- Enter your corporate credentials.
- Upon successful IdP verification, you will be redirected back to the ARES Dashboard (
/dashboard/) with active session cookies (ares-dev-refreshandares-dev-csrf). - Your account is automatically provisioned Just-In-Time (JIT) with the appropriate role according to your claim mappings, defaulting safely to
reporter.
- Navigate to
PART 3 - Troubleshooting Guide for Administrators
Common error messages returned in the login redirect URL (/dashboard/login?error=...) and their resolutions:
| Error Message | Root Cause | Administrative Resolution |
|---|---|---|
Invalid or expired OIDC state (replay rejected) orInvalid or expired SAML request ID (replay rejected) |
The user took longer than 10 minutes to complete sign-in at the IdP, or the user navigated Back, refreshed the callback page, or replayed an expired authorization URL. | Instruct the user to return to /dashboard/login and click "Or continue with SSO" to generate a fresh, single-use authentication state. |
SAML assertion missing InResponseTo (replay protection) |
The IdP sent an assertion lacking the InResponseTo attribute, typically caused by initiating the login from an external IdP portal (IdP-initiated SSO). |
ARES strictly enforces SP-initiated SSO to prevent token replay. Ensure operators initiate sign-in directly from the ARES login page. |
Invalid SAML signature orSignature validation failed |
The stored IdP x.509 certificate does not match the private key used by the IdP to sign the assertion (e.g., following an IdP cert rotation or expiration). | Obtain the current x.509 public signing certificate from the IdP and update the configuration via POST /auth/sso/config/{org_slug}. |
Invalid token issuer or audience (OIDC) |
The iss (issuer) or aud (audience) claim in the IdP's JWT token does not match the configured issuer_or_entity_id or client_id. |
Verify that the client_id and issuer_or_entity_id values in ARES match the exact client registration in your IdP console. |
SSO configuration not found for organization |
The requested organization has no active SSO profile, or is_active = 0 / is_enabled = 0. |
Verify that the organization is active in the organizations table and that its sso_configurations entry has is_enabled = 1. |