saml2-sp 0.1.0__py3-none-any.whl

saml2_sp/__init__.py

@@ -0,0 +1,35 @@
+# SPDX-FileCopyrightText: 2026 Iya CyberSecurity Solutions, LLC
+# SPDX-License-Identifier: MIT
+"""saml2-sp: a server-side SAML 2.0 service provider."""
+
+from saml2_sp.bindings import post_form_html
+from saml2_sp.config import read_config_file, resolve_config
+from saml2_sp.errors import SamlError, SamlStatus
+from saml2_sp.replay import MemoryReplayCache
+from saml2_sp.service_provider import ServiceProvider
+from saml2_sp.ssf.events import CAEP_EVENTS, DEFAULT_ENDING_EVENTS, DEFAULT_EVENTS_REQUESTED, EVENT, RISC_EVENTS, subject_of
+from saml2_sp.ssf.receiver import SignalEvent, SignalsReceiver
+from saml2_sp.ssf.session_index import DEFAULT_SUBJECT_ATTRIBUTE, MemorySessionIndex, tracked_from
+from saml2_sp.x509util import create_self_signed_key_pair
+
+__all__ = [
+    "CAEP_EVENTS",
+    "DEFAULT_ENDING_EVENTS",
+    "DEFAULT_EVENTS_REQUESTED",
+    "DEFAULT_SUBJECT_ATTRIBUTE",
+    "EVENT",
+    "MemoryReplayCache",
+    "MemorySessionIndex",
+    "RISC_EVENTS",
+    "SamlError",
+    "SamlStatus",
+    "ServiceProvider",
+    "SignalEvent",
+    "SignalsReceiver",
+    "create_self_signed_key_pair",
+    "post_form_html",
+    "read_config_file",
+    "resolve_config",
+    "subject_of",
+    "tracked_from",
+]

saml2_sp/artifact.py

