Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.
Python agentic-aiai-securityalert-triageblue-teamcybersecuritydetection-engineeringincident-responselanggraphllm-agentsmcpmitre-attackmodel-context-protocolpurple-teamsecurity-operationsself-hostedsiemsoarsocthreat-detectionthreat-intelligence
"""
SAML 2.0 Service Provider implementation for AiSOC.
Flow:
1. GET /auth/saml/login → redirect to IdP SSO URL
2. POST /auth/saml/acs ← IdP posts assertion here (ACS)
3. GET /auth/saml/metadata → SP metadata (share with IdP)
4. GET /auth/saml/logout → SLO initiation (optional)
Dependencies (optional):
- python3-saml (onelogin/python3-saml) if available
- Refuses with 501 when not installed, rather than inventing an identity
Where the identity provider comes from (fix pass 4.1)
-----------------------------------------------------
The **connection row**, not the environment. `aisoc_sso_connections`
carries `metadata_url` and `metadata_xml` per connection; both were
written by `POST /sso-connections` and read by nothing, so an
administrator could configure an IdP in the console and the deployment
would go on trusting whatever `SAML_IDP_*` said — which on a stock install
is nothing, so every assertion was refused. See
`app/auth/saml_metadata.py`.
The `SAML_IDP_*` variables below remain as a fallback for deployments that
configured SAML before connections were readable. A connection wins over
them whenever one resolves.
Configuration (env vars):
SAML_SP_ENTITY_ID SP Entity ID (defaults to ACS URL)
SAML_SP_ACS_URL Assertion Consumer Service URL
SAML_SP_PRIVATE_KEY SP private key PEM (optional, for signed requests)
SAML_SP_CERT SP certificate PEM (optional)
SAML_IDP_ENTITY_ID Fallback IdP Entity ID (issuer)
SAML_IDP_SSO_URL Fallback IdP SSO redirect URL
SAML_IDP_SLO_URL Fallback IdP SLO URL (optional)
SAML_IDP_CERT Fallback IdP X.509 certificate (PEM or single-line base64)
JWT_SECRET Secret used to sign issued JWTs
JWT_ALGORITHM HS256 (default)
JWT_EXPIRE_MINUTES Token lifetime (default: 480 = 8h)
"""
from __future__ import annotations
import logging
import os
import re
from datetime import UTC, datetime, timedelta
from typing import Any
from urllib.parse import quote
import jwt as _jwt
from fastapi import APIRouter, HTTPException, Request, status
from fastapi.responses import RedirectResponse, Response
from app.api.v1.deps import DBSession
from app.auth.saml_metadata import (
SamlTrustError,
environment_idp_is_configured,
environment_idp_settings,
idp_settings_for_connection,
issuer_from_saml_response,
resolve_saml_connection,
)
from app.auth.sso_provisioning import SsoProvisioningError, complete_sso_login
logger = logging.getLogger(__name__)
_SAFE_REDIRECT_RE = re.compile(r"^/[\w\-./]*$")
_SAFE_PATH_CHARS_RE = re.compile(r"[^\w\-./]")
def _safe_redirect(url: str) -> str:
"""Return a safe relative path derived from *url*; otherwise return '/'.
The path is *reconstructed* from allowed characters so that CodeQL's
taint tracking does not propagate the original user-supplied string
through to the redirect response.
"""
if url and _SAFE_REDIRECT_RE.match(url):
safe_path = "/" + _SAFE_PATH_CHARS_RE.sub("", url.lstrip("/"))
return safe_path
return "/"
router = APIRouter(prefix="/auth/saml", tags=["auth-saml"])
# ─── JWT helpers ──────────────────────────────────────────────────────────────
_JWT_SECRET = os.getenv("JWT_SECRET", "")
_JWT_ALGORITHM = os.getenv("JWT_ALGORITHM", "HS256")
_JWT_EXPIRE_MINUTES = int(os.getenv("JWT_EXPIRE_MINUTES", "480"))
def _issue_jwt(claims: dict[str, Any]) -> str:
# Refuse to mint a token signed with a missing or well-known-default
# secret. Previously this defaulted to ``"changeme-insecure-default"``,
# so a misconfigured deployment would happily sign session tokens with
# a value that's literally checked into source. We now fail closed and
# let the caller surface a 503/500 — operators must wire ``JWT_SECRET``
# explicitly (e.g. via Fly/k8s secrets).
if not _JWT_SECRET or _JWT_SECRET == "changeme-insecure-default":
raise RuntimeError("JWT_SECRET is not configured. Set the env var to a long random string before issuing SAML session tokens.")
payload = {
**claims,
"iat": datetime.now(UTC),
"exp": datetime.now(UTC) + timedelta(minutes=_JWT_EXPIRE_MINUTES),
}
return _jwt.encode(payload, _JWT_SECRET, algorithm=_JWT_ALGORITHM)
# ─── SAML settings builder ────────────────────────────────────────────────────
def _saml_settings(idp: dict[str, Any] | None = None) -> dict[str, Any]:
"""The python3-saml settings for this service provider.
The SP half is deployment-wide: one service, one ACS URL, one
certificate. The **IdP half is per connection** and is passed in —
`idp=None` falls back to `SAML_IDP_*`, which is how a pre-4.1
deployment was configured and the only thing that used to be possible.
"""
sp_acs = os.getenv("SAML_SP_ACS_URL", "http://localhost:8000/auth/saml/acs")
sp_entity = os.getenv("SAML_SP_ENTITY_ID", sp_acs)
sp_key = os.getenv("SAML_SP_PRIVATE_KEY", "")
sp_cert = os.getenv("SAML_SP_CERT", "")
return {
"strict": True,
"debug": os.getenv("SAML_DEBUG", "false").lower() == "true",
"security": {
# Keycloak's built-in "role list" mapper is on by default and
# emits **one `<Attribute Name="Role">` element per role**, so
# a stock Keycloak sends six of them before anybody adds a
# mapper. python3-saml defaults `allowRepeatAttributeName` to
# False and raises `Found an Attribute element with duplicated
# Name` out of `process_response()` — past every `except` this
# handler has, so the ACS answered an unhandled 500 and **no
# Keycloak user could complete a SAML sign-in at all**.
#
# Repeated `<Attribute>` elements are legal SAML 2.0 and this
# merges their values rather than refusing the assertion. It is
# not a relaxation of trust: `process_response()` calls
# `response.is_valid()` — signature, conditions and audience —
# and only reads attributes once that has passed, so an
# attacker cannot add an element without invalidating the
# signature that admitted it.
#
# Found by depth 8.1's containerised-IdP probe. The
# self-authored provider in `tests/isolation/test_sso_live.py`
# emits one attribute per name, so it could not have found it.
"allowRepeatAttributeName": True,
},
"sp": {
"entityId": sp_entity,
"assertionConsumerService": {
"url": sp_acs,
"binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
},
"singleLogoutService": {
"url": sp_acs.replace("/acs", "/slo"),
"binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
},
"privateKey": sp_key,
"x509cert": sp_cert,
},
"idp": idp if idp is not None else environment_idp_settings(),
}
async def _resolve_idp(db: DBSession, *, issuer: str | None) -> tuple[dict[str, Any], str]:
"""The IdP settings block and the issuer that keys its connection.
Returns `(idp_settings, issuer)`. The issuer returned is the one the
**connection** declares, never the one an assertion claimed: the
assertion's issuer only selected which connection to look at, and
`complete_sso_login` resolves the tenant from the row this returns the
key of.
"""
connection = await resolve_saml_connection(db, issuer=issuer)
if connection is not None:
return await idp_settings_for_connection(connection), str(connection["issuer"])
if environment_idp_is_configured():
env = environment_idp_settings()
logger.info("saml.trust_from_environment no connection row matched; using SAML_IDP_* ")
return env, str(env["entityId"])
raise SamlTrustError(
"no enabled SAML connection is configured for this deployment. Create one with "
"POST /api/v1/sso-connections carrying the identity provider's metadata_url or metadata_xml."
)
# ─── Routes ───────────────────────────────────────────────────────────────────
@router.get("/login")
async def saml_login(request: Request, db: DBSession, redirect: str = "/", issuer: str | None = None) -> Response:
"""Initiate SAML SSO — redirect to the IdP this connection names.
`issuer` is optional and the console does not send one: a deployment
with a single enabled SAML connection has an unambiguous answer. It
exists so a deployment with several can link one button per provider.
"""
from app.auth.oidc import _require_sso_enabled # noqa: PLC0415
_require_sso_enabled()
try:
from onelogin.saml2.auth import OneLogin_Saml2_Auth # type: ignore[import]
idp, _issuer = await _resolve_idp(db, issuer=issuer)
req = await _build_saml_request(request)
auth = OneLogin_Saml2_Auth(req, _saml_settings(idp))
login_url: str = auth.login(return_to=redirect)
return RedirectResponse(url=login_url)
except SamlTrustError as exc:
# A configuration problem, named. "SAML error: Invalid dict
# settings: idp_sso_url_invalid" sent an operator to read
# python3-saml's source; this sends them to the connection they
# thought they had configured.
logger.warning("saml.login_unconfigured reason=%s", str(exc).replace("\r", "").replace("\n", " ")[:300])
raise HTTPException(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail=str(exc)) from exc
except ImportError as exc:
# 501, not a page that looks like a login. This branch used to render
# a stub and the one below it used to mint a token, and since
# python3-saml was declared in no manifest, the stub was the only
# reachable path on a stock install.
logger.error("SAML is enabled but python3-saml is not installed")
raise HTTPException(
status_code=status.HTTP_501_NOT_IMPLEMENTED,
detail=("SAML is not available on this deployment: python3-saml is not installed. Install it, or use OIDC."),
) from exc
except Exception as exc:
logger.exception("SAML login error")
raise HTTPException(status_code=500, detail=f"SAML error: {exc}") from exc
@router.post("/acs")
async def saml_acs(request: Request, db: DBSession) -> Response:
"""Assertion Consumer Service — process IdP POST-back and issue JWT."""
from app.auth.oidc import _require_sso_enabled
_require_sso_enabled()
try:
from onelogin.saml2.auth import OneLogin_Saml2_Auth # type: ignore[import]
req = await _build_saml_request(request)
# The issuer the response names picks which connection's
# certificate to verify against. It confers nothing: an assertion
# naming an issuer whose private key the sender does not hold fails
# `process_response()` two lines below, and the tenant comes from
# the connection row either way.
claimed_issuer = issuer_from_saml_response(str(req.get("post_data", {}).get("SAMLResponse") or ""))
idp, connection_issuer = await _resolve_idp(db, issuer=claimed_issuer)
auth = OneLogin_Saml2_Auth(req, _saml_settings(idp))
auth.process_response()
errors = auth.get_errors()
if errors:
raise HTTPException(status_code=400, detail=f"SAML errors: {errors}")
if not auth.is_authenticated():
raise HTTPException(status_code=401, detail="SAML authentication failed")
attrs = auth.get_attributes()
name_id = auth.get_nameid()
email_claim = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
name_claim = "http://schemas.microsoft.com/identity/claims/displayname"
group_claim = "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"
# Parity 4.1. Same change as the OIDC callback, and for the same
# reason: this issued a JWT with no tenant, no role and no local
# user, signed with `JWT_SECRET` rather than the key the API
# verifies with, into a cookie the API does not read.
groups = [str(g) for g in (attrs.get("groups") or attrs.get(group_claim) or attrs.get("memberOf") or []) if g]
try:
session = await complete_sso_login(
db,
provider="saml",
# The entity id the *connection* declares, not the one the
# assertion claimed. They are equal on the path that got
# here — the signature verified against that connection's
# certificate — and passing the connection's value means a
# future change to selection cannot turn the assertion into
# the thing that chooses the tenant.
issuer=connection_issuer,
email=str(_first(attrs.get("email") or attrs.get(email_claim, [name_id]))),
subject=str(name_id or ""),
name=_first(attrs.get("displayName") or attrs.get(name_claim, [])),
groups=groups,
# A SAML assertion is signed by the identity provider, and the
# address it asserts *is* the provider's statement about the
# user -- there is no separate `email_verified` claim to
# consult, and the signature is the assurance OIDC uses that
# claim to provide. Stated here rather than defaulted inside
# `complete_sso_login`, so a reader of either caller can see
# which assurance applies.
email_verified=True,
)
except SsoProvisioningError as exc:
raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(exc)) from exc
# Land on the login page, not on the RelayState destination, and
# carry the refresh token too. Both halves were defects:
#
# `handleUnauthorized` in `apps/web/src/lib/api.ts` builds its
# bounce target from `pathname + search`, so an auth guard on
# `/alerts` redirects to `/login?next=/alerts` and **drops the
# fragment** — taking the only copy of the token with it. The OIDC
# callback already lands on /login for exactly this reason; this
# one did not, so a SAML sign-in could not complete in the console
# however valid the assertion.
#
# And the console's fragment consumer persists `refresh_token`
# alongside the access token; omitting it logged the user out
# silently when the access token expired.
relay_state = _safe_redirect(str((await request.form()).get("RelayState", "/")))
redirect_url = f"/login?next={quote(relay_state, safe='')}"
# In the fragment, which browsers do not send to the server and
# which does not land in an access log or a Referer header.
return RedirectResponse(
url=f"{redirect_url}{_session_fragment(session)}",
status_code=302,
)
except SamlTrustError as exc:
logger.warning("saml.acs_unconfigured reason=%s", str(exc).replace("\r", "").replace("\n", " ")[:300])
raise HTTPException(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail=str(exc)) from exc
except ImportError as exc:
# This issued a signed session for a principal called
# `stub-saml-user` that no identity provider had ever seen, from an
# exception handler that had verified nothing. It is a 501 now: an
# assertion consumer with no library to consume assertions has
# nothing to say about who the caller is.
logger.error("SAML ACS reached but python3-saml is not installed")
raise HTTPException(
status_code=status.HTTP_501_NOT_IMPLEMENTED,
detail=("SAML is not available on this deployment: python3-saml is not installed."),
) from exc
@router.get("/metadata")
async def saml_metadata() -> Response:
"""Return SP SAML metadata XML."""
try:
from onelogin.saml2.settings import OneLogin_Saml2_Settings # type: ignore[import]
settings_obj = OneLogin_Saml2_Settings(settings=_saml_settings(), sp_validation_only=True)
metadata, _errors = settings_obj.get_sp_metadata(), []
return Response(content=metadata, media_type="application/xml")
except ImportError:
sp_acs = os.getenv("SAML_SP_ACS_URL", "http://localhost:8000/auth/saml/acs")
sp_entity = os.getenv("SAML_SP_ENTITY_ID", sp_acs)
xml = f"""<?xml version="1.0"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="{sp_entity}">
<md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="true"
protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
Location="{sp_acs}" index="1"/>
</md:SPSSODescriptor>
</md:EntityDescriptor>"""
return Response(content=xml, media_type="application/xml")
@router.get("/logout")
async def saml_logout(request: Request, db: DBSession, issuer: str | None = None) -> Response:
"""Initiate SAML SLO, at the SingleLogoutService the connection names.
Resolved the same way `/login` is. A deployment whose IdP comes from a
connection has no `SAML_IDP_SLO_URL`, so this used to build a logout
request against an empty endpoint and 500 on the way out of a session.
An SLO that cannot be initiated is a local logout, not an error.
"""
try:
from onelogin.saml2.auth import OneLogin_Saml2_Auth # type: ignore[import]
idp, _issuer = await _resolve_idp(db, issuer=issuer)
req = await _build_saml_request(request)
auth = OneLogin_Saml2_Auth(req, _saml_settings(idp))
name_id = request.cookies.get("saml_name_id", "")
logout_url: str = auth.logout(name_id=name_id)
response = RedirectResponse(url=logout_url)
response.delete_cookie("aisoc_token")
response.delete_cookie("saml_name_id")
return response
except Exception: # noqa: BLE001
# Every failure here ends the same way, so they are not
# distinguished: python3-saml missing, no connection configured, or
# an IdP that publishes no SingleLogoutService. The session is
# already being discarded locally, and refusing to do that because
# the provider cannot be told would leave the user signed in.
logger.info("saml.slo_unavailable falling back to local logout")
response = RedirectResponse(url="/login")
response.delete_cookie("aisoc_token")
response.delete_cookie("saml_name_id")
return response
# ─── Helpers ──────────────────────────────────────────────────────────────────
def _first(lst: list[str]) -> str:
return lst[0] if lst else ""
def _session_fragment(session: dict[str, Any]) -> str:
"""The URL fragment a completed callback lands on.
Two outcomes, and the difference is whether a session exists at all.
When the tenant's policy requires a second factor of this role and
the provider did not assert one, `complete_sso_login` returns a
challenge and **no tokens** — so there is nothing to put in the
fragment but the challenge, and the console's sign-in page asks for
the factor before anybody is signed in.
Reading `access_token` unconditionally, as this did before depth 8.1,
would raise `KeyError` inside the handler on exactly the deployments
that enforce MFA. Shared with the OIDC callback so the two cannot
answer differently.
"""
if session.get("mfa_required") or session.get("mfa_enrollment_required"):
methods = ",".join(str(m) for m in (session.get("methods") or []))
key = "mfa_required" if session.get("mfa_required") else "mfa_enrollment_required"
return f"#{key}=1&mfa_token={quote(str(session['mfa_token']), safe='')}&methods={quote(methods, safe='')}"
return f"#access_token={session['access_token']}&refresh_token={session['refresh_token']}"
async def _build_saml_request(request: Request) -> dict[str, Any]:
"""Convert FastAPI request to the dict expected by python3-saml."""
body = await request.body()
form = await request.form() if request.method == "POST" else {}
return {
"https": "on" if request.url.scheme == "https" else "off",
"http_host": request.headers.get("host", request.url.netloc),
"server_port": str(request.url.port or (443 if request.url.scheme == "https" else 80)),
"script_name": request.url.path,
"get_data": dict(request.query_params),
"post_data": dict(form),
"body": body,
}