saml2-sp 0.1.0__tar.gz

saml2_sp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Iya CyberSecurity Solutions, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

saml2_sp-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: saml2-sp
+Version: 0.1.0
+Summary: Server-side SAML 2.0 service provider: signed AuthnRequests, HTTP-POST, HTTP-Redirect and HTTP-Artifact responses, encrypted assertions, and a Shared Signals poll receiver.
+Author: Iya CyberSecurity Solutions, LLC
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rcbj/saml2-sp-python
+Project-URL: Repository, https://github.com/rcbj/saml2-sp-python
+Project-URL: Issues, https://github.com/rcbj/saml2-sp-python/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=42
+Requires-Dist: lxml>=5
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# saml2-sp
+
+Server-side SAML 2.0 service provider for Python. It sends a signed `AuthnRequest` on HTTP-Redirect or HTTP-POST, accepts a `Response` on HTTP-POST, HTTP-Redirect, or HTTP-Artifact, verifies XML signatures, decrypts encrypted assertions, and can poll a Shared Signals transmitter for CAEP and RISC events.
+
+Version 0.1.0. License: MIT. `develop` and `main` are one commit. A pull request merged into `main` publishes the package to PyPI after the test workflow succeeds on that commit. A direct push does not. There is no API token: PyPI Trusted Publishing trades the workflow's GitHub OIDC token for a short-lived upload token, from the `pypi` environment, and PyPI holds the publisher for this repository and `publish.yml`. A version already on PyPI stays there; the next release is a new `version` in `pyproject.toml` (and `VERSION`).
+
+## Usage
+
+```python
+from saml2_sp import ServiceProvider
+
+sp = ServiceProvider.from_file("saml.json")
+request = sp.login(relay_state="/home")
+# request.binding is "redirect" (a URL) or "post" (request.html, an auto-posting form)
+who = sp.acs(method, url, body, request_id=request.id)
+```
+
+`saml.json` uses the same keys as the Node service provider: `entityId`, `acsUrl`, `privateKey`, `certificate`, `idpMetadata`, and the optional `requestBinding`, `responseBinding`, `idpCa`, `idpEntityId`, `nameIdFormat`, `clockSkewSeconds`, `wantAssertionsSigned`, `wantAssertionsEncrypted`, `allowUnsolicited`, and `signals`. A value may be PEM text, a file path, or an `env:` / `file:` placeholder. `signals` omitted or `true` leaves the Shared Signals receiver available. `false` turns it off and does not require transmitter metadata. Any other value is a configuration error: `signals must be true or false`. The resolved configuration omits `signals` when the receiver is on and includes `signals: false` when it is off. SAML does not send OAuth scopes, so the flag does not change the `AuthnRequest`.
+
+```sh
+docker compose build
+docker run --rm --user "$(id -u):$(id -g)" \
+  -v "$PWD/demo:/app/demo" \
+  saml2-sp-python-demo \
+  saml2-sp generate-keys --config demo/saml.json
+docker run --rm --user "$(id -u):$(id -g)" \
+  -v "$PWD/demo:/app/demo" \
+  saml2-sp-python-demo \
+  saml2-sp metadata --config demo/saml.json
+```
+
+## Shared Signals
+
+```python
+from saml2_sp import SignalsReceiver
+
+receiver = SignalsReceiver(transmitter="https://idp.example", on_end_sessions=end)
+receiver.track(local_id, login)
+receiver.start()
+```
+
+The receiver discovers the transmitter, keeps one poll stream (`urn:ietf:rfc:8936`), and verifies each Security Event Token against the published JWKS. By default a session ends on `session-revoked`, `account-disabled`, `account-purged`, `credential-compromise`, and `sessions-revoked`.
+
+## Tests
+
+```bash
+docker build --target test .
+```
+
+The suite runs in a container.
+
+The tests sign, encrypt, and decrypt with `cryptography` and exclusive canonicalization from `lxml`. They include a stub identity provider and a stub transmitter. Those stub tests do not start iya-sts.
+
+`python3 scripts/live_iya_sts.py` is the live half. It starts the latest main branch of iya-sts in memory mode with persistence and clustering off when `IYA_STS_URL` is unset, runs the install script in a scratch copy of this checkout (which registers the demo and writes the `idpCa` chain), then builds this demo image from it, checks the image carries the chain and no key, starts the demo with no CA mount, signs in, and requires a credential-change event and a session-revoked event on `GET /live-status`. The second event ends the local session. It uses two high ports (defaults 18546 and 18646, `LIVE_STS_PORT` and `LIVE_DEMO_PORT`) and never binds 3000, 8081 or 18481-18495. The nightly workflow runs the unit suite and this script once every 24 hours.
+
+## Layout
+
+- `src/saml2_sp/` the library (`ServiceProvider`, metadata, bindings, signatures, encryption, the replay cache, `ssf/`)
+- `tests/` pytest, including the stub identity provider
+- `demo/` the stdlib `http.server` application
+- `scripts/configure_iya_sts.py` registers that demo with iya-sts and writes the listener CA trust chain to the file `idpCa` names
+- `scripts/trust_chain.py` holds `save_trust_chain()` and refreshes that file
+- `scripts/live_iya_sts.py` signs the demo in to iya-sts and checks `GET /live-status`
+- `.github/workflows/nightly.yml` runs the unit suite and the live script once every 24 hours
+- `Dockerfile` and `docker-compose.yml` run the demo (`network_mode: host`, `PORT` defaults to 3000)
+
+## The iya-sts trust chain (`idpCa`)
+
+`idpCa` in `demo/saml.json` names the iya-sts TLS listener CA trust chain the library trusts for the IdP metadata URL, artifact resolution and the Shared Signals transmitter. The default is `file:generated/idp-ca.pem`, relative to `demo/`. The value may also be a plain path, `env:<NAME>`, or the PEM itself. The library loads every certificate in it into the default trust store (`ssl` `load_verify_locations(cadata=...)`), so the whole chain works and OpenSSL ends the path at the self-signed Root.
+
+`scripts/configure_iya_sts.py`, the install script, writes that file on every run (`scripts/trust_chain.py`, `save_trust_chain()`). It saves the whole chain iya-sts publishes at `GET /tls/server-certificate` (leaf, TLS Issuing CA, Intermediate, Root), or the chain from the TLS handshake when that path does not answer. It prints the path, the trust anchor's subject and its SHA-256 fingerprint. Compare the anchor with the Root CA on iya-sts's PKI page.
+
+The demo image build copies that file into the image at `/app/demo/generated/idp-ca.pem`, so the image trusts that iya-sts with no bind mount and no fetch. Run the install script before you build the image, and rebuild the image after running the install script against a different iya-sts. `.dockerignore` admits only that file from `demo/generated`: the SP key, certificate and metadata stay out of the image (compose still mounts `demo/generated` read-only for them). A build with no chain file yet (a fresh clone, CI) still succeeds; the image then has no `idpCa` file.
+
+The mechanism is `COPY demo demo` plus `.dockerignore`'s `demo/generated/*` and `!demo/generated/idp-ca.pem`. Do not replace it with a COPY that names the file or globs for it: when the file is absent, both BuildKit and the classic builder fail. A directory COPY of `demo/` (which always exists) succeeds in both. `python scripts/trust_chain.py --config demo/saml.json --idp <iya-sts URL>` refreshes the file by hand.
+
+## Demo
+
+```bash
+docker compose up --build
+```
+
+`PORT` defaults to 3000. `GET /healthz` returns `200` and the body `ok` even when the identity provider metadata is not on disk yet. The home page offers sign-in. `/login` answers a signed AuthnRequest (redirect, or a POST form). `/saml/acs` is the assertion consumer. `/saml/metadata` is this service provider's metadata. `GET /live-status` does not need an account id. It is JSON: `signedIn` (true when any local account session exists), `subject`, the receiver state, and the Shared Signals events this process has accepted (`type` and `jti` only). A loopback `entityId` and assertion consumer URL follow `PORT`. Any other host stays as written. `PUBLIC_URL` or `--public-url` replaces the origin and keeps the path; the default `http://localhost:3000` is not treated as an explicit public URL. The live script never binds port 3000 or 8081.
+
+`demo/saml.json` points at `file:` paths under `demo/generated/` and does not contain a key. Generate the key pair and, against a running iya-sts, register the application with:
+
+```bash
+python scripts/configure_iya_sts.py
+```
+
+The container's `PORT` wins over the shell's `PORT` when that script chooses the entityID and assertion consumer URL. The shipped demo leaves `signals` unset, so the receiver stays on when `ssf.transmitter` is set.