@@ -0,0 +1,86 @@
+# SPDX-FileCopyrightText: 2026 Iya CyberSecurity Solutions, LLC
+# SPDX-License-Identifier: MIT
+"""The HTTP-Artifact binding, as the receiving side of a Response."""
+
+from __future__ import annotations
+
+import hashlib
+from datetime import datetime, timezone
+
+from saml2_sp.backchannel import send
+from saml2_sp.errors import SamlError
+from saml2_sp.signature import sign_enveloped, verify_signed
+from saml2_sp.xml import NS, STATUS_SUCCESS, assert_unique_ids, attr, child, children, escape_xml, new_id, parse_xml, text
+
+
+def _iso(when: datetime | None = None) -> str:
+    when = when or datetime.now(timezone.utc)
+    return when.strftime("%Y-%m-%dT%H:%M:%S.") + f"{when.microsecond // 1000:03d}Z"
+
+
+def parse_artifact(saml_art: str) -> dict:
+    import base64
+    import re
+    raw = base64.b64decode(re.sub(r"\s+", "", saml_art))
+    if len(raw) != 44 or int.from_bytes(raw[0:2], "big") != 0x0004:
+        raise SamlError("artifact", "SAMLart is not a SAML 2.0 type 0x0004 artifact")
+    return {"endpoint_index": int.from_bytes(raw[2:4], "big"), "source_id": raw[4:24]}
+
+
+def resolve_artifact(data: dict) -> dict:
+    import os
+    parsed = parse_artifact(data["artifact"])
+    expected = hashlib.sha1(data["idp_entity_id"].encode("utf-8")).digest()
+    if parsed["source_id"] != expected:
+        raise SamlError("artifact", f"the artifact was not issued by {data['idp_entity_id']}")
+    services: dict[int, str] = data["artifact_resolution_services"]
+    location = services.get(parsed["endpoint_index"])
+    if location is None and parsed["endpoint_index"] == 0 and services:
+        location = next(iter(services.values()))
+    if not location:
+        raise SamlError("artifact", f"the identity provider's metadata has no SOAP ArtifactResolutionService with index {parsed['endpoint_index']}")
+    element_id = new_id(os.urandom(20).hex())
+    unsigned = (
+        f'<samlp:ArtifactResolve xmlns:samlp="{NS["samlp"]}" xmlns:saml="{NS["saml"]}" ID="{element_id}" Version="2.0" '
+        f'IssueInstant="{_iso()}" Destination="{escape_xml(location)}">'
+        f'<saml:Issuer>{escape_xml(data["entity_id"])}</saml:Issuer>'
+        f'<samlp:Artifact>{escape_xml(data["artifact"])}</samlp:Artifact>'
+        "</samlp:ArtifactResolve>"
+    )
+    signed = sign_enveloped(unsigned, element_id, data["key"], data["certificate"])
+    envelope = (
+        '<?xml version="1.0" encoding="UTF-8"?>'
+        f'<soap:Envelope xmlns:soap="{NS["soap"]}"><soap:Body>{signed}</soap:Body></soap:Envelope>'
+    )
+    answer = send(location, method="POST", headers={
+        "content-type": "text/xml; charset=utf-8",
+        "soapaction": '"http://www.oasis-open.org/committees/security"',
+        "accept": "text/xml",
+    }, body=envelope, tls=data.get("tls") or {}, code="artifact")
+    if answer.status != 200:
+        raise SamlError("artifact", f"the artifact resolution service answered HTTP {answer.status}")
+    root = parse_xml(answer.body, "the ArtifactResponse")
+    assert_unique_ids(root)
+    body = child(root, NS["soap"], "Body") if root.tag == f"{{{NS['soap']}}}Envelope" else None
+    artifact_response = child(body, NS["samlp"], "ArtifactResponse") if body is not None else None
+    if artifact_response is None:
+        raise SamlError("artifact", "the artifact resolution service did not answer with a SOAP ArtifactResponse")
+    xml = answer.body
+    signed_response = verify_signed(artifact_response, data["idp_certificates"], "the ArtifactResponse")
+    if signed_response is not None:
+        xml = signed_response
+        artifact_response = parse_xml(signed_response, "the signed ArtifactResponse")
+    if attr(artifact_response, "InResponseTo") != element_id:
+        raise SamlError("artifact", "the ArtifactResponse does not answer this ArtifactResolve")
+    issuer = child(artifact_response, NS["saml"], "Issuer")
+    if issuer is not None and text(issuer) != data["idp_entity_id"]:
+        raise SamlError("artifact", f"the ArtifactResponse was issued by {text(issuer)}")
+    status = child(artifact_response, NS["samlp"], "Status")
+    code_el = child(status, NS["samlp"], "StatusCode") if status is not None else None
+    code = attr(code_el, "Value") if code_el is not None else (attr(status, "Value") if status is not None else None)
+    if code != STATUS_SUCCESS:
+        raise SamlError("artifact", f"the artifact resolution failed: {code or 'no status'}")
+    responses = children(artifact_response, NS["samlp"], "Response")
+    if not responses:
+        raise SamlError("artifact", "the identity provider did not resolve the artifact (unknown, expired, or already used)")
+    return {"xml": xml, "response": responses[0]}

saml2_sp/backchannel.py

