Connect your SAML identity provider as a single sign-on (SSO) method.
🤷 What is SAML?
SAML is an open standard for SSO authentication (among other things). Sign-ins are shared across multiple service providers and managed by a central identity provider (IdP).
This guide assumes you are already using SAML within your organization (i.e., that your IdP is fully set up).
Step 1: Configure Your IdP¶
Add Zammad as a client/app¶
Import Zammad into your IdP using the XML configuration
🙋 What if my IdP doesn’t support XML import?
You will have to configure Zammad as a new client/app manually using the above XML metadata file for reference. For instance, when you see this tag:
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="http://your.zammad.domain/auth/saml/callback" index="0" isDefault="true"/>
Set the Assertion Consumer Service Binding URL
(sometimes also listed as Valid Redirect URIs)
Set up user attribute mapping¶
Zammad requests the following user attributes (or “properties”) from the IdP:
- Email address (
- Full name (
- Given name (
- Family name (
You may need to set up “mappers” (or “mappings”) to tell your IdP how user attributes in SAML correspond to those in Zammad. For a more detailed breakdown, refer to the XML metadata file referenced in the previous section.
To add Zammad as a client, save the XML configuration to disk (
https://your.zammad.domain/auth/saml/metadata) and use Clients > Create > Import in the Keycloak admin panel.
To help Zammad match its own user accounts to Keycloak users, create a user attribute (or “property”) mapper:
Clients > https://your.zammad.domain/auth/saml/metadata > Mappers > Create Name EmailAddress-Email Mapper Type User Property Property emailAddress SAML Attribute Name SAML Attribute NameFormat basic
In the example above, we’re telling Zammad that whenever it receives a SAML login request, it should take the
emailAddressproperty from Keycloak, look for a Zammad user with the same
If your Keycloak users’ email addresses are stored on another property (e.g.,
username), adjust accordingly.
Step 2: Configure Zammad¶
Enable SAML and enter your IdP’s details in the Admin Panel under Settings > Security > Third Party Applications > Authentication via SAML:
🔏 For the IdP certificate / certificate fingerprint:
Provide only one or the other—do not provide both! (Between the two, we recommend the signing certificate itself: fingerprints use SHA-1, which has been broken for a while now.)
Keycloak users: Find your certificate in the Keycloak admin panel under Realm Settings > Keys > RSA > Certificate.
See automatic account linking for details on how to link existing Zammad accounts to IdP accounts.
- Automatic account linking doesn’t work
- Have you double-checked your IdP’s user attribute mapping configuration?