Single sign on (SAML) and user provisioning (SCIM)

With single sign on, your team signs in to Deskwoot with the work account they already have, so nobody needs a separate Deskwoot password. Your company keeps these work accounts in an identity provider: the service where it manages who works there, like Microsoft Entra ID, Okta or Google Workspace. Deskwoot connects to it through SAML 2.0, a common standard that lets one service tell another who someone is. With user provisioning through SCIM, another standard, your identity provider can also add people to Deskwoot, keep their details up to date and remove them, all on its own.

Single sign on and user provisioning come with the Enterprise plan. Only administrators can set them up, under Settings > Single sign on. The page takes you through 5 steps in this order.

Step 1: Verify your email domain

Your email domain is the part after the @ in your team's email addresses, for example yourcompany.com. Only people with an address in a verified domain can sign in through your identity provider. You prove that the domain is yours with a DNS record. DNS is the address book of the internet, and you usually manage it at the company you bought the domain from.

1. Under 1. Which email domains belong to your company?, enter your domain without the @ and click Add domain.
2. Deskwoot shows the record you need. Where you manage the DNS of your domain, add a new record with these values:
   • Type: TXT
   • Name: your domain itself. Some DNS services want @ as the name instead.
   • Value: deskwoot-verification= followed by the code on the page. Use Copy next to it, so nothing goes missing.
3. Click Check now. When Deskwoot finds the record, the domain shows Verified.

A new record can take a few minutes, sometimes a few hours, before Deskwoot can see it. If the record is not there yet, check the name and the value, and try again later. You can add more than one domain. Each domain can be verified in one Deskwoot workspace only.

Step 2: Connect your identity provider

Under 2. Which identity provider does your company use?, Deskwoot shows Values for your identity provider. It works with Microsoft Entra ID, Okta, Google Workspace and any other SAML 2.0 provider.

1. In your identity provider, create a SAML app for Deskwoot.
2. Copy Deskwoot's values into the app:
   • Entity ID: Microsoft Entra ID calls it Identifier (Entity ID), Okta calls it Audience URI, and Google Workspace calls it Entity ID.
   • ACS URL: the address your provider sends people back to after they sign in. Microsoft Entra ID calls it Reply URL, Okta calls it Single sign on URL, and Google Workspace calls it ACS URL.
   • Metadata URL: some providers read all of Deskwoot's values from this address at once, so you do not have to copy them one by one.
3. Make sure your provider sends each person's email address. Set the Name ID format to email address, or send the address as an attribute called email or mail, or as the emailaddress claim.
4. Your provider has to sign the assertion, the part of its answer that says who signed in. Microsoft Entra ID and Okta do this by default. In Google Workspace, leave the default setting. Deskwoot does not support encrypted assertions, so leave encryption off.
5. Back in Deskwoot, under Your identity provider's settings, click Add provider settings and choose how you want to add them:
   • Paste metadata XML: your provider offers it as a file or a page called metadata, IdP metadata or federation metadata XML. Open it and paste all of it.
   • Enter by hand: enter the Provider entity ID, the Sign in URL and the Certificate. Deskwoot needs the sign in URL of the HTTP Redirect binding, and it starts with https://. Paste the whole signing certificate, with the BEGIN and END lines.
6. Click Save settings.

Saving changed settings turns single sign on off again. Test the sign in once more, then turn it back on.

Step 3: Test the sign in

Under 3. Does the sign in work?, click Test sign in and sign in at your identity provider with your own work account. Use an account whose address is in one of your verified domains. The test works while single sign on is still off, and single sign on stays off for everyone else while you test. Back on the page, Deskwoot shows the result and the email address your provider sent. If the test did not work, compare the entity ID, the sign in URL and the certificate with your provider, then test again.

Step 4: Turn on single sign on

Under 4. Turn on single sign on, switch on Single sign on. People with an address in your verified domains can now click Sign in with SSO on the Deskwoot sign in page. Until you require single sign on, they can still use their password too.

Step 5: Require single sign on (optional)

Under 5. Should people in your domains only sign in this way? (optional), switch on Require single sign on and confirm with Require it. Then:

• People with an address in your verified domains can only sign in through your identity provider. Deskwoot refuses their password and signing in with Google or Apple, and the sign in page sends them to single sign on.
• Anyone of them who is signed in another way is signed out the moment you turn it on.
• The workspace owner can always sign in with the password too, in case your provider fails.
• People with an address outside your domains, for example contractors, keep their password.
• When you invite someone with an address in your domains, they do not set a password. They click Continue with single sign on, and their first sign in through your provider accepts the invitation.

How your team signs in

1. On the Deskwoot sign in page, click Sign in with SSO.
2. Enter your Work email and click Continue.
3. Deskwoot takes you to your company's sign in page. After you sign in there, you are back in Deskwoot.

A Deskwoot tile in the Okta or Microsoft dashboard works too: Deskwoot then starts a fresh sign in through your provider. After single sign on, Deskwoot does not ask for its own two factor code. Your identity provider takes care of that step.

New people

Someone with an address in your domains who signs in through single sign on for the first time joins your workspace as an agent, on a free seat. You can make them an administrator under Settings > Agents.

• With no free seat, they see an error. Add seats under Settings > Billing, and they can try again. Deskwoot never buys seats on its own.
• A person can belong to one Deskwoot workspace only. Someone who already belongs to another Deskwoot workspace cannot join yours this way.

User provisioning (SCIM)

With user provisioning, your identity provider adds, updates and removes agents in Deskwoot for you. It works only for addresses in your verified domains and only on free seats.

1. Under User provisioning (SCIM), click Create token. A token is a long secret code that lets your provider talk to Deskwoot. Copy it right away: Deskwoot shows it only once. Then click Done.
2. In your identity provider, open the provisioning settings of your Deskwoot app and enter the SCIM base URL https://deskwoot.com/api/scim/v2 and the token:
   • Microsoft Entra ID: under Provisioning, paste the URL as Tenant URL and the token as Secret token.
   • Okta: choose SCIM 2.0, paste the URL as SCIM connector base URL, set the authentication mode to HTTP Header and paste the token as the Bearer token.
   • Google Workspace: in the Admin console, open the Deskwoot app under Apps > Web and mobile apps and click Configure auto-provisioning under Autoprovisioning. Paste the token, then the URL as the SCIM endpoint URL, map Primary email to userName and set Autoprovisioning to Active. Google is still rolling this out: if the app shows no Autoprovisioning, your organization does not have it yet, and people join on their first sign in instead.
3. Assign the people who should use Deskwoot to the app. Assign people, not groups: Deskwoot does not provision groups.

From then on, your provider does this on its own:

• Adds agents: only people with an address in your verified domains, and only on free seats. New people are agents. You make administrators under Settings > Agents.
• Updates people: names and email addresses follow your provider.
• Removes people: when you unassign or deactivate someone in your provider, they leave your workspace at once. Their Deskwoot login stays, and their conversations become unassigned. The workspace owner cannot be removed this way.

You can have up to 5 tokens. Each one shows when it was created and when it was last used. To stop a token, click Revoke next to it and confirm with Revoke token. People already in the workspace stay.

Summary

Under Settings > Single sign on, verify your email domain, connect your identity provider, test the sign in and turn on single sign on. If you want, require it for everyone in your domains, and let your provider add and remove agents through SCIM. Your team then signs in to Deskwoot with the work account they already have.

Frequently asked questions

What happens if our plan drops below Enterprise?

Single sign on and user provisioning stop, and people sign in with their password again. Someone who never had a Deskwoot password sets one with Forgot password? on the sign in page.

Deskwoot does not find my DNS record. What can I do?

A new record can take a few minutes, sometimes a few hours, before Deskwoot can see it. Check that the type is TXT, that the name is your domain (or @, if your DNS service wants that) and that the whole value is there, then click Check now again.

Someone sees that the workspace has no free seat. What now?

Add a seat under Settings > Billing, then the person signs in again. Deskwoot never buys seats on its own, also not through user provisioning.

What if our identity provider is down?

The workspace owner can always sign in with the password, even when single sign on is required. People with an address outside your verified domains keep their password too.

The test says my address is outside the verified domains. Why?

Your identity provider sent an email address whose domain you have not verified in Deskwoot. Test with an account whose address is in one of your verified domains, and check that your provider sends the email address as the Name ID or as the email attribute.