Skip to main content

Setting up authentication via SAML 2.0

  • Updated

SAML 2.0, or Security Assertion Markup Language version 2.0, is an XML-based protocol used for secure exchange of authentication and authorization data between parties, typically between an identity provider and a service provider.

This standard allows us to provide Single Sign-On capabilities (SSO) for various directory systems, including Okta, OneLogin, and AD FS.

The authentication is always Service-Provider Initiated. That means the authentication will not be successful if it is started from the Federation application (setup explained below).

 

If you wish to have an application in your IAM solution (such as Okta, OneLogin and jumpcloud) that can be clicked by users, you should additionally set up a Bookmark application:

Bookmark application: This application can be shown to users and takes care that the authentication is initiated at the Service Provider (deskbird). The bookmark link uses the following format: https://app.deskbird.com/saml?providerName={saml-provider-ID} 

The SAML-provider-ID has the format "saml.{company name}". E.g., the full bookmark link for company "Polaroid" would be https://app.deskbird.com/saml?providerName=saml.polaroid . When we set up the SAML authentication for your company, we will let you know about exact bookmark link for the avoidance of any doubt.

Federation application: This application is not shown to users and works in the background. It should be configured as shown below.

 

Setup of SAML 2.0 Federation:

  1. General setup

To set up the SAML 2.0 process between deskbird and your directory, please use the following Service Provider information:

Service Provider ID

 https://api.deskbird.app/saml/metadata

ACS URL (callback URL)

 https://app.deskbird.com/__/auth/handler
💡 To ensure successful SAML 2.0 authentication with Deskbird, the NameID must be set to the user's email address using the format urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified. This configuration is essential for accurate user identification and seamless login experiences.
Example Configuration:
<saml2:Subject>
<saml2:NameID 
Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
NameQualifier="Identity Provider's Entity ID"
SPNameQualifier="https://api.deskbird.app/saml/metadata"
xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
email
</saml2:NameID>
<saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
</saml2:Subject>
For the setup on our side, we would need the following information from you:

IdP Entity ID

  

IdP SSO URL

  

IdP Certificate

 Must start with "-----BEGIN CERTIFICATE-----", and end with "-----END CERTIFICATE-----". Be careful to paste certificate without additional symbols (new lines).

If you have an Identity provider metadata file at hand, you can simply send us this.

  1. User attributes

For the authentication to work, we need at least access to the below mentioned attributes. Please make sure to use the exact same wording:

Attribute

Description
email UPN Email address of the user to send booking information, notifications and alerts
first_name First name of the user to display in the platform
last_name Last name of the user to display in the platform

In addition, we recommend to also provide the following user attributes. We use these to unlock further functionalities for the user and to improve the overall experience on our platform:

Attribute

Description
avatar_url URL to profile picture of user; user initials are used if both avatar_url is skipped
external_id ID given by IDP to match users
manager_id ID given by IDP to user's line manager; used for approval management
locale User's preferred language; company's default language is used if skipped
office Office that the user is located at
job_title Job title of the user
department Department of the user; Used for access management
company_entity Entity of user; company's default entity is used if skipped

 

  1. Metafile for configuration at deskbird

After setting up a SAML application in your directory, please send us the metafile of your configuration. This metafile should include:

  • Certificate
  • Entity ID
  • SSO URL 

Related articles