saml2_sp-0.1.0/README.md

@@ -0,0 +1,91 @@
+# saml2-sp
+
+Server-side SAML 2.0 service provider for Python. It sends a signed `AuthnRequest` on HTTP-Redirect or HTTP-POST, accepts a `Response` on HTTP-POST, HTTP-Redirect, or HTTP-Artifact, verifies XML signatures, decrypts encrypted assertions, and can poll a Shared Signals transmitter for CAEP and RISC events.
+
+Version 0.1.0. License: MIT. `develop` and `main` are one commit. A pull request merged into `main` publishes the package to PyPI after the test workflow succeeds on that commit. A direct push does not. There is no API token: PyPI Trusted Publishing trades the workflow's GitHub OIDC token for a short-lived upload token, from the `pypi` environment, and PyPI holds the publisher for this repository and `publish.yml`. A version already on PyPI stays there; the next release is a new `version` in `pyproject.toml` (and `VERSION`).
+
+## Usage
+
+```python
+from saml2_sp import ServiceProvider
+
+sp = ServiceProvider.from_file("saml.json")
+request = sp.login(relay_state="/home")
+# request.binding is "redirect" (a URL) or "post" (request.html, an auto-posting form)
+who = sp.acs(method, url, body, request_id=request.id)
+```
+
+`saml.json` uses the same keys as the Node service provider: `entityId`, `acsUrl`, `privateKey`, `certificate`, `idpMetadata`, and the optional `requestBinding`, `responseBinding`, `idpCa`, `idpEntityId`, `nameIdFormat`, `clockSkewSeconds`, `wantAssertionsSigned`, `wantAssertionsEncrypted`, `allowUnsolicited`, and `signals`. A value may be PEM text, a file path, or an `env:` / `file:` placeholder. `signals` omitted or `true` leaves the Shared Signals receiver available. `false` turns it off and does not require transmitter metadata. Any other value is a configuration error: `signals must be true or false`. The resolved configuration omits `signals` when the receiver is on and includes `signals: false` when it is off. SAML does not send OAuth scopes, so the flag does not change the `AuthnRequest`.
+
+```sh
+docker compose build
+docker run --rm --user "$(id -u):$(id -g)" \
+  -v "$PWD/demo:/app/demo" \
+  saml2-sp-python-demo \
+  saml2-sp generate-keys --config demo/saml.json
+docker run --rm --user "$(id -u):$(id -g)" \
+  -v "$PWD/demo:/app/demo" \
+  saml2-sp-python-demo \
+  saml2-sp metadata --config demo/saml.json
+```
+
+## Shared Signals
+
+```python
+from saml2_sp import SignalsReceiver
+
+receiver = SignalsReceiver(transmitter="https://idp.example", on_end_sessions=end)
+receiver.track(local_id, login)
+receiver.start()
+```
+
+The receiver discovers the transmitter, keeps one poll stream (`urn:ietf:rfc:8936`), and verifies each Security Event Token against the published JWKS. By default a session ends on `session-revoked`, `account-disabled`, `account-purged`, `credential-compromise`, and `sessions-revoked`.
+
+## Tests
+
+```bash
+docker build --target test .
+```
+
+The suite runs in a container.
+
+The tests sign, encrypt, and decrypt with `cryptography` and exclusive canonicalization from `lxml`. They include a stub identity provider and a stub transmitter. Those stub tests do not start iya-sts.
+
+`python3 scripts/live_iya_sts.py` is the live half. It starts the latest main branch of iya-sts in memory mode with persistence and clustering off when `IYA_STS_URL` is unset, runs the install script in a scratch copy of this checkout (which registers the demo and writes the `idpCa` chain), then builds this demo image from it, checks the image carries the chain and no key, starts the demo with no CA mount, signs in, and requires a credential-change event and a session-revoked event on `GET /live-status`. The second event ends the local session. It uses two high ports (defaults 18546 and 18646, `LIVE_STS_PORT` and `LIVE_DEMO_PORT`) and never binds 3000, 8081 or 18481-18495. The nightly workflow runs the unit suite and this script once every 24 hours.
+
+## Layout
+
+- `src/saml2_sp/` the library (`ServiceProvider`, metadata, bindings, signatures, encryption, the replay cache, `ssf/`)
+- `tests/` pytest, including the stub identity provider
+- `demo/` the stdlib `http.server` application
+- `scripts/configure_iya_sts.py` registers that demo with iya-sts and writes the listener CA trust chain to the file `idpCa` names
+- `scripts/trust_chain.py` holds `save_trust_chain()` and refreshes that file
+- `scripts/live_iya_sts.py` signs the demo in to iya-sts and checks `GET /live-status`
+- `.github/workflows/nightly.yml` runs the unit suite and the live script once every 24 hours
+- `Dockerfile` and `docker-compose.yml` run the demo (`network_mode: host`, `PORT` defaults to 3000)
+
+## The iya-sts trust chain (`idpCa`)
+
+`idpCa` in `demo/saml.json` names the iya-sts TLS listener CA trust chain the library trusts for the IdP metadata URL, artifact resolution and the Shared Signals transmitter. The default is `file:generated/idp-ca.pem`, relative to `demo/`. The value may also be a plain path, `env:<NAME>`, or the PEM itself. The library loads every certificate in it into the default trust store (`ssl` `load_verify_locations(cadata=...)`), so the whole chain works and OpenSSL ends the path at the self-signed Root.
+
+`scripts/configure_iya_sts.py`, the install script, writes that file on every run (`scripts/trust_chain.py`, `save_trust_chain()`). It saves the whole chain iya-sts publishes at `GET /tls/server-certificate` (leaf, TLS Issuing CA, Intermediate, Root), or the chain from the TLS handshake when that path does not answer. It prints the path, the trust anchor's subject and its SHA-256 fingerprint. Compare the anchor with the Root CA on iya-sts's PKI page.
+
+The demo image build copies that file into the image at `/app/demo/generated/idp-ca.pem`, so the image trusts that iya-sts with no bind mount and no fetch. Run the install script before you build the image, and rebuild the image after running the install script against a different iya-sts. `.dockerignore` admits only that file from `demo/generated`: the SP key, certificate and metadata stay out of the image (compose still mounts `demo/generated` read-only for them). A build with no chain file yet (a fresh clone, CI) still succeeds; the image then has no `idpCa` file.
+
+The mechanism is `COPY demo demo` plus `.dockerignore`'s `demo/generated/*` and `!demo/generated/idp-ca.pem`. Do not replace it with a COPY that names the file or globs for it: when the file is absent, both BuildKit and the classic builder fail. A directory COPY of `demo/` (which always exists) succeeds in both. `python scripts/trust_chain.py --config demo/saml.json --idp <iya-sts URL>` refreshes the file by hand.
+
+## Demo
+
+```bash
+docker compose up --build
+```
+
+`PORT` defaults to 3000. `GET /healthz` returns `200` and the body `ok` even when the identity provider metadata is not on disk yet. The home page offers sign-in. `/login` answers a signed AuthnRequest (redirect, or a POST form). `/saml/acs` is the assertion consumer. `/saml/metadata` is this service provider's metadata. `GET /live-status` does not need an account id. It is JSON: `signedIn` (true when any local account session exists), `subject`, the receiver state, and the Shared Signals events this process has accepted (`type` and `jti` only). A loopback `entityId` and assertion consumer URL follow `PORT`. Any other host stays as written. `PUBLIC_URL` or `--public-url` replaces the origin and keeps the path; the default `http://localhost:3000` is not treated as an explicit public URL. The live script never binds port 3000 or 8081.
+
+`demo/saml.json` points at `file:` paths under `demo/generated/` and does not contain a key. Generate the key pair and, against a running iya-sts, register the application with:
+
+```bash
+python scripts/configure_iya_sts.py
+```
+
+The container's `PORT` wins over the shell's `PORT` when that script chooses the entityID and assertion consumer URL. The shipped demo leaves `signals` unset, so the receiver stays on when `ssf.transmitter` is set.

saml2_sp-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "saml2-sp"
+version = "0.1.0"
+description = "Server-side SAML 2.0 service provider: signed AuthnRequests, HTTP-POST, HTTP-Redirect and HTTP-Artifact responses, encrypted assertions, and a Shared Signals poll receiver."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "Iya CyberSecurity Solutions, LLC" }]
+dependencies = [
+  "cryptography>=42",
+  "lxml>=5",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.scripts]
+saml2-sp = "saml2_sp.cli:main"
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src", "scripts", "tests"]
+testpaths = ["tests"]
+
+[project.urls]
+Homepage = "https://github.com/rcbj/saml2-sp-python"
+Repository = "https://github.com/rcbj/saml2-sp-python"
+Issues = "https://github.com/rcbj/saml2-sp-python/issues"

saml2_sp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

saml2_sp-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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>
+"""