Single Sign-On (SSO) with SAML 2.0 lets your users sign in to deskbird with their existing identity provider (IdP). Below you'll find quick-start options for Okta and Keycloak, plus a full federation setup guide (SP-initiated SSO).
- SAML using Okta
- SAML using Keycloak
- Setup of SAML 2.0 Federation
- SAML certificate renewal
- When to use SAML vs. OAuth / OIDC
1. SAML using Okta
Use our dedicated Okta guide to configure an Okta SAML app, map the required attributes, and test SP-initiated SSO to deskbird. It includes screenshots, attribute statements, and troubleshooting tips.
👉 Step-by-step: Configure SAML SSO with Okta
2. SAML using Keycloak
Prefer using Keycloak? Follow the Keycloak guide to initiate SSO to deskbird.
👉 Step-by-step: Configure SAML SSO with Keycloak
3. Setup of SAML 2.0 Federation
SAML 2.0 (Security Assertion Markup Language) is an XML-based protocol to securely exchange authentication/authorization data between an identity provider (IdP) and a service provider (SP). deskbird supports SP-initiated SSO (authentication must start from deskbird).
If you want a tile in your IAM launcher (e.g., OneLogin, JumpCloud) that users can click, add a Bookmark application that launches the SP-initiated flow in deskbird:https://app.deskbird.com/saml?providerName={saml-provider-ID}
The SAML provider ID follows saml.{company-name}. Example for "Polaroid": https://app.deskbird.com/saml?providerName=saml.polaroid.
Create a separate, hidden Federation application in your IdP for the SAML connection itself (not visible to users).
3.1 General setup
Configure your IdP with the following deskbird Service Provider details:
| Service Provider ID (Entity ID) | https://api.deskbird.app/saml/metadata |
| ACS URL (Callback) | https://app.deskbird.com/__/auth/handler |
💡 For successful SAML 2.0 authentication, set NameID to the user's email address with format urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified.
Example assertion snippet
<saml2:Subject> <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" NameQualifier="<IdP 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> Send to deskbird for configuration
| IdP Entity ID | |
| IdP SSO URL | |
| IdP Certificate | Must start with -----BEGIN CERTIFICATE----- and end with -----END CERTIFICATE----- (paste without extra characters/new lines). |
If you have an IdP metadata file, you can simply send that instead.
3.2 User attributes
Required attribute (use the exact name):
| Attribute | Description |
| UPN email address used for sign-in, notifications, and booking info |
Recommended attributes:
| Attribute | Description |
| first_name | User's first name (displayed in the platform). Microsoft Entra ID's default givenname claim also works. |
| last_name | User's last name (displayed in the platform). Microsoft Entra ID's default surname claim also works. |
| avatar_url | Profile picture URL; initials are used if omitted |
| external_id | IdP user ID for matching |
| manager_id | IdP ID of the user's line manager (used for approvals) |
| locale | User's preferred language (defaults to company language if omitted) |
| job_title | User's job title |
| company_entity | User's legal entity (defaults to company entity if omitted) |
3.3 Name sync from your IdP
If users are created on their first SAML login (no SCIM or HRIS sync), deskbird takes their first and last name from your IdP and keeps it in sync:
- First login: the user is created with the first and last name from the SAML assertion.
- Later logins: if your IdP sends a different name, deskbird updates it. This also replaces names that were changed manually in deskbird.
- Editing: while your IdP provides the name, users and admins can't edit it in deskbird (web, iOS and Android). Name changes need to be made in your IdP and show up after the user's next login.
- SCIM or HRIS sync: if you also use one of these, that sync manages the name, and SAML never overwrites it.
- No name sent: if the assertion doesn't include both first and last name, users enter their name during setup and can still edit it.
💡 Only first and last name are synced. Other attributes, such as office or department, are not taken from SAML.
3.4 Metadata file
After creating the SAML application in your IdP, please send us the metadata file that includes:
- Certificate
- Entity ID
- SSO URL
4. SAML certificate renewal
SAML certificates have an expiration date (typically 1–3 years after creation). When a certificate is about to expire, your identity provider will alert you. It is important to renew the certificate before it expires to avoid login outages.
Start the renewal process at least 2–3 weeks before the expiry date to allow time for coordination.
Step-by-step renewal process (Microsoft Entra ID):
- In the Microsoft Entra ID portal, go to your deskbird Enterprise Application.
- Navigate to Single sign-on > SAML Certificates.
- Click the Edit (pencil) icon.
- Click New Certificate.
- Set the expiration date (default is 3 years).
- Click Save. The new certificate will appear with an Inactive status.
- Download the new certificate (Base64 format).
- Send the certificate to deskbird support via a support ticket. Include your company name and mention it is a SAML certificate renewal.
- deskbird support will replace the certificate on our side and confirm when it is ready.
- Once deskbird confirms, go back to Entra ID and activate the new certificate (set it to Active).
Downtime
There is typically no downtime during certificate rotation, as long as you coordinate the activation timing with deskbird support. The old certificate continues to work until you switch to the new one.
5. When to use SAML vs. OAuth / OIDC
If you are deciding between SAML and OAuth (Microsoft SSO), consider the following:
| Feature | SAML 2.0 | OAuth / Microsoft SSO / Google SSO |
|---|---|---|
| Certificate management | Requires periodic renewal | No certificate management needed |
| User experience | Users click "Sign in with company account (SSO)" on the login screen | Users click "Sign in with Microsoft" on the login screen |
| IdP flexibility | Works with any SAML 2.0 IdP (Okta, Keycloak, ADFS, etc.) | Microsoft and Google only |
| Plan requirement | User and Data Management Plus | Available on all plans |