FusionAuth developer image
FusionAuth developer logo
  • Back to site
  • Expert Advice
  • Blog
  • Developers
  • Downloads
  • Account
  • Contact sales
Navigate to...
  • Welcome
  • Getting Started
  • 5-Minute Setup Guide
  • Release Notes
  • Core Concepts
    • Overview
    • Users
    • Roles
    • Groups
    • Entity Management
    • Registrations
    • Applications
    • Tenants
    • Identity Providers
    • Key Master
    • SCIM
    • Search
    • Authentication and Authorization
    • Integration Points
    • Localization and Internationalization
    • Editions and Features
    • Roadmap
  • Installation Guide
    • Overview
    • System Requirements
    • Server Layout
    • Cloud
    • Cluster
    • Docker
    • Fast Path
    • Kubernetes
      • Overview
      • Deployment Guide
      • Minikube Setup
      • Amazon EKS Setup
      • Google GKE Setup
      • Microsoft AKS Setup
    • Kickstart™
    • Homebrew
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Common Configuration
  • Admin Guide
    • Overview
    • Account Portal
    • Config Management
    • Licensing
    • Monitoring
    • Proxy Setup
    • Securing
    • Technical Support
    • Troubleshooting
    • Upgrading
  • Migration Guide
    • Overview
    • General
    • Auth0
    • Keycloak
    • Amazon Cognito
    • Firebase
    • Tutorial
  • APIs
    • Overview
    • Authentication
    • Errors
    • Actioning Users
    • API Keys
    • Applications
    • Audit Logs
    • Connectors
      • Overview
      • Generic
      • LDAP
    • Consents
    • Emails
    • Entity Management
      • Overview
      • Entities
      • Entity Types
      • Grants
    • Event Logs
    • Families
    • Forms
    • Form Fields
    • Groups
    • Identity Providers
      • Overview
      • Links
      • Apple
      • External JWT
      • Epic Games
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
      • SAML v2
      • SAML v2 IdP Initiated
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • Xbox
    • Integrations
    • IP Access Control Lists
    • JWT
    • Keys
    • Lambdas
    • Login
    • Message Templates
    • Messengers
      • Overview
      • Generic
      • Kafka
      • Twilio
    • Multi-Factor/Two Factor
    • Passwordless
    • Reactor
    • Registrations
    • Reports
    • SCIM
      • Overview
      • SCIM EnterpriseUser
      • SCIM Group
      • SCIM Service Provider Config.
      • SCIM User
    • System
    • Tenants
    • Themes
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • Webhooks
  • Client Libraries
    • Overview
    • Dart
    • Go
    • Java
    • JavaScript
    • .NET Core
    • Node
    • OpenAPI
    • PHP
    • Python
    • Ruby
    • Typescript
  • Themes
    • Overview
    • Examples
    • Helpers
    • Localization
    • Template Variables
  • Email & Templates
    • Overview
    • Configure Email
    • Email Templates
    • Email Variables
    • Message Templates
  • Events & Webhooks
    • Overview
    • Writing a Webhook
    • Securing Webhooks
    • Events
      • Overview
      • Audit Log Create
      • Event Log Create
      • JWT Public Key Update
      • JWT Refresh
      • JWT Refresh Token Revoke
      • Kickstart Success
      • User Action
      • User Bulk Create
      • User Create
      • User Create Complete
      • User Deactivate
      • User Delete
      • User Delete Complete
      • User Email Update
      • User Email Verified
      • User IdP Link
      • User IdP Unlink
      • User Login Failed
      • User Login Id Duplicate Create
      • User Login Id Duplicate Update
      • User Login New Device
      • User Login Success
      • User Login Suspicious
      • User Password Breach
      • User Password Reset Send
      • User Password Reset Start
      • User Password Reset Success
      • User Password Update
      • User Reactivate
      • User Registration Create
      • User Registration Create Complete
      • User Registration Delete
      • User Registration Delete Complete
      • User Registration Update
      • User Registration Update Complete
      • User Registration Verified
      • User Two Factor Method Add
      • User Two Factor Method Remove
      • User Update
      • User Update Complete
  • Example Apps
    • Overview
    • Dart
    • Go
    • Java
    • JavaScript
    • .NET Core
    • PHP
    • Python
    • Ruby
  • Lambdas
    • Overview
    • Apple Reconcile
    • Client Cred. JWT Populate
    • Epic Games Reconcile
    • External JWT Reconcile
    • Facebook Reconcile
    • Google Reconcile
    • HYPR Reconcile
    • JWT Populate
    • LDAP Connector Reconcile
    • LinkedIn Reconcile
    • Nintendo Reconcile
    • OpenID Connect Reconcile
    • SAML v2 Populate
    • SAML v2 Reconcile
    • SCIM Group Req. Converter
    • SCIM Group Resp. Converter
    • SCIM User Req. Converter
    • SCIM User Resp. Converter
    • Sony PSN Reconcile
    • Steam Reconcile
    • Twitch Reconcile
    • Twitter Reconcile
    • Xbox Reconcile
  • Identity Providers
    • Overview
    • Apple
    • Epic Games
    • External JWT
      • Overview
      • Example
    • Facebook
    • Google
    • HYPR
    • LinkedIn
    • Nintendo
    • OpenID Connect
      • Overview
      • Azure AD
      • Discord
      • Github
    • Sony PlayStation Network
    • Steam
    • Twitch
    • Twitter
    • SAML v2
      • Overview
      • ADFS
    • SAML v2 IdP Initiated
      • Overview
      • Okta
    • Xbox
  • Messengers
    • Overview
    • Generic Messenger
    • Kafka Messenger
    • Twilio Messenger
  • Connectors
    • Overview
    • Generic Connector
    • LDAP Connector
    • FusionAuth Connector
  • Self Service Account Mgmt
    • Overview
    • Updating User Data & Password
    • Add Two-Factor Authenticator
    • Add Two-Factor Email
    • Add Two-Factor SMS
    • Customizing
    • Troubleshooting
  • Advanced Threat Detection
    • Overview
  • Integrations
    • Overview
    • CleanSpeak
    • Kafka
    • Twilio
  • OpenID Connect & OAuth 2.0
    • Overview
    • Endpoints
    • Tokens
  • SAML v2 IdP
    • Overview
    • Google
    • Zendesk
  • Plugins
    • Plugins
    • Writing a Plugin
    • Custom Password Hashing
  • Guides
    • Overview
    • Advanced Registration Forms
    • Breached Password Detection
    • Multi-Factor Authentication
    • Multi-Tenant
    • Passwordless
    • Securing Your APIs
    • Silent Mode
    • Single Sign-on
  • Tutorials
    • Overview
    • User Control & Gating
      • Gate Unverified Users
      • Gate Unverified Registrations
      • User Account Lockout
    • Setup Wizard & First Login
    • Register/Login a User
    • Start and Stop FusionAuth
    • Authentication Tokens
    • Key Rotation
    • JSON Web Tokens
    • Prometheus Setup
    • Switch Search Engines
    • Two Factor (pre 1.26)
  • Reference
    • CORS
    • Configuration
    • Data Types
    • Known Limitations
    • Password Hashes

    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

    © 2021 FusionAuth
    Subscribe for developer updates