SAML, OIDC, Third-Party-Authentication

Hey there,

first of all, I want to say, that I know, that there are many existing issues or feature requests, but I still do not understand the problem.
Since more than two years, people are asking for a good solution to implement either an own 3rd-party authentication or SAML or OIDC (see FR: Two Factor Authentication). This year @mattronix asked for OIDC and Keycloak (see OIDC / Keycloak). There is a solution from @fgaillard, but as @MrGeneration said correctly

Please note that changing Zammad files is not update-safe and produces further needed work on every update.

So my question is now:
Will it ever be possible to use OIDC, SAML or an own 3rd-party authentication in Zammad?
@muhammadn started to work on OIDC 1,5 years ago (see Branch: Openid connect) but this branch is still there and still not merged.

Thanks for your reply.


Good news, a colorful bird left a hint that SAML is coming soon™.
If anyone is interested in this (currently) experimental feature for testing, please let us know.


Sounds great!
Please inform us, if there is something new.

I would love to test this new SAML experimental feature at my site where I have Zammad tied into AD via LDAP to sync in and authenticate users.

I want to be able to authenticate them via Keycloak (SAML) which I have integrated to Kerberos for auto-login of domain users already. Right now helpdesk users login directly to Zammad with their LDAP username and password from AD via the Zammad login form.

Most of our web apps support SAML or OIDC, so most logins are seamless single sign on in our site, except Zammad. But the LDAP integration has already eliminated the multiple password problem, so Zammad is making good progress in authentication options the last few years.

On a side note: Keycloak will support Webauthn in a future release, so for Zammad development to me it makes sense to focus on SAML and OIDC instead of MFA and Webauthn built into Zammad directly.

That way a simple SAML integration can open up the floodgates for users that need advanced MFA and SSO deployments. And for users without AD/Keycloak etc, they would at least have an option of deploying a SAML server like Keycloak (or okta /azure AD/ADFS/etc) to gain that functionality in a clearly supported way.

That would take care of lots of enterprise type customers that “need” 2fa for policy and compliance, then if the community is still desiring “built-in” MFA/2FA/Webauthn, then those features could come next.

And thanks for all the hard work on Zammad! We love it and are excited to see SAML support on the radar!


@thorsteneckel could you handle that please?

carl2187 wants to play hamster. :smiley:

I would love to test !!!

I’m experienced with SAML/OAUTH and LDAP!

Sign me up!!! :slight_smile: :partying_face:

Thorsten is currently out of order, we’ll need to give him some time to recover. He’ll be back soon™ :>

No Worries :slight_smile:

I hope all is well! :slight_smile:

I know this has been mentioned earlier but maybe its a good time to bring it up again.

It would be really awesome if once SAML is implemented that you could tell Zammad to immediately redirect to saml if the user is not authenticated.

Now to give some context here is a screenshot showing our SSO screen:

Alot of SAML based systems also handle social logins, Federations with other companies and user mappings meaning that mostly once you have SAML you don’t need or want internal authentication.

Here is two business reasons why:

  • Using external auth (SAML) means you are compliant with cooperate policy for on-boarding and off-boarding employees when you disable the account of an agent they can no longer login.

  • Two-Factor can be-enforced and no longer bypassed.

It would be amazing actually to be able to disable internal authentication completely or do not allow it for SAML accounts.

Thank you!


Hey folks I’m back and I’m happy that you’re interested in testing the SAML authentication. It would be great if you could just register a free hosted instance over at and let me know your host-/instancename here. I’ll then activate the feature for your instance :+1:

Awesome! Thanks for getting SAML support going!

My new SAML test instance is here:


Hey @carl2187! I activated SAML for your account now. Looking forward to your feedback.

Almost working with SAML via Keycloak 7.0:

got things configured how I think they need to be in Zammad, using a working Nextcloud <-> Keycloak SAML integration for reference of the various SAML config items.

In Zammad I enabled the auto-mapping feature for third party integration. I also manually added a Zammad user with the same username/email address that I have in Keycloak already to ensure the account is mapped correctly.

Then i was able to grab a valid-looking metadata.xml file from the zammad instance at:

Import that into Keycloak as a new client.

Since zammad doesn’t present any certs/keys on the SP side, we need to disable a setting in Keycloak: clients -> Zammad Helpdesk -> Client Signature Required : OFF

Now that SAML is configured and enabled on both sides, i click “OR SIGN IN USING” -> “SAML”
Keycloak login page appears, log in using my test user that exists already in keycloak, and a matching user exists in Zammad.
The login is “successful” from Keycloak’s point of view, but keycloak shows an error: “Failed to process request” instead of redirecting back to Zammad.

When this happens in the Keycloak logs i see:
2019-09-04 17:24:59,126 ERROR [org.keycloak.protocol.saml.SamlProtocol] (default task-61) failed:java.lang.IllegalArgumentException: Illegal character in path at index 6: Zammad Helpdesk at

so it appears the Client ID, being hard-coded to “Zammad Helpdesk” is causing an illegal character problem due to the space character. I’ve attempted to escape the value: Zammad%20Helpdesk but this results in “client not found” on Keycloak. Keycloak uses the ClientID to find the correct SAML configuration to use. Client ID in keycloak = EntityID in the SAML metadata XML files.

