Breached password detection is a critical component of secure applications.    Read the white paper

FusionAuth logo
FusionAuth logo
  • Features
    FusionAuth Reactor

    FusionAuth Reactor is a powerful suite of features developed to extend FusionAuth's core functionality.

    • Flexible Architecture   Flexible Architecture
    • Auth the Way You Want It   Auth the Way You Want It
    • Security & Compliance   Security & Compliance
    • Ultimate Password Control   Ultimate Password Control
    • Customizable User Experience   Customizable User Experience
    • Advanced Registration Forms   Advanced Registration Forms
    • Built for Devs   Built for Devs
    • User Management & Reporting   User Management & Reporting
    • Scalability   Scalability
    • Single Sign-on   Single Sign-on
    • Breached Password Detection   Breached Password Detection
    • Connectors   Connectors
    • FusionAuth Reactor   FusionAuth Reactor
  • Pricing
    Cloud Pricing

    Let us host, monitor, manage, and maintain your deployments in your own private cloud.

    SEE PRICING cloud pricing   See FusionAuth Cloud Pricing
    Editions Pricing

    A powerful set of features with available support that extends FusionAuth's core functionality.

    SEE PRICING edition pricing   See FusionAuth Edition Pricing
    Editions + Cloud

    FusionAuth will handle everything so you can get back to building something awesome.

    GET STARTED Get started
  • Docs
  • Downloads
  • Resources
    FusionAuth Resources
    • Upgrade from SaaS
    • Upgrade from Open Source
    • Upgrade from Home Grown
    • Blog   Blog
    • Forum   Forum
    • Community & Support   Community & Support
    • Customer & Partners   Customers & Partners
    • Video & Podcasts   Videos & Podcasts
    • Getting Started   Getting Started
  • Expert Advice
    Expert Advice for Developers

    Learn everything you need to know about authentication, authorization, identity, and access management from our team of industry experts.

    • Authentication   Authentication
    • CIAM   CIAM
    • Identity Basics   Identity Basics
    • OAuth   OAuth
    • Security   Security
    • Tokens   Tokens
    • Dev Tools   Dev Tools
  • Account
Navigate to...
  • Welcome
  • Getting Started
  • 5-Minute Setup Guide
  • Reactor
  • Core Concepts
    • Overview
    • Users
    • Roles
    • Groups
    • Registrations
    • Applications
    • Tenants
    • Identity Providers
    • Authentication and Authorization
    • Integration Points
    • Roadmap
  • Installation Guide
    • Overview
    • System Requirements
    • Server Layout
    • Cluster
    • Docker
    • Fast Path
    • Kickstart™
    • Homebrew
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Securing
    • Upgrading
  • APIs
    • Overview
    • Authentication
    • Errors
    • Actioning Users
    • Applications
    • Audit Logs
    • Connectors
      • Overview
      • Generic
      • LDAP
    • Consent
    • Emails
    • Event Logs
    • Families
    • Forms
    • Form Fields
    • Groups
    • Identity Providers
      • Overview
      • Apple
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Twitter
      • OpenID Connect
      • SAML v2
      • External JWT
    • Integrations
    • JWT
    • Keys
    • Lambdas
    • Login
    • Passwordless
    • Registrations
    • Reports
    • System
    • Tenants
    • Themes
    • Two Factor
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • Webhooks
  • Client Libraries
    • Overview
    • Dart
    • Go
    • Java
    • JavaScript
    • .NET Core
    • Node
    • PHP
    • Python
    • Ruby
    • Typescript
  • Themes
    • Overview
    • Localization
    • Examples
  • Email & Templates
    • Overview
    • Configure Email
    • Email Templates
  • Events & Webhooks
    • Overview
    • Events
    • Writing a Webhook
    • Securing Webhooks
  • Example Apps
    • Overview
    • Go
    • Java
    • JavaScript
    • .NET Core
    • PHP
    • Python
    • Ruby
  • Lambdas
    • Overview
    • Apple Reconcile
    • External JWT Reconcile
    • Facebook Reconcile
    • Google Reconcile
    • HYPR Reconcile
    • JWT Populate
    • LDAP Connector Reconcile
    • LinkedIn Reconcile
    • OpenID Connect Reconcile
    • SAML v2 Populate
    • SAML v2 Reconcile
    • Twitter Reconcile
  • Identity Providers
    • Overview
    • Apple
    • Facebook
    • Google
    • HYPR
    • LinkedIn
    • Twitter
    • OpenID Connect
      • Overview
      • Azure AD
      • Github
      • Discord
    • SAML v2
      • Overview
      • ADFS
    • External JWT
      • Overview
      • Example
  • Connectors
    • Overview
    • Generic Connector
    • LDAP Connector
    • FusionAuth Connector
  • Integrations
    • Overview
    • CleanSpeak
    • Kafka
    • Twilio
  • OpenID Connect & OAuth 2.0
    • Overview
    • Endpoints
    • Tokens
  • SAML v2 IdP
    • Overview
    • Google
    • Zendesk
  • Plugins
    • Writing a Plugin
    • Password Encryptors
  • Guides
    • Overview
    • Advanced Registration Forms
    • Breached Password Detection
    • Migration
    • Passwordless
    • Securing Your APIs
    • Silent Mode
    • Single Sign-on
  • Tutorials
    • Overview
    • Setup Wizard & First Login
    • Register/Login a User
    • Migrate Users
    • JSON Web Tokens
    • Authentication Tokens
    • Start and Stop FusionAuth
    • Switch Search Engines
    • User Account Lockout
    • Two Factor
  • Reference
    • CORS
    • Configuration
    • Data Types
    • Known Limitations
    • Password Encryptors
  • Release Notes
  • Troubleshooting

