SAML

Nauthilus includes a native SAML IdP.

The current configuration root is:

• identity.saml

Endpoints

• GET /saml/metadata
• GET /saml/sso
• GET /saml/slo for the Redirect binding
• POST /saml/slo for the POST binding

Example

identity:
  saml:
    enabled: true
    entity_id: "https://idp.example.com/saml"
    cert_file: "/etc/nauthilus/saml/idp.pem"
    key_file: "/etc/nauthilus/saml/idp.key"
    signature_method: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
    default_expire_time: 1h
    name_id_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
    slo:
      enabled: true
      front_channel_enabled: true
      back_channel_enabled: false
      request_timeout: 3s
      max_participants: 64
      back_channel_max_retries: 1
    service_providers:
      - name: "Example SP"
        entity_id: "https://sp.example.com/metadata"
        acs_url: "https://sp.example.com/saml/acs"
        slo_url: "https://sp.example.com/saml/slo"
        slo_back_channel_url: "https://sp.example.com/saml/slo/backchannel"
        cert_file: "/etc/nauthilus/saml/sp.pem"
        authn_requests_signed: true
        logout_requests_signed: true
        logout_responses_signed: true
        require_mfa:
          - "totp"
        supported_mfa:
          - "totp"
          - "webauthn"
        required_mfa_level: 2
        allowed_attributes:
          - "mail"
          - "cn"
          - "uid"

Request Signature Policy

authn_requests_signed, logout_requests_signed, and logout_responses_signed control the inbound signature policy for a service provider. Their default is false.

When one of these fields is true, the service provider must also provide a valid signing certificate through cert or cert_file; Nauthilus validates that configuration at startup. An unsigned message for a required-signature flow is rejected. When a signature is present even though it is not required, Nauthilus still validates it and rejects an invalid signature.

Redirect-binding messages use the detached query signature. POST-binding SLO messages use an XML signature. Nauthilus rejects malformed signature parameter combinations and unsupported algorithms, including SHA-1 signature algorithms.

Single Logout Security

SAML SLO validates message type, signature, protocol fields, destination, time bounds, participant correlation, and request replay state before local session cleanup. identity.saml.slo controls front-channel and back-channel fanout.

The SLO endpoint applies its per-client rate limit and body-size limit before it parses the message. A RelayState longer than 80 bytes (the SAML binding limit), an encoded SAMLRequest or SAMLResponse larger than 512 KiB, and missing, duplicated, or mixed SLO parameters are rejected with HTTP 400 before any session state is touched.

Back-channel SLO delivery does not follow HTTP redirects. Configure every slo_back_channel_url as the final HTTPS endpoint. A 3xx response is a failed delivery and may fall back to front-channel fanout when that channel is enabled.

Keep request_timeout, max_participants, and back_channel_max_retries non-negative. Setting slo.enabled: false also makes the channel-specific flags ineffective.

Attribute Release

allowed_attributes is an allowlist for assertion attributes. An empty list permits normal releasable attributes, but Nauthilus always removes secret-bearing values such as passwords, tokens, private keys, TOTP secrets, and recovery-code fields. Adding a sensitive name to allowed_attributes does not override that protection.

Attribute names are classified defensively across case and common word separators. Keep authentication secrets in dedicated backend fields and never design a service provider to consume them from a SAML assertion.

MFA Assurance

Service providers can configure require_mfa, supported_mfa, required_mfa_level, and local mfa_policy.levels. Nauthilus verifies the current proof strength before issuing an assertion and separately enforces required factor enrollment. See MFA Assurance Policy.

Notes

• SLO is nested below identity.saml.slo
• old flat aliases such as identity.saml.slo_enabled are not part of the current surface
• browser MFA and frontend behavior are shared with OIDC through identity.frontend and identity.mfa