risaml 0.7.0

Maintained fork of saml-rs: pure-Rust SAML 2.0 Service Provider and Identity Provider support, with XML security from ribergshamra.
Documentation

risaml

crates.io docs.rs MIT licensed unsafe forbidden

Pure-Rust SAML 2.0 Service Provider and Identity Provider support. The protocol layer uses Rust XML parsing and does not require libxml2, xmlsec1, or an OpenSSL build chain. XML cryptography (XML-DSig, XML-Enc, C14N, detached message signatures) is delegated to ribergshamra, using the riptering crypto providers. The default crypto-ribergshamra feature selects RustCrypto and preserves the historical optional algorithm and PKCS#11 capabilities.

[dependencies]
risaml = "0.7"

# Crypto-free protocol layer only:
# risaml = { version = "0.7", default-features = false }

The Rust import path is risaml.

Upgrading

risaml is currently pre-1.0, so minor releases may contain breaking API or behavior changes. Before updating across minor versions, review the migration guides.

Why risaml?

risaml is aimed at applications that need SAML SP/IdP flows without a C XML security stack in their build and deployment environment.

Area risaml
Native dependencies No libxml2, xmlsec1, or OpenSSL build chain for the protocol layer
Roles Service Provider and Identity Provider
Bindings HTTP-POST, HTTP-Redirect, HTTP-POST-SimpleSign
Metadata Parse and generate SP/IdP metadata; verify signed metadata
Single Logout Create and parse LogoutRequest / LogoutResponse
Crypto XML-DSig, XML-Enc, detached signatures via ribergshamra
Hardening Request correlation, audience/destination/issuer checks, XSW guards, bounded parsing
Unsafe code #![forbid(unsafe_code)]

Compared with samael, the main tradeoff is deployment shape: samael is the established Rust SAML crate and commonly uses the native xmlsec stack, while risaml keeps the SAML protocol path Rust-only and delegates XML crypto to a Rust crate.

What you can do

Area Highlights
Web SSO Signed AuthnRequest / Response, HTTP-POST, HTTP-Redirect, POST-SimpleSign
Metadata Parse peer metadata, generate SP/IdP descriptors, verify signed aggregates
Single Logout Create and parse logout request/response flows across all three bindings
Validation Issuer, audience, destination/recipient, bearer confirmation, status, time windows, request correlation
Crypto XML-DSig sign/verify, XML-Enc encrypt/decrypt, detached message signatures, metadata key pinning
Extraction quick-xml DOM plus local-name field extraction

Unsupported SAML profiles

The high-level Saml API currently focuses on browser Web SSO, metadata-driven SP/IdP setup, XML signature/encryption through ribergshamra, and Single Logout. It does not yet implement Artifact resolution, SOAP/back-channel profiles, ECP/PAOS, SAML query protocols, NameID management, or metadata federation. If you need one of those profiles for a real interoperability target, please open an issue with the profile, binding, IdP/SP product, and a minimal expected flow so we can consider the implementation.

Quick Start

The primary API is the typed Saml facade. Build local SP/IdP configuration with SpConfig::builder and IdpConfig::builder, import peer metadata into typed descriptors, and keep the returned Pending<_> value with your browser session while the SAML round trip is in flight.

Runnable typed SSO

A signed SP -> IdP -> SP round trip is available as an executable example:

cargo run -p risaml --example sso

Source: examples/sso.rs.

The repository also includes a typed Single Logout walkthrough in examples/slo.rs and a low-level compatibility walkthrough in examples/raw_compat.rs.

The crate-root docs contain doctested fragments for the typed Saml facade, including Saml<Sp>::start_sso, Saml<Sp>::finish_sso, Saml<Idp>::receive_sso, and Saml<Sp>::finish_slo. Those rustdoc snippets are compiled by cargo test --doc; the README stays as an entry point and links to the complete examples above.

Service Provider SSO flow

  1. Build local SP state with SpConfig::builder and Saml::sp.
  2. Import peer IdP metadata into IdpDescriptor.
  3. Start SSO with sp.start_sso(...) and store started.pending with the browser session.
  4. In the ACS handler, pass the posted response fields and the matching pending value to sp.finish_sso(...).

See examples/sso.rs for a complete signed SP -> IdP -> SP round trip and the doctested crate-root SSO fragment for the compact API shape.

