ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.
Python active-directorycloud-securitydefensive-validationfastapigood-first-issuemitre-attackopsecreactred-teamreportingsecurity
"""
ARES Enterprise Single Sign-On (SSO) Core Service.
Supports SAML 2.0 (via python3-saml) and OpenID Connect (via authlib).
Features app-level secret encryption, JIT role mapping, and strict replay protection.
"""
from __future__ import annotations
import json
import secrets
import time
import warnings
from collections.abc import Mapping
from typing import Any
from urllib.parse import urlencode
import httpx
from authlib.deprecate import AuthlibDeprecationWarning
warnings.filterwarnings("ignore", category=AuthlibDeprecationWarning)
from authlib.jose import JsonWebKey, JsonWebToken
from authlib.jose import jwt as authlib_jwt # noqa: F401 (kept for compatibility / callers)
# OIDC id_tokens are asymmetrically signed. Pin the decoder to the standard
# asymmetric algorithms so an attacker cannot (a) force a symmetric HS* path
# verified with the shared client_secret, nor (b) mount RSA-public-key-as-HMAC
# "alg confusion" by submitting an HS256 token signed with a public key from the
# IdP's JWKS. (AUDIT run-1 C1)
_OIDC_ID_TOKEN_ALGORITHMS = [
"RS256", "RS384", "RS512",
"ES256", "ES384", "ES512",
"PS256", "PS384", "PS512",
]
_OIDC_JWT = JsonWebToken(_OIDC_ID_TOKEN_ALGORITHMS)
from onelogin.saml2.auth import OneLogin_Saml2_Auth
from onelogin.saml2.settings import OneLogin_Saml2_Settings
from ares.core.config import AresSettings
from ares.core.logger import get_logger
from ares.core.security import DataEncryptor
logger = get_logger("ares.core.sso")
_ALLOWED_ROLES = frozenset({"team_lead", "operator", "recon", "reporter"})
# ── App-Level Secret Encryption ───────────────────────────────────────────────
def encrypt_sso_secret(secret: str | None, settings: AresSettings) -> str:
"""Encrypt sensitive credentials (X.509 certs, client secrets) using DataEncryptor."""
if not secret:
return ""
encryptor = DataEncryptor(settings.encryption_key_value)
encrypted = encryptor.encrypt(secret)
return encrypted or ""
def decrypt_sso_secret(encrypted_secret: str | None, settings: AresSettings) -> str:
"""Decrypt sensitive credentials using DataEncryptor."""
if not encrypted_secret:
return ""
encryptor = DataEncryptor(settings.encryption_key_value)
decrypted = encryptor.decrypt(encrypted_secret)
return decrypted or ""
# ── Role Mapping ─────────────────────────────────────────────────────────────
def map_idp_role(
claims: Mapping[str, Any],
role_mapping_json: str | None,
default_role: str = "reporter",
) -> str:
"""
Map IdP groups/roles to ARES roles.
Strictly defaults to 'reporter' (least privilege) if no match is found.
Never defaults to team_lead or operator.
"""
safe_default = default_role if default_role in _ALLOWED_ROLES else "reporter"
mapping: dict[str, str] = {}
if role_mapping_json:
try:
parsed = json.loads(role_mapping_json)
if isinstance(parsed, dict):
mapping = {str(k): str(v) for k, v in parsed.items()}
except Exception:
logger.warning("sso_role_mapping_parse_failed")
# Inspect common claim keys where IdP sends roles or groups
candidate_groups: list[str] = []
group_keys = (
"roles",
"groups",
"role",
"http://schemas.microsoft.com/ws/2008/06/identity/claims/groups",
"http://schemas.microsoft.com/ws/2008/06/identity/claims/role",
"cognito:groups",
)
for key in group_keys:
val = claims.get(key)
if isinstance(val, list):
candidate_groups.extend(str(item) for item in val)
elif isinstance(val, str):
candidate_groups.append(val)
# Check realm_access / resource_access (Keycloak standard)
realm_access = claims.get("realm_access")
if isinstance(realm_access, dict):
roles = realm_access.get("roles")
if isinstance(roles, list):
candidate_groups.extend(str(r) for r in roles)
# Map candidate groups to ARES roles
for group in candidate_groups:
if group in mapping:
target_role = mapping[group]
if target_role in _ALLOWED_ROLES:
return target_role
# Direct match if IdP explicitly passed an ARES role name
for group in candidate_groups:
lowered = group.lower()
if lowered in _ALLOWED_ROLES:
return lowered
return safe_default
# ── SAML 2.0 Flow ─────────────────────────────────────────────────────────────
def _build_saml_settings_dict(
sso_config: Mapping[str, Any],
base_url: str,
idp_cert: str,
) -> dict[str, Any]:
"""Construct python3-saml settings dictionary."""
sp_entity_id = sso_config.get("sp_entity_id") or f"{base_url}/auth/sso/saml/metadata"
acs_url = sso_config.get("acs_url") or f"{base_url}/auth/sso/saml/acs"
idp_entity_id = sso_config.get("issuer_or_entity_id", "")
sso_url = sso_config.get("sso_url", "")
# Clean certificate formatting (remove PEM headers if present for python3-saml)
clean_cert = idp_cert.replace("-----BEGIN CERTIFICATE-----", "")
clean_cert = clean_cert.replace("-----END CERTIFICATE-----", "")
clean_cert = clean_cert.replace("\r", "").replace("\n", "").strip()
return {
"strict": True,
"debug": False,
"sp": {
"entityId": sp_entity_id,
"assertionConsumerService": {
"url": acs_url,
"binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
},
"NameIDFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
"x509cert": "",
"privateKey": "",
},
"idp": {
"entityId": idp_entity_id,
"singleSignOnService": {
"url": sso_url,
"binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
},
"x509cert": clean_cert,
},
"security": {
"nameIdEncrypted": False,
"authnRequestsSigned": False,
"logoutRequestSigned": False,
"logoutResponseSigned": False,
"signMetadata": False,
"wantMessagesSigned": False,
"wantAssertionsSigned": True, # Require signed assertions
"wantNameId": True,
"wantNameIdEncrypted": False,
"wantAssertionsEncrypted": False,
"signatureAlgorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
"digestAlgorithm": "http://www.w3.org/2001/04/xmlenc#sha256",
},
}
def build_saml_auth_request(
sso_config: Mapping[str, Any],
base_url: str,
settings: AresSettings,
) -> tuple[str, str]:
"""
Generate SAML AuthnRequest.
Returns (redirect_url, request_id).
"""
idp_cert = decrypt_sso_secret(sso_config.get("idp_certificate_enc"), settings)
saml_settings_dict = _build_saml_settings_dict(sso_config, base_url, idp_cert)
saml_settings = OneLogin_Saml2_Settings(saml_settings_dict)
# Empty dummy request for OneLogin_Saml2_Auth initialization
req = {
"https": "on" if base_url.startswith("https") else "off",
"http_host": base_url.split("://")[-1],
"script_name": "/auth/sso/saml/acs",
"get_data": {},
"post_data": {},
}
auth = OneLogin_Saml2_Auth(req, old_settings=saml_settings)
redirect_url = auth.login()
request_id = auth.get_last_request_id()
if not request_id:
request_id = f"ARES_SAML_{secrets.token_hex(16)}"
return redirect_url, request_id
def process_saml_response(
sso_config: Mapping[str, Any],
post_data: dict[str, Any],
expected_request_id: str,
base_url: str,
settings: AresSettings,
) -> dict[str, Any]:
"""
Process SAML ACS response (HTTP-POST).
Validates XML signature, expiration, and InResponseTo.
Returns extracted user profile and mapped role.
"""
idp_cert = decrypt_sso_secret(sso_config.get("idp_certificate_enc"), settings)
saml_settings_dict = _build_saml_settings_dict(sso_config, base_url, idp_cert)
saml_settings = OneLogin_Saml2_Settings(saml_settings_dict)
req = {
"https": "on" if base_url.startswith("https") else "off",
"http_host": base_url.split("://")[-1],
"script_name": "/auth/sso/saml/acs",
"get_data": {},
"post_data": post_data,
}
auth = OneLogin_Saml2_Auth(req, old_settings=saml_settings)
auth.process_response(request_id=expected_request_id)
errors = auth.get_errors()
if errors:
reason = auth.get_last_error_reason() or ", ".join(errors)
logger.warning("saml_assertion_validation_failed", error=reason)
raise ValueError(f"SAML assertion verification failed: {reason}")
if not auth.is_authenticated():
reason = auth.get_last_error_reason() or "Assertion not authenticated"
logger.warning("saml_not_authenticated", error=reason)
raise ValueError(f"SAML authentication rejected: {reason}")
nameid = auth.get_nameid()
attributes = auth.get_attributes()
# Determine username/email from NameID and attributes
email = ""
email_keys = (
"email",
"mail",
"userPrincipalName",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
)
for ek in email_keys:
val = attributes.get(ek)
if val and isinstance(val, list) and len(val) > 0:
email = str(val[0])
break
username = email.split("@")[0] if email and "@" in email else (nameid or f"saml_{secrets.token_hex(4)}")
role = map_idp_role(
attributes,
sso_config.get("role_mapping_json"),
default_role=sso_config.get("default_role", "reporter"),
)
return {
"username": username,
"email": email,
"external_id": nameid,
"role": role,
"attributes": attributes,
}
# ── OpenID Connect (OIDC) Flow ───────────────────────────────────────────────
def build_oidc_auth_request(
sso_config: Mapping[str, Any],
redirect_uri: str,
) -> tuple[str, str, str]:
"""
Generate OIDC authorization URL with state and nonce.
Returns (authorization_url, state, nonce).
"""
client_id = sso_config.get("client_id", "")
auth_endpoint = sso_config.get("sso_url", "")
if not auth_endpoint:
raise ValueError("OIDC sso_url (authorization endpoint) is not configured")
state = secrets.token_urlsafe(32)
nonce = secrets.token_urlsafe(32)
params = {
"client_id": client_id,
"response_type": "code",
"scope": "openid profile email",
"redirect_uri": redirect_uri,
"state": state,
"nonce": nonce,
}
delimiter = "&" if "?" in auth_endpoint else "?"
redirect_url = f"{auth_endpoint}{delimiter}{urlencode(params)}"
return redirect_url, state, nonce
async def process_oidc_callback(
sso_config: Mapping[str, Any],
code: str,
redirect_uri: str,
expected_nonce: str,
settings: AresSettings,
http_client: httpx.AsyncClient | None = None,
) -> dict[str, Any]:
"""
Process OIDC callback code.
Exchanges code for tokens, validates ID token signature via JWKS,
enforces iss, aud, exp, and nonce matching.
"""
client_id = sso_config.get("client_id", "")
client_secret = decrypt_sso_secret(sso_config.get("client_secret_enc"), settings)
issuer = sso_config.get("issuer_or_entity_id", "")
token_endpoint = sso_config.get("acs_url") # In OIDC, acs_url holds token_endpoint
jwks_uri = sso_config.get("jwks_uri", "")
if not token_endpoint:
raise ValueError("OIDC token endpoint (acs_url) is not configured")
client = http_client or httpx.AsyncClient(timeout=15.0)
should_close = http_client is None
try:
# 1. Exchange authorization code for tokens
token_resp = await client.post(
token_endpoint,
data={
"grant_type": "authorization_code",
"code": code,
"redirect_uri": redirect_uri,
"client_id": client_id,
"client_secret": client_secret,
},
headers={"Accept": "application/json"},
)
if token_resp.status_code >= 400:
# Do NOT log token_resp.text — IdPs often reflect the submitted `code`,
# `redirect_uri`, and sometimes substrings of `client_id`/`client_secret`
# in `error_description`, which would land in the loguru sink's retention.
# Status code alone is enough for operational triage. (AUDIT run-1 M14)
logger.warning("oidc_token_exchange_failed", status=token_resp.status_code)
raise ValueError(f"OIDC token exchange failed: HTTP {token_resp.status_code}")
token_data = token_resp.json()
id_token = token_data.get("id_token")
if not id_token:
raise ValueError("OIDC response missing id_token")
# 2. Verify the id_token signature against the IdP's published JWKS.
# jwks_uri is mandatory: there is no symmetric fallback. Verifying an
# OIDC id_token with the shared client_secret (HS*) would let anyone
# who holds that secret mint a token asserting any identity/role.
# (AUDIT run-1 C1)
if not jwks_uri:
raise ValueError(
"OIDC configuration is missing jwks_uri; refusing to verify the "
"id_token without the IdP's published asymmetric signing keys."
)
jwks_resp = await client.get(jwks_uri)
if jwks_resp.status_code >= 400:
raise ValueError("Failed to fetch OIDC JWKS from the identity provider")
jwks = jwks_resp.json()
key_set = JsonWebKey.import_key_set(jwks)
claims = _OIDC_JWT.decode(id_token, key_set)
# 3. Validate standard claims. Each required claim is enforced; an absent
# iss/aud/exp must be a hard failure, not a silently-skipped check.
now = time.time()
exp = claims.get("exp")
if not exp or exp < now:
raise ValueError("OIDC id_token is missing exp or has expired")
# iss is REQUIRED and must match the configured issuer. An empty configured
# issuer means we cannot establish the token's origin, so we refuse.
if not issuer:
raise ValueError(
"OIDC configuration is missing issuer_or_entity_id; cannot validate id_token iss"
)
if str(claims.get("iss", "")) != issuer:
raise ValueError("OIDC issuer mismatch")
# aud is REQUIRED and must contain our client_id. A token with no aud claim
# (previously accepted by falling through both isinstance branches) is rejected.
token_aud = claims.get("aud")
if isinstance(token_aud, list):
if client_id not in token_aud:
raise ValueError("OIDC aud mismatch")
elif isinstance(token_aud, str):
if token_aud != client_id:
raise ValueError("OIDC aud mismatch")
else:
raise ValueError("OIDC id_token is missing or has a malformed aud claim")
token_nonce = claims.get("nonce")
if expected_nonce and token_nonce != expected_nonce:
raise ValueError("OIDC nonce mismatch (replay protection triggered)")
sub = str(claims.get("sub", ""))
email = str(claims.get("email") or claims.get("preferred_username") or "")
username = email.split("@")[0] if email and "@" in email else (claims.get("preferred_username") or sub)
role = map_idp_role(
claims,
sso_config.get("role_mapping_json"),
default_role=sso_config.get("default_role", "reporter"),
)
return {
"username": username,
"email": email,
"external_id": sub,
"role": role,
"claims": dict(claims),
}
finally:
if should_close:
await client.aclose()