@@ -0,0 +1,94 @@
+# SPDX-FileCopyrightText: 2026 Iya CyberSecurity Solutions, LLC
+# SPDX-License-Identifier: MIT
+"""The back channel: identity-provider metadata and artifact resolution. TLS is verified."""
+
+from __future__ import annotations
+
+import os
+import ssl
+import tempfile
+import urllib.error
+import urllib.request
+
+from saml2_sp.errors import SamlError
+
+MAX_BYTES = 2 * 1024 * 1024
+TIMEOUT_S = 15
+
+
+class HttpAnswer:
+    def __init__(self, status: int, content_type: str, body: str) -> None:
+        self.status = status
+        self.content_type = content_type
+        self.body = body
+
+
+def send(url: str, method: str = "GET", headers: dict[str, str] | None = None, body: str | None = None,
+         tls: dict[str, str] | None = None, code: str = "metadata") -> HttpAnswer:
+    if not (url.startswith("https://") or url.startswith("http://")):
+        raise SamlError(code, f"{url} is not an http(s) URL")
+    data = None if body is None else body.encode("utf-8")
+    req_headers = dict(headers or {})
+    if data is not None:
+        req_headers["content-length"] = str(len(data))
+    request = urllib.request.Request(url, data=data, headers=req_headers, method=method)
+    ctx = None
+    temps: list[str] = []
+    tls = tls or {}
+    if url.startswith("https://"):
+        ctx = ssl.create_default_context()
+        if tls.get("ca"):
+            ctx.load_verify_locations(cadata=tls["ca"])
+        if tls.get("cert") and tls.get("key"):
+            cert_path = _write_temp(tls["cert"])
+            key_path = _write_temp(tls["key"])
+            temps.extend([cert_path, key_path])
+            ctx.load_cert_chain(cert_path, key_path)
+    try:
+        try:
+            response = urllib.request.urlopen(request, timeout=TIMEOUT_S, context=ctx)
+        except urllib.error.HTTPError as err:
+            response = err
+        except Exception as err:
+            raise SamlError(code, f"{url}: {err}") from err
+        chunks: list[bytes] = []
+        size = 0
+        while True:
+            part = response.read(65536)
+            if not part:
+                break
+            size += len(part)
+            if size > MAX_BYTES:
+                raise SamlError(code, f"{url} answered more than {MAX_BYTES} bytes")
+            chunks.append(part)
+        content_type = ""
+        if response.headers is not None:
+            content_type = response.headers.get("content-type") or ""
+        status = getattr(response, "status", None)
+        if status is None:
+            status = response.getcode()
+        return HttpAnswer(int(status or 0), content_type, b"".join(chunks).decode("utf-8", "replace"))
+    except SamlError:
+        raise
+    except Exception as err:
+        message = str(err).lower()
+        if "timed out" in message or "timeout" in message:
+            raise SamlError(code, f"{url} did not answer within {TIMEOUT_S} s") from err
+        raise SamlError(code, f"{url}: {err}") from err
+    finally:
+        for path in temps:
+            try:
+                os.unlink(path)
+            except OSError:
+                pass
+
+
+def _write_temp(pem: str) -> str:
+    handle = tempfile.NamedTemporaryFile("w", delete=False)
+    try:
+        handle.write(pem)
+        handle.close()
+    except Exception:
+        handle.close()
+        raise
+    return handle.name

saml2_sp/bindings.py