Typed SSO and SP-initiated SLO pending requests expire after five minutes by default. StartSso::pending_lifetime and StartSlo::pending_lifetime set a named local correlation lifetime; IdP-initiated SLO defaults to its generated wire expiration, which a local lifetime can shorten. Completion always checks the stored expiry against the caller's validation clock. RequireCache also atomically records a separate completed request ID until that expiry, rejecting a second completion even when a peer issues a different valid response. Persist the expiry when restoring snapshots. Replay-disabled compatibility still requires the application to atomically consume browser-bound pending state, and must not be used for assertions carrying OneTimeUse.

Identity Provider - receive and respond

The IdP side mirrors the SP flow: import peer SP metadata into SpDescriptor, parse an AuthnRequest with idp.receive_sso(...), then produce a typed browser response with idp.respond_sso(...). The complete path is exercised in examples/sso.rs, and the short rustdoc version is in the Identity Provider flows crate-root section.

IdpConfig::builder(...).issuance_lifetime(Duration) controls the shared issuance window for typed IdP output. One captured UTC IssueInstant derives both SSO Conditions@NotOnOrAfter and bearer SubjectConfirmationData@NotOnOrAfter. The default is exactly five minutes; that duration is risaml policy, not an OASIS requirement.

Single Logout

Typed Single Logout starts from session.logout_subject(), stores the PendingLogoutRequest, and finishes only with the matching LogoutResponse. Peer-initiated logout uses Received<LogoutRequest> rather than free-form request ID strings. See examples/slo.rs for the complete typed walkthrough and the doctested SLO fragment for the compact shape.

Saml<Idp>::start_slo models the local IdP as the SAML Session Authority and always emits a UTC LogoutRequest@NotOnOrAfter derived from the same IdpConfig::issuance_lifetime and captured IssueInstant. The exact values are persisted in PendingLogoutRequest. Custom typed IdP LogoutRequest templates must place NotOnOrAfter="{NotOnOrAfter}" as one unqualified root attribute so the library can validate and sign the final value. Typed Saml<Sp>::start_slo does not synthesize this role-specific attribute.

Inbound LogoutRequest messages require a UTC IssueInstant; risaml does not invent a maximum age for it. Generic inbound NotOnOrAfter remains optional under the protocol schema and is not rejected merely because a Session-Authority producer rule would require it on a narrower outbound flow. When present it must be UTC, and risaml rejects the request at its effective exclusive deadline. That fail-closed rejection is a library policy permitted by SAML, not an OASIS receiver MUST. ClockSkew controls the NotOnOrAfter tolerance, and replay storage uses the same skew-adjusted deadline instead of generic retention when the attribute is present.

Metadata

Metadata trust is explicit. The rustdoc Metadata trust section describes production-shaped signed metadata validation with pinned certificates. MetadataTrustPolicy::UnsignedForCompatibility is available for legacy interoperability, but it is a compatibility exception rather than a production default.

Imports retain validUntil from the entity and selected SP/IdP role. Each typed and raw browser-flow use checks that deadline; signature trust never extends metadata validity. Metadata::validate_at supports manual consumers and refresh managers. Aggregate EntitiesDescriptor imports remain unsupported and fail closed so parent expiration cannot be discarded. Refresh scheduling and cacheDuration are application concerns, distinct from hard validity. Signing-only and encryption-only metadata keys keep their declared purpose, including a sole key; keys without use serve both purposes. Role imports never borrow another role's keys or endpoints.

Unknown assertion Conditions fail closed. OneTimeUse requires a replay cache and immediate use of the assertion; retained assertion data must not be reused for later decisions. ProxyRestriction is understood as a restriction on subsequent assertion issuance, not an extra login audience restriction. SsoSession::proxy_restriction_xml exposes it for applications implementing proxy issuance; the built-in SSO consumer does not reissue session assertions.

The compact rustdoc flow snippets use ReplayPolicy::DisabledForCompatibility only to keep examples dependency-free. Production inbound validation should use ReplayPolicy::RequireCache with a caller-owned replay cache and the retention guidance in SamlValidationContext.

Advanced/raw compatibility

The low-level compatibility API remains available under risaml::raw for callers that need direct access to ServiceProvider, IdentityProvider, HttpRequest, BindingContext, or protocol helper functions. New browser SSO/SLO integrations should start with Saml, typed descriptors, and the builder-backed config types shown above. Public raw create_logout_request* helpers retain their compatibility output: they do not synthesize NotOnOrAfter, and the public LOGOUT_REQUEST_TEMPLATE remains unchanged. Use visible docs.rs modules, crate-root re-exports, and risaml::raw before reaching for hidden lower-level module paths.

