Skip to content

SAML IdP Certificate File

Canvus Server validates signed SAML responses by comparing the certificate embedded in the response (under <Signature><KeyInfo><X509Data>) against the SHA-256 fingerprint set by idp-cert-fingerprint in the [saml] configuration section.

Some Identity Providers sign their responses but do not include <KeyInfo> in the signed XML. This is permitted by the xmldsig-core specification (KeyInfo is OPTIONAL) but means fingerprint-based validation cannot extract a certificate to verify. The login fails with an error similar to:

Signature does not contain KeyInfo

To support these IdPs, Canvus Server accepts an explicit path to the IdP's signing certificate via the idp-cert-file key. When set, the server uses the certificate at that path as the SAML trust anchor directly and skips in-response extraction. When idp-cert-file is unset, the existing fingerprint-based path runs unchanged.

Use idp-cert-file when any of the following is true:

  • Your IdP omits <KeyInfo> from signed SAML responses.
  • You want a stable, file-based trust anchor independent of whatever the IdP embeds in each response.
  • You are integrating with a load-balanced IdP cluster where the response-embedded certificate might rotate without your INI being updated.

If your IdP's responses include <KeyInfo> (most Microsoft Entra, Okta, and ADFS deployments do by default), continue using idp-cert-fingerprint — there is no benefit to switching.

Configuration

  1. Obtain the IdP's signing certificate as a PEM file.

    Most IdPs publish their certificate via federation metadata XML. Download it from your IdP's metadata URL, extract the <X509Certificate> content of the signing key descriptor, and wrap it in PEM armor:

    -----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIE...
...base64 cert body...
-----END CERTIFICATE-----

    Save it to a path readable by the Canvus Server process — for example /etc/MultiTaction/canvus/idp.pem.

  2. Edit mt-canvus-server.ini and add the new key to the [saml] section:

    [saml]
saml-enabled=true

; Existing settings — keep these
idp-target-url=https://your-idp.example.com/saml2
idp-entity-id=https://your-idp.example.com/
sp-entity-id=canvus

; NEW: point at the cert file saved in step 1.
idp-cert-file=/etc/MultiTaction/canvus/idp.pem

; You can leave idp-cert-fingerprint set as a fallback; the server
; prefers idp-cert-file when both are present.
; idp-cert-fingerprint=

  3. Restart Canvus Server so the new INI is read:

    • Bare-metal: systemctl restart mt-canvus-server
    • Container: bounce the canvus-combined container — for example, podman-compose down && podman-compose up -d from the directory containing your podman-compose.yml.

  4. Verify by attempting a SAML login. On success the server log will record:

    SAML IdpCertPEM configured: true

    Look for this in mt-canvus-server-YYYY-MM-DD.log. If the cert file is unreadable or empty, the server logs an error and falls back to the legacy fingerprint-based path; the line will read SAML IdpCertPEM configured: false.

Container Deployments

The idp-cert-file path is interpreted inside the container, so the file must be present on a path the container can read.

The default bind-mount layout exposes /canvus-data/config on the host as /etc/MultiTaction/canvus inside the container. Placing the certificate at /canvus-data/config/idp.pem on the host makes it visible inside the container as /etc/MultiTaction/canvus/idp.pem.

Set the INI key to the container-internal path:

[saml]
idp-cert-file=/etc/MultiTaction/canvus/idp.pem

No additional volume mounts are required if you use the default config bind-mount.

Behaviour summary

Condition Result
idp-cert-file set and readable Server uses the file's cert as the SAML trust anchor. idp-cert-fingerprint is ignored. IdPs that omit <KeyInfo> are supported.
idp-cert-file set but path unreadable Server logs an error, then falls back to the fingerprint path. SAML keeps working for IdPs that include <KeyInfo>.
idp-cert-file unset (default) Legacy behaviour. Server extracts the cert from <Signature><KeyInfo> in each response and verifies its SHA-256 against idp-cert-fingerprint.

Troubleshooting

The login still fails with "Signature does not contain KeyInfo".

Confirm the server log shows SAML IdpCertPEM configured: true on startup. If it shows false, the file path in the INI is unreadable from the server process. Check filesystem permissions and, for containerised deployments, confirm the path resolves inside the container (not just on the host).

The login fails with a signature-verification error.

The certificate in idp-cert-file does not match the key the IdP actually uses to sign responses. Re-download the IdP's federation metadata, locate the <KeyDescriptor use="signing"> block, and confirm the <X509Certificate> content matches what you saved.

The cert is in DER (binary) form, not PEM.

Convert it with:

openssl x509 -in idp.der -inform DER -out idp.pem -outform PEM

My IdP exposes multiple signing certs during a certificate rollover.

idp-cert-file accepts only a single certificate. During a rollover window, keep idp-cert-fingerprint set as well so the legacy path can fall through to validation against the response-embedded certificate if the file's cert no longer matches.