@@ -0,0 +1,129 @@
+# SPDX-FileCopyrightText: 2026 Iya CyberSecurity Solutions, LLC
+# SPDX-License-Identifier: MIT
+"""HTTP-Redirect and HTTP-POST encodings (SAML 2.0 Bindings, sections 3.4 and 3.5)."""
+
+from __future__ import annotations
+
+import base64
+import re
+import zlib
+from urllib.parse import quote, unquote
+
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import padding
+
+from saml2_sp.errors import SamlError
+from saml2_sp.signature import RSA_SHA256, SIGNATURE_ALGORITHMS
+from saml2_sp.xml import escape_xml
+
+MAX_INFLATED = 1024 * 1024
+_URI_SAFE = "-_.!~*'()"
+_B64 = re.compile(r"^[A-Za-z0-9+/]+={0,2}$")
+_BAD_PCT = re.compile(r"%(?![0-9A-Fa-f]{2})")
+
+
+def uri_escape(value: str) -> str:
+    return quote(value, safe=_URI_SAFE)
+
+
+def uri_unescape(value: str) -> str:
+    text = value.replace("+", "%20")
+    if _BAD_PCT.search(text):
+        raise SamlError("binding", "the query string is not validly percent-encoded")
+    return unquote(text)
+
+
+def deflate_raw(data: bytes) -> bytes:
+    compressor = zlib.compressobj(wbits=-15)
+    return compressor.compress(data) + compressor.flush()
+
+
+def inflate_raw(data: bytes, limit: int = MAX_INFLATED) -> bytes:
+    decompressor = zlib.decompressobj(wbits=-15)
+    out = decompressor.decompress(data, limit + 1)
+    if len(out) > limit or decompressor.unconsumed_tail:
+        raise SamlError("binding", "the message inflates past the limit")
+    return out + decompressor.flush()
+
+
+def redirect_query(param: str, xml: str, relay_state: str | None, key) -> str:
+    encoded = base64.b64encode(deflate_raw(xml.encode("utf-8"))).decode("ascii")
+    parts = [f"{param}={uri_escape(encoded)}"]
+    if relay_state is not None:
+        parts.append(f"RelayState={uri_escape(relay_state)}")
+    parts.append(f"SigAlg={uri_escape(RSA_SHA256)}")
+    signed = "&".join(parts)
+    signature = base64.b64encode(key.sign(signed.encode("utf-8"), padding.PKCS1v15(), hashes.SHA256())).decode("ascii")
+    return f"{signed}&Signature={uri_escape(signature)}"
+
+
+def read_redirect(raw_query: str, param: str, certs: list) -> dict:
+    raw: dict[str, str] = {}
+    query = raw_query[1:] if raw_query.startswith("?") else raw_query
+    for pair in query.split("&"):
+        if not pair:
+            continue
+        eq = pair.find("=")
+        name = uri_unescape(pair if eq < 0 else pair[:eq])
+        if name in raw:
+            raise SamlError("binding", f"the query string carries {name} twice")
+        raw[name] = "" if eq < 0 else pair[eq + 1:]
+    message = raw.get(param)
+    if message is None:
+        raise SamlError("binding", f"the query string carries no {param}")
+    try:
+        xml = inflate_raw(base64.b64decode(uri_unescape(message))).decode("utf-8")
+    except SamlError:
+        raise
+    except Exception as err:
+        raise SamlError("binding", f"{param} is not a DEFLATE-encoded message") from err
+    relay_state = uri_unescape(raw["RelayState"]) if "RelayState" in raw else None
+    if "Signature" not in raw:
+        return {"xml": xml, "relay_state": relay_state, "signed": False}
+    sig_alg = uri_unescape(raw.get("SigAlg", ""))
+    hash_name = SIGNATURE_ALGORITHMS.get(sig_alg)
+    if not hash_name:
+        raise SamlError("signature", f"the query is signed with {sig_alg or '(no SigAlg)'}, which is refused")
+    signed_parts = [f"{param}={message}"]
+    if "RelayState" in raw:
+        signed_parts.append(f"RelayState={raw['RelayState']}")
+    signed_parts.append(f"SigAlg={raw.get('SigAlg', '')}")
+    data = "&".join(signed_parts).encode("utf-8")
+    try:
+        sig_bytes = base64.b64decode(uri_unescape(raw["Signature"]))
+    except Exception as err:
+        raise SamlError("signature", "the query string signature does not verify against the identity provider's certificate") from err
+    hash_alg = {"sha256": hashes.SHA256(), "sha384": hashes.SHA384(), "sha512": hashes.SHA512()}[hash_name]
+    for cert in certs:
+        try:
+            cert.public_key().verify(sig_bytes, data, padding.PKCS1v15(), hash_alg)
+            return {"xml": xml, "relay_state": relay_state, "signed": True}
+        except Exception:
+            continue
+    raise SamlError("signature", "the query string signature does not verify against the identity provider's certificate")
+
+
+def read_post(value: str, param: str) -> str:
+    compact = re.sub(r"\s+", "", value)
+    if not compact or not _B64.match(compact):
+        raise SamlError("binding", f"{param} is not base64")
+    return base64.b64decode(compact).decode("utf-8")
+
+
+def post_form_html(action: str, fields: dict[str, str], nonce: str | None = None, title: str | None = None) -> str:
+    inputs = "\n      ".join(
+        f'<input type="hidden" name="{escape_xml(name)}" value="{escape_xml(value)}">' for name, value in fields.items()
+    )
+    script = f'\n    <script nonce="{escape_xml(nonce)}">document.forms[0].submit();</script>' if nonce else ""
+    return f"""<!doctype html>
+<html lang="en">
+  <head><meta charset="utf-8"><title>{escape_xml(title or "Signing in")}</title></head>
+  <body>
+    <form method="post" action="{escape_xml(action)}">
+      {inputs}
+      <noscript><p>Your browser is not running scripts. Press Continue to go on.</p></noscript>
+      <button type="submit">Continue</button>
+    </form>{script}
+  </body>
+</html>
+"""

saml2_sp/cli.py