Features

[features]
default = ["crypto-ribergshamra"]
crypto-ribergshamra = [
    "crypto-rustcrypto",
    "crypto-legacy-algorithms",
    "crypto-post-quantum",
    "crypto-pkcs11",
]
crypto-bergshamra = ["crypto-ribergshamra"]  # compatibility alias
crypto-rustcrypto = ["dep:ribergshamra", "ribergshamra/rustcrypto"]
crypto-aws-lc = ["dep:ribergshamra", "ribergshamra/aws-lc"]
crypto-fips = ["dep:ribergshamra", "ribergshamra/fips"]
crypto-legacy-algorithms = ["ribergshamra?/legacy-algorithms"]
crypto-legacy-rsa-decryption = ["ribergshamra?/legacy-rsa-decryption"]
crypto-post-quantum = ["ribergshamra?/post-quantum"]
crypto-pkcs11 = ["ribergshamra?/pkcs11"]

crypto-bergshamra is a compatibility alias for crypto-ribergshamra, kept so that feature selections written for the bergshamra-based releases keep working. New configurations should name crypto-ribergshamra or select a provider directly.

With default-features = false, the protocol layer still builds messages, parses metadata, and runs extraction. Operations that need signing, verification, or encryption return SamlError::Unsupported.

risaml requires Rust 1.88. Select at most one of crypto-rustcrypto, crypto-aws-lc, and crypto-fips; provider combinations are rejected at compile time. Disable default features before selecting AWS-LC or FIPS.

crypto-legacy-algorithms, crypto-post-quantum, and crypto-pkcs11 forward those ribergshamra capabilities without selecting a provider. The default crypto-ribergshamra feature enables them with RustCrypto to preserve existing behavior; direct provider selection starts with only that provider's baseline. Without crypto-legacy-algorithms, and always with AWS-LC or FIPS, riptering rejects RSA keys shorter than 2048 bits.

crypto-legacy-rsa-decryption is a separate, off-by-default compatibility exception for the unresolved RustCrypto RSA private-decryption timing advisory. Neither crypto-legacy-algorithms nor the default feature enables it. To retain RustCrypto RSA-OAEP assertion decryption, explicitly select this Cargo feature and the existing XmlEncryptionPolicy software-RSA risk option (or its raw equivalent). The runtime option alone now propagates SamlError::Crypto from the disabled backend; default runtime policy still returns Unsupported. The exception does not fix RUSTSEC-2023-0071. RSA encryption, signing and verification remain available, and the accepted compatibility wire format is unchanged. Non-FIPS AWS-LC decryption is unaffected; FIPS approval restrictions remain in force.

The dependency minimum is ribergshamra 0.11.0, which uses riptering 0.7 and exposes legacy-rsa-decryption. Refresh consumer lockfiles when upgrading; applications that depend directly on these crates must use matching release lines. CI validates the published registry graph with --locked.

ribergshamra supports AWS-LC and FIPS on Linux x86_64/aarch64. The risaml provider matrix currently validates Linux x86_64; Linux aarch64 is an upstream capability that this repository does not exercise in CI. risaml initializes ribergshamra before its first crypto operation. Applications can fail early and inspect the result during startup:

use risaml::{initialize_crypto_provider, CryptoFipsStatus};

let provider = initialize_crypto_provider()?;
assert_ne!(provider.fips_status(), CryptoFipsStatus::Uninitialized);
# Ok::<(), risaml::SamlError>(())

Initialization, attestation, unsupported-algorithm, and key-import failures are fail-closed and map to SamlError::Crypto. crypto-fips means that the selected AWS-LC provider actively attested FIPS mode; it does not claim that a consuming binary or deployment is FIPS certified. FIPS policy rejects algorithms outside its approved set, including the currently exposed SHA-1-based RSA_OAEP_MGF1P XML-Enc key transport. ribergshamra's AWS-LC providers reject signing with RSA_SHA1. The FIPS provider also rejects verifying RSA_SHA1; non-FIPS AWS-LC still verifies inbound RSA-SHA1 Redirect and XML-DSig signatures. AWS-LC has a narrower capability set than RustCrypto; consult ribergshamra's provider-capability documentation before enabling custom algorithm URIs.

