Manage users and groups with SAML in DESK SaaS

DESK SaaS enables authentication through your organization's identity provider (IdP). If you want to use your organization's corporate credentials for authentication in DESK, you can set up SAML to delegate authentication to your IdP.

SAML 2.0 is used for authentication. Based on the domain part of your corporate email address, DESK can determine if SAML was configured for that domain and redirect to your company’s IdP for authentication.

IdP requirements

Your IdP needs to follow some basic SAML specification and security requirements to be compliant with DESK SSO:

The entire SAML message must be signed (signing only SAML assertions is insufficient and will generate a 400 Bad Request response)
The SAML protocol version is urn:oasis:names:tc:SAML:2.0:protocol
The NameID format is urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
IdP response NotBefore and NotOnOrAfter assertion timestamps must consider system clock skew and must be set to at least 1 minute before and 1 minute after the current time (this particularly concerns AD FS default settings)
The IdP response status code must be urn:oasis:names:tc:SAML:2.0:status:Success
The SignatureMethod algorithm is http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
The DigestMethod algorithm is http://www.w3.org/2001/04/xmlenc#sha256
No assertion encryption

DESK SSO SP metadata is provided at https://sso.desk.com/sso/metadata. If your IdP requires manual configuration and you don't have any XML parser addons installed in your Chrome browser, we recommend that you view the metadata in Firefox.

Depending on the IdP type, these endpoints need to be configured as follows:

https://sso.desk.com:443/saml2/login for Entity ID / Audience Restriction
https://sso.desk.com:443/saml2/sp/consumer for Single Sign On URL / Destination URL / Recipient URL
https://sso.desk.com:443/saml2/sp/logout for Single Logout Service URL

If your IdP configuration screen contains the option to set SAML bindings for login or logout, set it to urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST.

SAML federated IdP configuration

To set up SAML for your domain

Create a fallback user account
Verify your ownership of the domain
Configure metadata
Test your configuration

1. Create a fallback user account

When a user signs in, DESK checks the domain part of your corporate email address to determine whether SAML was configured for that domain. If there is a match, the sign-in is redirected to your company’s IdP for authentication. For a fallback, you need an email address that will not be redirected like this.

Important

You need to create a fallback user account so you don't get locked out if you have configuration troubles.

Your fallback account must be a non-federated user account that has the manage users and manage groups permissions and isn't covered by the federated login.

Invite a user with a non-federated email address (an email address with a different domain than the one for which you are setting up SAML).
Specify the manage users and manage groups permissions in the invitation (users can be invited via the User management page).

2. Verify your ownership of the domain

Before you can configure the domain for which you want to set up SAML, you need to prove ownership of the domain.

Select Account settings from the user menu on the right side of the menu bar.
Select Single sign-on from the navigation menu on the left side.
In the Verify domain section, enter the domain (for example, @mycompanyname.com) for which you want to set up SAML.
Select Copy and add the TXT resource record to your domain’s DNS configuration.
Select Verify so that DESK can verify that the record was added to your domain’s DNS.
It may take a few minutes for the record to be propagated in the DNS system and the value to become available for DESK to verify.
After successful verification, the domain is listed in Verified domains.

If people in your organization use more than one domain to sign in (for example, @mycompanyname.com and @uk.mycompanyname.com), you can add additional domains using the same procedure: enter and verify the additional domains to add them to the Verified domains list.

3. Configure metadata

After you create a fallback user account and verify your ownership of the domain, you can configure metadata.

Select Add configuration to start configuring metadata.
Select Download XML to download the service provider (SP) metadata displayed in the Service provider SAML 2.0 XML metadata.
- Alternative: if you prefer, you can select and copy the displayed data from this page instead of downloading a file.
Register the data at your IdP and get the metadata of your IdP in XML format. The activities involved in this step depend upon your IdP's interface and requirements.
Example IdP-specific instructions for registering the SP data at your IdP and getting the IdP metadata:
- AD FS
- Azure
- GSuite
- Okta
These examples were correct at the time of writing, but DESK has no control over any changes that may be made by your IdP.
Select Upload XML to upload the file containing the metadata of your IdP in XML format.
- Alternative: if you prefer, you can paste the IdP metadata text directly into the Identity provider SAML 2.0 XML metadata box instead of uploading a file.
In the Attribute mapping section, specify the following:
- First name attribute is the attribute that contains the first name of a user.
  For Microsoft Azure, it's http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
- Last name attribute is the attribute that contains the last name.
  For Microsoft Azure, it's http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
- Security group claim attribute contains the groups/roles of a user from your IdP. This field is needed if you want to use SAML authorization.
Select Validate configuration to verify your settings. You may need to sign in to your SSO.
If validation is successful, DESK will display a confirmation message:

Close that message to return to the Add configuration page and then select Continue to display a summary of the validated configuration.
Select Single sign-on to enable your configuration.
Note: Don't sign out of DESK yet in case any SSO issues occur.
Select Save to save your configuration.

4. Test your configuration

To test your configuration