@@ -0,0 +1,147 @@
+# SPDX-FileCopyrightText: 2026 Iya CyberSecurity Solutions, LLC
+# SPDX-License-Identifier: MIT
+"""saml2-sp's command line: a key pair, and this service provider's metadata."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+from saml2_sp.config import resolve_config
+from saml2_sp.service_provider import ServiceProvider
+from saml2_sp.x509util import create_self_signed_key_pair
+
+USAGE = """Usage:
+  saml2-sp generate-keys --config <saml.json> [--cn <name>] [--days <n>] [--bits <n>] [--force]
+  saml2-sp generate-keys --key <file> --cert <file> [--cn <name>] [--days <n>] [--bits <n>] [--force]
+      A new RSA key and a self-signed certificate, written where the configuration's privateKey and
+      certificate point (or to --key and --cert). Refuses to replace existing files without --force.
+      The common name defaults to the host of the configuration's entityId.
+
+  saml2-sp metadata --config <saml.json> [--out <file>] [--entity-id <url>] [--acs-url <url>]
+      This service provider's SAML metadata, from the configuration and its certificate. Written to
+      --out, or to standard output. --entity-id and --acs-url replace the file's values for this run."""
+
+
+def parse_args(argv: list[str]) -> tuple[str | None, dict]:
+    command = argv[0] if argv else None
+    rest = argv[1:]
+    args: dict = {}
+    index = 0
+    while index < len(rest):
+        item = rest[index]
+        if not item.startswith("--"):
+            raise SystemExit(f"unexpected argument {item}\n\n{USAGE}")
+        key = item[2:]
+        if key in ("force", "help"):
+            args[key] = True
+        else:
+            if index + 1 >= len(rest) or rest[index + 1].startswith("--"):
+                raise SystemExit(f"--{key} needs a value\n\n{USAGE}")
+            args[key] = rest[index + 1]
+            index += 1
+        index += 1
+    return command, args
+
+
+def _str(value) -> str | None:
+    return value if isinstance(value, str) else None
+
+
+def key_paths(args: dict) -> dict:
+    config_path = _str(args.get("config"))
+    key = _str(args.get("key"))
+    cert = _str(args.get("cert"))
+    common_name = _str(args.get("cn"))
+    if config_path:
+        with open(config_path, encoding="utf-8") as handle:
+            raw = json.load(handle)
+        base = os.path.dirname(os.path.abspath(config_path))
+
+        def at(path: str | None, what: str) -> str:
+            if not path or "-----BEGIN " in path:
+                raise SystemExit(f"{config_path}'s {what} must be a file path for generate-keys to write to")
+            value = path[5:] if path.startswith("file:") else path
+            if value.startswith("env:"):
+                raise SystemExit(f"{config_path}'s {what} must be a file path for generate-keys to write to")
+            return value if os.path.isabs(value) else os.path.abspath(os.path.join(base, value))
+
+        key = key or at(raw.get("privateKey"), "privateKey")
+        cert = cert or at(raw.get("certificate"), "certificate")
+        if not common_name and raw.get("entityId"):
+            from urllib.parse import urlparse
+            try:
+                common_name = urlparse(raw["entityId"]).hostname or raw["entityId"]
+            except Exception:
+                common_name = raw["entityId"]
+    if not key or not cert:
+        raise SystemExit(f"generate-keys needs --config, or --key and --cert\n\n{USAGE}")
+    return {"key": os.path.abspath(key), "cert": os.path.abspath(cert), "common_name": common_name or "saml2-sp service provider"}
+
+
+def _write(path: str, text: str, mode: int) -> None:
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, mode)
+    with os.fdopen(fd, "w", encoding="utf-8") as handle:
+        handle.write(text)
+
+
+def main(argv: list[str] | None = None) -> None:
+    command, args = parse_args(list(sys.argv[1:] if argv is None else argv))
+    if not command or args.get("help") or command == "help":
+        print(USAGE)
+        return
+    if command == "generate-keys":
+        paths = key_paths(args)
+        if not args.get("force") and (os.path.exists(paths["key"]) or os.path.exists(paths["cert"])):
+            which = paths["key"] if os.path.exists(paths["key"]) else paths["cert"]
+            raise SystemExit(f"{which} already exists; pass --force to replace the key pair.\n"
+                             "Replacing it means giving the identity provider the new metadata before the next sign-in.")
+        days = int(args["days"]) if _str(args.get("days")) else None
+        bits = int(args["bits"]) if _str(args.get("bits")) else None
+        if days is not None and days <= 0:
+            raise SystemExit("--days must be a positive whole number")
+        if bits is not None and bits not in (2048, 3072, 4096):
+            raise SystemExit("--bits must be 2048, 3072 or 4096")
+        pair = create_self_signed_key_pair(paths["common_name"], days or 1095, bits or 3072)
+        _write(paths["key"], pair.private_key_pem, 0o600)
+        _write(paths["cert"], pair.certificate_pem, 0o644)
+        print(f"Wrote the private key  {paths['key']} (mode 600)")
+        print(f"Wrote the certificate  {paths['cert']}")
+        print(f"  subject   CN={paths['common_name']}")
+        print(f"  valid to  {pair.valid_to}")
+        print(f"  sha256    {pair.fingerprint256}")
+        return
+    if command == "metadata":
+        config_path = _str(args.get("config"))
+        if not config_path:
+            raise SystemExit(f"metadata needs --config\n\n{USAGE}")
+        with open(config_path, encoding="utf-8") as handle:
+            raw = json.load(handle)
+        raw.pop("idpCa", None)
+        if _str(args.get("entity-id")):
+            raw["entityId"] = args["entity-id"]
+        if _str(args.get("acs-url")):
+            raw["acsUrl"] = args["acs-url"]
+        xml = ServiceProvider(resolve_config(raw, os.path.dirname(os.path.abspath(config_path))), None).metadata()
+        target = _str(args.get("out"))
+        if target:
+            os.makedirs(os.path.dirname(os.path.abspath(target)) or ".", exist_ok=True)
+            with open(target, "w", encoding="utf-8") as handle:
+                handle.write(xml)
+            print(f"Wrote the service provider metadata to {os.path.abspath(target)}")
+        else:
+            sys.stdout.write(xml)
+        return
+    raise SystemExit(f"unknown command {command}\n\n{USAGE}")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except SystemExit as err:
+        if err.code not in (None, 0):
+            sys.stderr.write(f"{err.code if isinstance(err.code, str) else err}\n")
+            raise SystemExit(1) from err
+        raise