With crypto-ribergshamra enabled:

  • XML signatures can be verified against metadata-declared keys.
  • Signed-reference placement checks help mitigate XML Signature Wrapping (XSW).
  • XML-Enc support is available. On the default RustCrypto provider, software RSA key-transport decryption is gated off by default and requires an explicit crypto-legacy-rsa-decryption feature and runtime opt-in through XmlEncryptionPolicy. AWS-LC decrypts RSA-OAEP with the default options.

Security

Report security problems privately as described in SECURITY.md; do not open a public issue.

risaml is pre-1.0 and has not had an external security audit. Review the crate, configuration, and peer metadata trust model before production use.

Security-sensitive defaults and checks include:

  • #![forbid(unsafe_code)] on the crate root.
  • DOCTYPE / XXE rejection and bounded XML parsing before authentication.
  • XML escaping for generated templates, metadata endpoint locations, and SAML attribute values.
  • Response validation for issuer, SAML status, assertion time window, audience, destination/recipient, bearer subject confirmation, and InResponseTo.
  • Logout validation for issuer and request/response correlation.
  • Signed metadata verification with root coverage requirements.
  • AuthnRequest root-signature coverage when signed requests are required.
  • Detached Redirect/SimpleSign signatures bound to the fields consumed by the flow parser.
  • HTTP-Redirect raw DEFLATE output limits.
  • XML-Enc software RSA key-transport decryption disabled by default on RustCrypto because that backend, reached through ribergshamra / riptering, is affected by RUSTSEC-2023-0071. AWS-LC and FIPS do not apply this gate. The separate compile-time exception and runtime risk policy are both required for RustCrypto decryption.

Schema validation is optional defense in depth via context::set_schema_validator.

Development

Report bugs and feature requests in GitHub Issues.

cargo fmt --all --check
cargo clippy -p risaml --all-targets -- -D warnings
cargo nextest run -p risaml
cargo test -p risaml --doc
RUSTDOCFLAGS="-D warnings -D missing_docs" cargo doc -p risaml --lib --no-deps
cargo test -p risaml --doc --no-default-features
cargo check -p risaml --no-default-features
cargo nextest run -p risaml --no-default-features --features crypto-rustcrypto
# AWS-LC/FIPS checks run on supported Linux runners; see .github/workflows/ci.yml.

Compatibility and migration

Compatibility notes for applications moving from saml-rs 0.5.0.

  • Names. The crate is risaml (use risaml::..., cargo run -p risaml). The compatibility re-export crates (opensaml, samlify, rustsaml, samlet) are not included. Public modules and all SAML protocol constants (URNs, namespaces, bindings, NameID formats, status codes) are unchanged.
  • XML security. ribergshamra 0.11 replaces bergshamra 0.8 and riptering 0.7 replaces kryptering 0.5, so Key, KeysManager and the other re-exported XML security types come from ribergshamra. The default feature is now called crypto-ribergshamra; crypto-bergshamra remains as an alias for it, and the provider and capability features keep their names.
  • Software RSA key size. The default RustCrypto software configuration retains historical RSA key sizes with crypto-legacy-algorithms. Without that feature, RustCrypto rejects RSA keys shorter than 2048 bits, as AWS-LC and FIPS already did. PKCS#11 has a separate key-admission policy described in the migration guide.
  • Project. Package metadata points at https://github.com/Rhein-Industries/risaml; CI runs on GitHub-hosted runners and publishing is manual (the upstream release-plz automation is not used).

The full list is in the changelog.

Migrating from saml-rs

[dependencies]
risaml = "0.7"
# or keep the `saml_rs::` paths in your code:
# saml-rs = { package = "risaml", version = "0.7" }

With the plain risaml dependency, replace saml_rs:: with risaml::. Replace crypto-bergshamra with crypto-ribergshamra in feature lists (the old name keeps working). Code that names bergshamra types next to risaml's API, for example the Key returned by load_private_key, switches to ribergshamra::. The 0.5 to 0.6 guide covers the initial crate rename; then apply the 0.6 to 0.7 guide for security policy changes. Review the XML processing limits when upgrading: the delegated XML backend applies fixed resource budgets and corrected canonicalization and CRL policies.

License

MIT.[^history]

[^history]: Started from saml-rs by Sebastian Sala, version 0.5.0 (tag v0.5.0, commit 9302371).