Zammad (SAML)
This guide explains how to connect the support center Zammad (all features open source) to VaultysHub using SAML 2.0.
Zammad's OpenID Connect expects a public client and a publicly recognized certificate. SAML works with all installations: VaultysHub signs the assertions, and Zammad verifies them with VaultysHub's certificate.
Prerequisites
- Zammad 6.x or 7.x, served over HTTPS (for example
https://support.example.com) - Administrator access to Zammad and VaultysHub
Configuration in VaultysHub
- Applications → Add: name Zammad, URL
https://support.example.com/ - Type SAML2. In the Service Provider tab:
- Entity ID:
https://support.example.com/auth/saml/metadata - ACS URL:
https://support.example.com/auth/saml/callback - Sign assertions: enabled
- Sign requests (signing the entire response): optional, Zammad only requires the signed assertion
- Entity ID:
- In the Identity Provider tab, note the SSO URL (
https://your-vaultyshub.link.vaultys.org/api/saml2/sso/[appid]) and the certificate. - Assign the application to the relevant users.
VaultysHub sends the NameID in the format emailAddress and the attributes email, firstName, and lastName, which Zammad recognizes.
Configuration in Zammad
Settings → Security → Third-party Authentication → Authentication via SAML, enable it, then:
| Field | Value |
|---|---|
| Display Name | VaultysHub |
| IDP SSO target URL | the SSO URL noted in VaultysHub |
| IDP Single Logout target URL | https://your-vaultyshub.link.vaultys.org/api/auth/signout (see the note below) |
| IDP certificate | the certificate noted in VaultysHub (block -----BEGIN CERTIFICATE-----) |
| Name Identifier Format | urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress |
| SSL verification | see the note below |
| Signing & Encrypting | None |
Check that Your callback URL, displayed at the bottom of the form, matches the ACS URL declared in VaultysHub. If it does not, correct the system address (Settings → System → Base: domain name and protocol https).
- Logout: VaultysHub does not offer SAML Single Logout. However, Zammad requires a URL: specify the logout page of VaultysHub.
- SSL verification: during registration, Zammad calls the SSO URL and follows its redirects. However, VaultysHub responds to an anonymous call with a relative redirect to its login page, which Zammad's HTTP client cannot follow. If registration fails on this verification, disable SSL verification. This only concerns this check: connections are not affected, as assertions are verified with the certificate.
Users created on first login are Clients. VaultysHub does not transmit groups: assign the roles Agent or Admin in Zammad.
Test
The login page displays a VaultysHub button: validate with your VaultysID, and you will be logged back into Zammad.
Troubleshooting
/auth/failure?message=invalid_ticket: Zammad rejected the SAML response. The Zammad server log (railsserver) contains the response received. Points to check: the Entity ID and ACS URL are identical on both sides, the certificate copied in full, the server times (assertions are valid for 5 minutes).- Parameter registration fails: see SSL verification above.