SAML v2 & Zendesk

Overview

Zendesk allows customers to sign into their Zendesk accounts using a SAML identity provider. This document covers the configuration necessary to get Zendesk working with FusionAuth as the identity provider using SAML v2.

This document covers configuration for FusionAuth’s SAML v2 identity provider, where FusionAuth is the system of record for users, and other applications federate with FusionAuth.

If, on the other hand, you are looking for instructions on setting up FusionAuth as a SAML v2 service provider (i.e. you want to allow users to log into either FusionAuth’s UI or your applications via a third party SAML v2 identity provider), consult the SAML v2 Identity Provider documentation.

A bit confusing, we know. But in FusionAuth, Identity Providers are third party sources of record for user data.

We’ll also set up roles in FusionAuth to automatically grant agent dashboard access in Zendesk. Here’s a video showing the integration process:

Prerequisites

This document assumes you have a running instance of FusionAuth and a working Zendesk application. You will also need admin accounts for both to configure them correctly.

Additionally, you’ll need to know your Zendesk URL. It may be something like: https://fusionauth-example.zendesk.com where fusionauth-example is your registered domain. We’ll use that value for this document, but please replace it with your Zendesk URL.

Finally, you’ll need a FusionAuth user that you will use to sign into Zendesk. You can use an existing user or create a new user for this purpose.

Configure FusionAuth

First, we want to create a new application named, Zendesk, in FusionAuth. Navigate to Applications and create an application with the following two roles:

  • agent

  • admin

When you are done, your screen should look like this just before saving. The role descriptions are optional but may be helpful to provide. Once you have confirmed the values, save the new application.

Creating FusionAuth application with Zendesk roles.

Next, we’ll create a lambda to take FusionAuth role information and populate the SAML assertion that Zendesk will receive. Navigate to Settings → Lambdas and click the add button.

  • Name the lambda Populate Zendesk roles.

  • Set the type to SAML v2 populate.

  • Add the following function body:

    function populate(samlResponse, user, registration) {
      if (registration && registration.roles) {
        samlResponse.assertion.attributes.role = registration.roles;
      }
    }

 
When this lambda function is executed, it will set the users' roles in the SAML assertion to the roles found in the registration. These roles are the ones assigned by FusionAuth for the Zendesk FusionAuth application. If no roles are assigned, Zendesk treats the user as an end user, not an agent or an admin.

Creating a lambda to populate roles.

Click save, and then return to the Zendesk FusionAuth application by navigating to Applications

  • Edit the application.

  • Go to the SAML tab.

  • Enable SAML.