Open a new browser instance and a new incognito window.
Navigate to sso.desk.com and type your email address at the sign-in page.
Select Next.
You should be redirected to your company’s IdP.
Provide your domain password.
After successful authentication, you should be redirected to your DESK environment’s home page.

Troubleshooting:

If you experience trouble, use the non-federated user (the fallback user account you created earlier) to sign in and change the configuration or disable federation.
See Frequently asked questions below for answers to common questions.

SAML authorization

You can use SAML authorization to manage permissions in DESK. To do so, you need to map groups from your IdP to groups in DESK.

Select Group management and select a group.
- We strongly recommend that you create a new group first (select Create new group) to test whether SAML authorization works for that group.
- Make sure that you have a non-federated user with manage groups permission as discussed earlier.
When you specify a Security group claim name for a group and select Save
- All existing users from that group will be removed
- The group becomes a federated group. Assignment of users to that group is then controlled via the Security group claim attribute that you specified on the Single-sign on page.
Expand the Edit pane of a group to set up the mapping.
Specify a value in the field Security group claim name. This is the federated group name that is returned by your IdP and that this DESK group is mapped to.
- This typically isn't a group display name. It may be, for example, an LDAP ID.
SAML federated group mapping - example
Select Save.
Note: Don't sign out of DESK yet.
Open a new browser instance and a new incognito window and perform the sign-in.
Navigate to account settings (select Account settings in the user menu) and verify that you can still see the User management and Group management tabs on the left.
If you can't see them, you've lost your DESK admin permissions. Use the non-federated user account to change the configuration if you've run into any issues.
DESK checks the value of the Security group claim attribute of each user following successful sign-in. If a matching DESK group is found, the user is added to the DESK group and inherits all permissions of that group.

Note:

When using SAML authorization, it's not required that you invite users to DESK. If a user doesn't yet exist in DESK, but during sign-in one or more matching DESK groups are found (via the security group claim name), the user is created automatically.
Upon each sign-in, the DESK group assignment is updated based on the values specified in the Security group claim attribute.

SAML IdP configuration

Follow the examples linked here to configure any of these SAML identity providers (IdPs) to work with DESK SSO.

Frequently asked questions (FAQ)

What’s the proper `NameIdFormat`?

The NameIdFormat must be urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.

What needs to be signed in SAML?

Whole messages need to be signed, including logout request and response. It's not sufficient to just sign the assertion part.

Why am I logged out from my services when I've requested a logout from DESK?

Upon logout, a global logout is triggered, including for your IdP, which then cascades to other services. Otherwise you would be logged out from DESK, but it would be sufficient to just enter your email to reauthenticate.

If you want to disable it (not a good idea from a security standpoint), edit your metadata, remove all SingleLogoutService tags, and upload the updated metadata.

What claim rules do I need in AD FS on the DESK relying party?

You need two issuance transform rules, in this order:

The first one uses the Send LDAP Attributes as Claims rule template and creates an outgoing claim type named E-Mail Address from an LDAP attribute in your attribute store containing the DESK username (the user’s domain email address).
The second one uses the Transform an Incoming Claim rule template and creates an outgoing claim type Name ID and outgoing name ID format Email with the Pass through all claim values option enabled.

What are the possible causes of the DESK technical difficulties page?

If, after you authenticate with your IdP, you are redirected to a DESK page such as We’ve run into technical difficulties… or 400 Bad Request, it's likely that there is a problem with the configuration.

The most common causes of this are:

Your IdP doesn’t accept an authN request using our NameId format and returns an error response with status code InvalidNameIdPolicy. The NameIdFormat must be urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress. You might also need a rule to create a NameId using our format.
You're using a <saml:Attribute/> to return the DESK username but the attribute wasn't recognized by DESK; alternatively, we couldn't find it using NameID as we didn't recognize its format. See the previous question (What claim rules do I need in AD FS on the DESK relying party?) for the proper format.
DESK didn't trust your IdP SAML signing certificate. The IdP SAML metadata you uploaded did not contain a certificate for signing that matches the certificate in the assertion sent by your IdP. Verify that the certificate is in the metadata XML file that was uploaded to DESK. If you're using a URL to upload the metadata, look at the contents generated by the URL. In some organizations, the SAML signing certificate must be requested separately and manually inserted into the metadata by saving the URL contents to a file, adding the signing certificate to the file, and then uploading the file to us.
The response from the IdP isn't fully signed (assertion signature might be present, but it isn't sufficient).
Your IdP doesn't accept some SAML objects or attributes that the SAML 2.0 specification describes as optional. Please contact DESK Support.

Are SAML users added automatically to DESK?

Yes, users are added following successful authentication.

Is the domain verification TXT resource record needed permanently?

No, it can be removed after DESK has successfully validated ownership of the domain.

Are multiple domains and subdomains supported for authentication?

Yes, but you need to do domain verification and create a configuration for each domain separately. Each domain configuration can use the same IdP metadata and settings.

Is sending a full DN allowed in a group attribute?

No, a full DN contains commas and this is recognized as independent group names. The IdP should send the group name or group ID.