saml2_sp/config.py

@@ -0,0 +1,156 @@
+# SPDX-FileCopyrightText: 2026 Iya CyberSecurity Solutions, LLC
+# SPDX-License-Identifier: MIT
+"""The configuration: seven settings, four of them with defaults. The rest is in the identity provider's metadata."""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+import re
+
+from cryptography.hazmat.primitives.asymmetric import rsa
+
+from saml2_sp.errors import SamlError
+from saml2_sp.x509util import certificate_pem, load_certificate, load_private_key, private_key_pem
+
+_REQUEST = ("redirect", "post")
+_RESPONSE = ("post", "redirect", "artifact")
+
+
+class ResolvedConfig:
+    """The configuration with its files read and its defaults filled in.
+
+    ``signals`` is present only when CAEP and RISC are off. Omitted means on: test ``signals not in config``.
+    """
+
+    def __init__(self, **fields: object) -> None:
+        self.__dict__.update(fields)
+
+    def __contains__(self, key: object) -> bool:
+        return key in self.__dict__
+
+
+def _expand(value: str) -> str:
+    seen = 0
+    while value.startswith("env:") or value.startswith("file:"):
+        seen += 1
+        if seen > 4:
+            raise SamlError("config", f"the placeholder {value} is nested too deeply")
+        if value.startswith("env:"):
+            name = value[4:]
+            if not name or name not in os.environ:
+                raise SamlError("config", f"environment variable {name or value} is not set")
+            value = os.environ[name]
+            continue
+        value = value[5:]
+    return value
+
+
+def _looks_like_pem(value: str) -> bool:
+    return "-----BEGIN " in value
+
+
+def material(value: str, base_dir: str, what: str) -> str:
+    value = _expand(value)
+    if _looks_like_pem(value):
+        return value
+    path = value if os.path.isabs(value) else os.path.abspath(os.path.join(base_dir, value))
+    try:
+        with open(path, encoding="utf-8") as handle:
+            return handle.read()
+    except OSError as err:
+        raise SamlError("config", f"{what} is neither a PEM nor a readable file ({path})") from err
+
+
+def _absolute_url(value: object, what: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise SamlError("config", f"{what} is required")
+    if not re.match(r"https?://", value):
+        raise SamlError("config", f"{what} must be an absolute http(s) URL, not {value}")
+    return value
+
+
+def _one_of(value: object, allowed: tuple[str, ...], default: str, what: str) -> str:
+    if value is None or value == "":
+        return default
+    if value not in allowed:
+        raise SamlError("config", f"{what} must be one of {', '.join(allowed)}, not {value}")
+    return str(value)
+
+
+def _number(value: object) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value)
+
+
+def resolve_config(config: dict, base_dir: str | None = None) -> ResolvedConfig:
+    if not isinstance(config, dict):
+        raise SamlError("config", "the configuration must be an object")
+    base = base_dir or os.getcwd()
+    entity_id = config.get("entityId")
+    if not isinstance(entity_id, str) or not entity_id.strip():
+        raise SamlError("config", "entityId is required")
+    acs_url = _absolute_url(config.get("acsUrl"), "acsUrl")
+    if not isinstance(config.get("privateKey"), str) or not isinstance(config.get("certificate"), str):
+        raise SamlError("config", "privateKey and certificate are required: every AuthnRequest is signed")
+    try:
+        key_pem = material(config["privateKey"], base, "privateKey")
+        cert_pem = material(config["certificate"], base, "certificate")
+        private_key = load_private_key(key_pem)
+        certificate = load_certificate(cert_pem)
+    except SamlError:
+        raise
+    except Exception as err:
+        raise SamlError("config", f"the private key or certificate cannot be read: {err}") from err
+    if not isinstance(private_key, rsa.RSAPrivateKey):
+        kind = "ec" if private_key.__class__.__name__.lower().startswith("ec") else private_key.__class__.__name__
+        raise SamlError("config", f"the private key is {kind}; an RSA key is required")
+    if private_key.public_key().public_numbers() != certificate.public_key().public_numbers():
+        raise SamlError("config", "the certificate is not for the private key")
+    idp_metadata = config.get("idpMetadata")
+    if not isinstance(idp_metadata, str) or not idp_metadata.strip():
+        raise SamlError("config", "idpMetadata is required")
+    idp_metadata = _expand(idp_metadata.strip())
+    if not re.match(r"https?://", idp_metadata) and not idp_metadata.startswith("<"):
+        idp_metadata = idp_metadata if os.path.isabs(idp_metadata) else os.path.abspath(os.path.join(base, idp_metadata))
+    skew = config["clockSkewSeconds"] if "clockSkewSeconds" in config and config["clockSkewSeconds"] is not None else 60
+    if not _number(skew) or skew < 0 or skew > 600:
+        raise SamlError("config", "clockSkewSeconds must be a number from 0 to 600")
+    if "signals" in config and not isinstance(config["signals"], bool):
+        raise SamlError("config", "signals must be true or false")
+    fields: dict[str, object] = {
+        "entity_id": entity_id,
+        "acs_url": acs_url,
+        "private_key": private_key,
+        "private_key_pem": private_key_pem(private_key),
+        "certificate": certificate,
+        "certificate_pem": certificate_pem(certificate),
+        "idp_metadata": idp_metadata,
+        "request_binding": _one_of(config.get("requestBinding"), _REQUEST, "redirect", "requestBinding"),
+        "response_binding": _one_of(config.get("responseBinding"), _RESPONSE, "post", "responseBinding"),
+        "clock_skew_ms": int(skew) * 1000,
+        "want_assertions_signed": True if config.get("wantAssertionsSigned") is None else config.get("wantAssertionsSigned"),
+        "want_assertions_encrypted": False if config.get("wantAssertionsEncrypted") is None else config.get("wantAssertionsEncrypted"),
+        "allow_unsolicited": False if config.get("allowUnsolicited") is None else config.get("allowUnsolicited"),
+    }
+    if config.get("signals") is False:
+        fields["signals"] = False
+    if config.get("idpCa"):
+        fields["idp_ca"] = material(config["idpCa"], base, "idpCa")
+    if config.get("idpEntityId"):
+        fields["idp_entity_id"] = config["idpEntityId"]
+    if config.get("nameIdFormat"):
+        fields["name_id_format"] = config["nameIdFormat"]
+    return ResolvedConfig(**fields)
+
+
+def read_config_file(path: str, overrides: dict | None = None) -> ResolvedConfig:
+    try:
+        with open(path, encoding="utf-8") as handle:
+            parsed = json.load(handle)
+    except Exception as err:
+        raise SamlError("config", f"{path} cannot be read as JSON: {err}") from err
+    defined = {k: v for k, v in (overrides or {}).items() if v is not None}
+    if not isinstance(parsed, dict):
+        raise SamlError("config", "the configuration must be an object")
+    return resolve_config({**parsed, **defined}, os.path.dirname(os.path.abspath(path)))