To configure SAML, use the following settings, replacing fusionauth-example with your actual Zendesk domain.

  • Issuer : https://fusionauth-example.zendesk.com, note that there is no trailing slash.

  • Audience : Leave this blank.

  • Callback URL (ACS) : https://fusionauth-example.zendesk.com/access/saml/

  • Logout URL : A location that users should be sent to after they sign out of Zendesk.

  • Signing Key : Either select an existing key or let FusionAuth create a new one.

  • XML signature canonicalization method : Exclusive with comments

  • Response populate lambda : Choose the previously created lambda named Populate Zendesk roles.

Application SAML configuration.

Click save. Now view the application configuration and scroll down to the SAML v2 Integration details section. Copy the following information:

  • Login URL

  • Logout URL

The SAML Integration Details.

Next, navigate to Users to edit the user you have previously set up or create a new one. Create a registration to add that user to the Zendesk application and give them the appropriate role. If you don’t give them an admin or agent role, they’ll default to a user Zendesk role.

Finally, go to Settings → Key Master and view the Signing Key you created or chose. Copy the Fingerprint (SHA-256) value. This will be something like FF:74:12:A5:40:67:E9:90:24:FC:95:07:FC:B7:E6:36:9B:26:75:6B:24:9D:3E:49:0A:43:4D:BC:03:00:DD:AA.

The required certificate fingerprint.

Configure Zendesk

The general Zendesk SSO instructions are worth reading.

To configure Zendesk to use FusionAuth to manage your users, head to your application’s security center, then to the Single sign-on section. This is a direct URL to that section: https://fusionauth-example.zendesk.com/admin/security/sso

Enable SAML, then configure it.

  • The SAML SSO URL is the Login URL previously copied.

  • The Remote Logout URL is the Logout URL previously copied.

  • The Certificate fingerprint is the Fingerprint (SHA-256) value previously copied.

The Zendesk SSO configuration screen.

Save the SAML configuration. The next step is to allow users to log in using the SAML integration. You can choose to let end users, staff, or both use single sign-on.

Proceed to the Staff members section. Check External authentication and select Single sign-on. You should see that SAML is enabled. Save the configuration.

Navigate to the End users section. Check External authentication. You should see that SAML is enabled. Save the configuration.

You can also uncheck Zendesk Authentication in these two sections to ensure that users are managed only in FusionAuth.

Log in

Open a different browser and go to your Zendesk URL: https://fusionauth-example.zendesk.com/.

Enter the user credentials previously configured in FusionAuth.

You should arrive at a screen appropriate to the role of the user (Help Center for end users, the Zendesk dashboard for others).

Troubleshooting

Admin users will be able to access their dashboard at https://fusionauth-example.zendesk.com/access/normal should FusionAuth be unavailable for any reason. There’s more information at the Zendesk help center.

Ensure that the Issuer setting has no trailing slash and exactly matches your Zendesk URL.

Make sure you are connecting over TLS. All Zendesk-bound traffic must be secure.

When troubleshooting, turn on SAML debugging at the application level and lambda debugging for the populate lambda. Use console.log statements in the lambda if needed.

New users are assigned the Zendesk user role if they have no FusionAuth role. By default, such users are sent to the Zendesk Help Center after sign in, which is not enabled by default in new Zendesk accounts. If this is the case, you’ll get an error message.

If you have reached the license limit for your Zendesk account and you try to authenticate with a new user with the agent role, you’ll be automatically logged out by Zendesk and arrive back at the FusionAuth login screen with no error message displayed.

Feedback

How helpful was this page?

See a problem?

File an issue in our docs repo

Quick Links

  • Download
  • Cloud Pricing
  • Editions Pricing
  • Contact Us
  • Jobs (come work with us)
  • My Account

Resources

  • Docs
  • Blog
  • Community & Support
  • Upgrade from SaaS
  • Upgrade from Homegrown
  • Upgrade from Open Source

Everything Else

  • Privacy Policy
  • Product Privacy Policy
  • License
  • License FAQ
  • Enterprise Sales FAQ
  • Security (contact, bug bounty, etc)
  • Technical Support

Connect with Us

logo
Subscribe for Updates
We only send dev friendly newsletters. No marketing fluff!
© 2021 FusionAuth