FusionAuth developer image
FusionAuth developer logo
  • Back to site
  • Expert Advice
  • Blog
  • Developers
  • Downloads
  • Account
  • Contact sales
Navigate to...
  • Welcome
  • Getting Started
    • Getting Started
    • 5-minute Setup Guide
      • Overview
      • Docker
      • Fast Path
      • Sandbox
    • Setup Wizard & First Login
    • Register a User and Login
    • Self-service Registration
    • Start and Stop FusionAuth
    • Core Concepts
      • Overview
      • Users
      • Roles
      • Groups
      • Registrations
      • Applications
      • Tenants
      • Identity Providers
      • Authentication/Authorization
      • Integration Points
    • Example Apps
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • PHP
      • Python
      • Ruby
    • Tutorials
  • 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
    • Marketplaces
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Common Configuration
  • Migration Guide
    • Overview
    • General
    • Auth0
    • Keycloak
    • Amazon Cognito
    • Firebase
    • Microsoft Azure AD B2C
    • Tutorial
  • Admin Guide
    • Overview
    • Account Portal
    • Config Management
    • Editions and Features
    • Key Rotation
    • Licensing
    • Monitoring
    • Prometheus Setup
    • Proxy Setup
    • Reference
      • Overview
      • Configuration
      • CORS
      • Data Types
      • Hosted Login Pages Cookies
      • Known Limitations
      • Password Hashes
    • Releases
    • Roadmap
    • Search And FusionAuth
    • Securing
    • Switch Search Engines
    • Technical Support
    • Troubleshooting
    • Upgrading
    • WebAuthn
  • Login Methods
    • Identity Providers
      • Overview
      • Apple
      • Epic Games
      • External JWT
        • Overview
        • Example
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
        • Overview
        • Amazon Cognito
        • Azure AD
        • Discord
        • Github
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • SAML v2
        • Overview
        • ADFS
        • Azure AD
      • SAML v2 IdP Initiated
        • Overview
        • Okta
      • Xbox
    • OIDC & OAuth 2.0
      • Overview
      • Endpoints
      • Tokens
      • OAuth Modes
    • Passwordless
      • Overview
      • Magic Links
      • WebAuthn & Passkeys
    • SAML v2 IdP
      • Overview
      • Google
      • Zendesk
  • Developer Guide
    • Overview
    • API Gateways
      • Overview
      • ngrok Cloud Edge
    • Client Libraries & SDKs
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • Node
      • OpenAPI
      • PHP
      • Python
      • React
      • Ruby
      • Typescript
    • 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
        • Group Create
        • Group Create Complete
        • Group Delete
        • Group Delete Complete
        • Group Update
        • Group Update Complete
        • Group Member Add
        • Group Member Add Complete
        • Group Member Remove
        • Group Member Remove Complete
        • Group Member Update
        • Group Member Update Complete
        • 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 Dup. Create
        • User Login Id Dup. 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 Reg. Create
        • User Reg. Create Complete
        • User Reg. Delete
        • User Reg. Delete Complete
        • User Registration Update
        • User Reg. Update Complete
        • User Reg. Verified
        • User 2FA Method Add
        • User 2FA Method Remove
        • User Update
        • User Update Complete
    • Guides
      • Overview
      • Authentication Tokens
      • Exposing A Local Instance
      • JSON Web Tokens
      • Key Master
      • Localization and Internationalization
      • Multi-Factor Authentication
      • Multi-Tenant
      • Passwordless
      • Registration-based Email Verification
      • Searching With Elasticsearch
      • Securing Your APIs
      • Silent Mode
      • Single Sign-on
      • Two Factor (pre 1.26)
    • Integrations
      • Overview
      • CleanSpeak
      • Kafka
      • Twilio
    • Plugins
      • Overview
      • Writing a Plugin
      • Custom Password Hashing
    • User Control & Gating
      • Overview
      • Gate Unverified Users
      • Gate Unverified Registrations
      • User Account Lockout
  • Customization
    • Email & Templates
      • Overview
      • Configure Email
      • Email Templates
      • Email Variables
      • Message Templates
    • 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. Convtr.
      • SCIM User Req. Converter
      • SCIM User Resp. Converter
      • Sony PSN Reconcile
      • Steam Reconcile
      • Twitch Reconcile
      • Twitter Reconcile
      • Xbox Reconcile
    • Messengers
      • Overview
      • Generic Messenger
      • Twilio Messenger
    • Themes
      • Overview
      • Examples
      • Helpers
      • Localization
      • Template Variables
  • Premium Features
    • Overview
    • Advanced Registration Forms
    • Advanced Threat Detection
    • Application Specific Themes
    • Breached Password Detection
    • Connectors
      • Overview
      • Generic Connector
      • LDAP Connector
      • FusionAuth Connector
    • Entity Management
    • SCIM
      • Overview
      • Azure AD Client
      • Okta Client
      • SCIM-SDK
    • Self Service Account Mgmt
      • Overview
      • Updating User Data & Password
      • Add Two-Factor Authenticator
      • Add Two-Factor Email
      • Add Two-Factor SMS
      • Add WebAuthn Passkey
      • Customizing
      • Troubleshooting
    • WebAuthn
  • APIs
    • Overview
    • Authentication
    • Errors
    • API Explorer
    • 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
      • Twilio
    • Multi-Factor/Two Factor
    • Passwordless
    • Reactor
    • Registrations
    • Reports
    • SCIM
      • Overview
      • SCIM User
      • SCIM Group
      • SCIM EnterpriseUser
      • SCIM Service Provider Config.
    • System
    • Tenants
    • Themes
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • WebAuthn
    • Webhooks
  • Release Notes

    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

    Have a question or comment to share?

    Visit the FusionAuth community forum.

    © 2023 FusionAuth
    Subscribe for developer updates