In the working nextcloud example, the clientID is actually a link to the metadata URL, here’s a comparison of the two XML files “EntityDescriptor” lines:

<md:EntityDescriptor ID="_6ce7f6f7-3280-4770-a9a2-a25bd7032c77" entityID="Zammad Helpdesk" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" validUntil="2019-09-06T16:37:42Z" cacheDuration="PT604800S" entityID="" ID="pfx09b5ac53-2700-1a53-8d84-de9cabf67c88"><ds:Signature xmlns:ds="">

All the keycloak examples i find for SAML avoid using spaces for the Client ID field. So perhaps we need to change the ClientID that Zammad is sending to something without spaces, or perhaps it should be changed to the meta data URL, similar to how nextcloud’s Saml app generates its XML metadata config file.

I’m looking into how to re-map the Keycloak ClientID to something else, but that seems to a primary key so to speak.

It looks like Zammad is using OmniAuth library for the SSO? if that’s the case i can find some other apps using omniauth and look into the XML metadata they provide to see what Zammad should send as the EntityID/Client ID that Keycloak will tolerate.

Thanks for getting this feature ready, it seems i’m one step away from having it functional.


1 Like

Looking into this a bit more, it looks like “issuer” is the rails/omniauth field that controls the value “Zammad Helpdesk”. Since Keycloak doesn’t like that value, I dove into what it “should” be:

The SAML 2.0 specification requires a fully qualified URI for the EntityID, not more than 1024 characters. The spec “Recommends” that the URI contains the SP’s domain name.

In nextclouds saml implementation they use the metadata xml URL in its entirety as the issuer / entityID, which obviously contains the SP’s domain name, so i suppose that would be considered a “best practice” implementation.

I suggest modifying the issuer / Entity ID sent by the Zammad SAML module to be “SAML 2.0” compliant by changing:

Zammad Helpdesk
https://<current Zammad domain>/auth/saml/metadata

Hope that helps get this feature polished up!


some references related to this:

Working SAML environment:
Nextcloud SAML entityID, and Keycloak Client ID: “

1 Like

@carl2187 I must say you are amazing! Thanks for the insights and references. I already applied your proposed changes to use the metadata-URL as the issues/entity id. Your test system is updated and ready for the next round of testing. Looking forward to read our feedback!

Awesome! thanks for fixing that up so quick @thorsteneckel!

I just updated the client id in keycloak and now I’m successfully logged in to Zammad via SAML!

I have a naming mismatch where it created a new user instead of mapping to the existing local Zammad user, but that’s an attribute mapping I havn’t setup in Keycloak yet, I’ll start figuring out what attributes and format they need to be sent in next to allow Zammad to auto-map existing users and come back with details here soon.

Some potential followup items for SAML integration:

  • Documentation on what attributes are used for the mapping (appears “email address” is the attribute to use, i’m pursuing this right now).
  • Create an option to disable all local Zammad authentication, and upon landing at the Zammad URL, immediately redirect to the SSO provider login page.
    • Nextcloud handles this nicely with a setting, where if you enable the option for “SSO Login only”, the default local login screen is always bypassed, but a special URL param allows local login in case the SSO server is down, or for keeping an admin account in the local user database. (ie: ) . This is what @mattronix was asking about a few days ago. Ideally it can be implemented as an optional setting. Some people will want the option of local sign-in and SSO, some will want only SSO.
  • Define the Single-Logout-Service URL so if a user clicks Logout from Zammad, it logs them out of the SAML provider as well.
    • I’m not sure exactly where this gets implemented, but the Nextcloud SAML does this by default, so mentioning it here since i’m using Nextcloud options as a reference SAML implementation.
  • We should ideally remove the option of using the IDP’s certificate thumbprint, and require the certificate itself. The rails docs suggest the fingerprint only for testing, because its based on SHA1, it has vulnerabilities that can only be avoided by using the certificate itself instead of the fingerprint.
    • Or we could show in the GUI that the “certificate” is recommended, and the fingerprint is optional, and also to show that only one of the two needs to be configured.

Thanks again for all the hard work! Seeing some incredible progress this year in Zammad!

I can’t get the existing local Zammad account to be used that has the same login, name, email address as the keycloak user. Instead when logging in via SAML a new user is created but with a number appended to the login name. Even though the login name from keycloak matches the “Login” field of the existing user.

Also I’ve deactivated the auto-created account with the number appended in Zammad->Users, but that user can still login via SAML. So my attempts to change the field mappings seem to be ignored now that Zammad has created this user.

Maybe we need to define the account linking/mapping somewhere in Zammad’s SAML implementation? In most of my production SAML integrations i send the email address or AD UPN as the username. email and UPN’s always look like: user@domain.tld. Then configure the user’s email address as the matcher on the SP (Zammad) side.

Or i may be missing something related to the automatic account linking paradigm, or perhaps that functionality isn’t implemented yet for the SAML provider?

Ah cant do it with the self hosted?

Would love to test saml :slight_smile:

I have nextcloud set up exactly the same way and love this as our customers really like the smooth flow between our systems! as they go to a url and bam logged in!