Single Sign-On (SSO) allows your organization to securely access Spruce using your existing identity provider (Microsoft Entra ID), eliminating the need for teammates to manage separate Spruce passwords. SSO is only available on the Communicator Plan with the purchase of an add-on. This article covers how to enable Microsoft Entra ID SSO in Spruce.
IN THIS ARTICLE
- Introduction to Single Sign-On (SSO)
- How to Enable SSO with Microsoft Entra ID (Web Browser Only)
- Automatic Account Creation in Spruce with Entra SSO
- Spruce SSO Authentication for Existing Spruce Users
- Editing Your Client Secret
- Automatic Teammate Suspension
- Restoring Teammates with SSO
-
FAQs
- Microsoft Entra ID SSO is available on the Communicator plan with an Add-On purchase. Upgrade by clicking here on a desktop computer.
- Administrators can enable SSO for their organization.
Introduction to Single Sign-On (SSO)
Single Sign-On (SSO) helps organizations manage access more securely and efficiently by requiring that teammates sign in to Spruce with the same credentials as their organization’s SSO provider (ex. Microsoft Entra ID).
This article specifically covers how to enable Microsoft Entra ID SSO in Spruce. Learn more about Single Sign-On (SSO) management at Spruce.
How to Enable SSO with Microsoft Entra ID (Web Only)
Step One: Purchase SSO Add-On
Single Sign-On (SSO) is available for customers on the Communicator plan with an add-on purchase of $300/month. Administrators must purchase the add-on before they can connect to an SSO provider in Spruce.
- Navigate to Settings > Organization Preferences > Single Sign-On (SSO) Authentication
- Click “Purchase SSO Add-On.” A dialog will appear on your screen.
- Check the checkbox to confirm you understand that your Spruce plan and monthly pricing will be adjusted.
- Click “Purchase Spruce Add-On” to complete your purchase. You will not be billed for the add-on until you enable SSO for your organization.
Step Two: Enable SSO for your organization
Once the add-on purchase is completed, administrators can enable Single Sign-On (SSO) for their organization using Spruce in a web browser by navigating to Settings > Organization Preferences > Single Sign-On (SSO) Authentication.
Enabling Microsoft Entra ID SSO
To begin, log in to your Microsoft Entra Admin Center and create an OIDC web application for Spruce. You must be at least a Cloud Application Administrator in Microsoft Entra to create an OIDC web app.
As you create the OIDC app, you will gather your Application (client) ID, Client Secret, and Issuer URI (OpenID Connect metadata document URL). These will need to be copied and pasted into Spruce to enable SSO.
- Go to Microsoft Entra Admin Center > App registrations > New Registration
-
Register the application
- Name your New Application (e.g. Spruce Health SSO)
- Ensure that Single tenant only is selected for Support account types
- Add https://app.sprucehealth.com/sso/callback as the Web Redirect URI
- Click Register
- Once it’s created, the Application (client) ID will be visible under the Essentials section. Copy this and save it, as it will need to be entered into Spruce.
-
Next, the Client Secret needs to be configured.
- Go to > Certificates & secrets in the left side column
- Go to the Client secrets section and tap + New Client Secret
- Enter “Spruce Health SSO Secret” in the description field.
- Next > Select an expiration date.
- *IMPORTANT* Take note of the client secret expiration date. Before this client secret expires, a new client secret must be generated and updated in Spruce to ensure that SSO authentication continues functioning properly.
- Tap Add to create the Client Secret.
- Make sure to copy the Secret Value and not the Secret ID. The secret value will only be displayed for a short period of time and won’t be fully visible again. Save this, as it will need to be entered into Spruce.
-
Next, Add Additional Claim
- Go to Token configuration > Add optional claim
- Choose ID
- Check the box for upn
- Click Add
- Next, the API permissions need to be configured. Go to API permissions in the left side column.
- Tap > Add a permission. Go to > Delegated permissions. Scroll down to the permissions table.
- Select each item under the OpenId permissions (email, offline_access, openid, and profile).
- Tap > Add permissions.
-
Go to Overview in the left hand column > then Endpoints at the top of this page.
- Scroll down and locate the “OpenID Connect metadata document” URL. Copy this and save it, as this will be used in Spruce as the Issuer URI.
Next, return to Spruce to complete Microsoft Entra ID SSO set up.
You must be an Administrator in Microsoft Entra ID in order to complete SSO set up in Spruce, and your Spruce account email must match the email from the Microsoft Entra ID account that you’d like to connect to.
- In Spruce, go to Settings > Organization Preferences > Single Sign-On (SSO) Authentication
- Tap Connect next to Microsoft to be taken to the Microsoft Entra ID SSO page where you can begin the connection process.
Begin Step 1 > Enter your Microsoft Entra ID organization information
- Note - you must follow the above steps and create an OIDC app integration within your Microsoft Admin Console before proceeding.
-
Enter your Application (Client) ID.
- This is the client ID of the Microsoft Entra ID application you have created for Spruce in your Microsoft Admin Console.
-
Enter your Client Secret.
- This is the client secret of the Microsoft Entra ID application. Spruce stores it securely and never displays it again.
-
Enter your Issuer URI.
- This is the OIDC issuer URI (OpenID Connect metadata document) of your Microsoft Entra ID organization. (ex: login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration).
Continue with Step 1 > Authenticate with Microsoft Entra ID SSO
-
Tap Save and Log in to Microsoft.
- You must log in using the same email from Microsoft that you’d like to connect to Spruce.
- The domain of your Microsoft account must also be the same as the domain as your Spruce account email address. (Ex: @organization.com)
- Once this step is complete, a green checkmark will appear next to Step 1. Proceed to step 2.
Begin Step 2 > Review Spruce Teammate Emails
- Note: In some cases, this step may be automatically completed and a green checkmark will be displayed. If so, you can move to Step 3.
- Tap > Check Spruce Teammate Emails. This will ensure that all existing Spruce teammates use the same Microsoft domain on their Spruce account email addresses. Ex: If your organization uses @exampleclinic.com, all teammates in Spruce must use an @exampleclinic.com email address.
- If any account emails do not match, a dialog will display which teammates need to update their email address. Ask teammates to update their Spruce account email address by going to Settings > Account > Edit Email.
SSO cannot be enabled for your organization until all Spruce teammate account emails match your Microsoft domain.
Begin Step 3 > Enable SSO for Your Organization
- Check the checkbox to confirm you understand the implications of turning on SSO for your organization.
-
Tap Enable SSO to complete the connection.
Once you enable Microsoft Entra ID SSO, the following actions will take place:
- You will be returned to the main SSO page and will see a “Connected SSO Provider” card with a green checkmark, indicating that the connection was successful.
- All Spruce teammates will immediately be logged out of their Spruce accounts across all devices, and can no longer log in using an email and password. Teammates will need to log in to Spruce again using their Microsoft email, and will authenticate through Microsoft Entra ID.
- Password-based login and two-factor authentication will be disabled for your organization.
- If teammates are on an active phone call, they will be able to finish their call before being logged out.
Automatic Account Creation in Spruce with Entra SSO
When a teammate signs in to Spruce with Entra SSO for the first time, Spruce automatically creates an account for them using their Entra ID profile information (email, first name, and last name).
Email Address
- Spruce will use the email address from Entra ID for their Spruce account.
- If no email address is available, Spruce will use the Entra User Principal Name (UPN), which must have a custom domain. The default onmicrosoft.com domain is not supported.
First and Last Name
- Spruce will use the first and last name provided in Entra ID for their Spruce account.
- If either name is missing, Spruce will attempt to create a first and last name from the teammate’s Display Name in Entra.
Spruce SSO Authentication for Existing Spruce Users
Existing Spruce users can sign in with Entra SSO as long as their Spruce account email matches their email address in Entra ID. If no email address is listed in Entra ID, their Spruce account email must match their User Principal Name (UPN) instead.
Editing Your Client Secret
After connecting Microsoft Entra ID SSO, you will have the ability to edit your Microsoft Entra ID Client Secret in Spruce, if needed. The Client Secret is a secure credential that allows Spruce to authenticate its connection with Microsoft. Updating your Microsoft Entra ID Client Secret will not disable SSO or change how your teammates sign in.
Before updating your Microsoft Entra ID Client Secret in Spruce, you will need to retrieve the new Client Secret from Microsoft. You can find your Client Secret in the Microsoft Admin Console on the app page that you created for Spruce.
To update your Client Secret in Spruce:
- In Spruce, go to Settings > Organization Preferences > Single Sign-On (SSO) Authentication.
- On the Connected SSO Provider card, select Edit Client Secret. The dialog will display the last four characters of your current Client Secret.
- Enter the new Client Secret from Microsoft and select Save.
- Once the Client Secret is successfully updated, Spruce will confirm the change.
After the Client Secret is updated, all Admins in your organization will receive an email with the name of the Admin who made the change, and when it occurred.
If the update is unsuccessful, your existing Client Secret will remain active.
Note: Your Client ID and Issuer URI cannot be edited while SSO is enabled. To change either of these values, you must first disable SSO and complete the Microsoft Entra ID SSO setup process again.
Automatic Teammate Suspension in Spruce
Automatic Teammate Suspension ensures that teammate access is securely synced between Microsoft Entra ID and Spruce. When enabled, deleting a teammate in Microsoft (or removing a teammate from the SCIM app) automatically suspends their account in Spruce.
When a teammate is deactivated in Microsoft Entra ID:
- Their access to Spruce is immediately revoked. They are logged out of Spruce and can no longer sign in.
- Your organization is no longer billed for their seat in Spruce.
A Spruce Admin can later restore the suspended teammate, or permanently delete their account in Spruce.
Note: Suspending a teammate in Spruce does not transfer their resources. For example, if a phone number rings to the suspended teammate, an Admin will need to update the ring list manually. To transfer the teammate’s resources, permanently delete the teammate in Spruce.
If Automatic Teammate Suspension is not enabled, removing a teammate from Microsoft Entra ID does not affect their Spruce account. An Admin must manually suspend or delete the teammate in Spruce to revoke their access and stop billing for their seat.
How to Enable Automatic Teammate Suspension
Note: An entirely new app integration must be created in Microsoft Entra Admin Center to support this functionality. The Microsoft Entra ID OIDC app that was created for enabling the Spruce SSO connection will not support this.
- Create a new SCIM application in the Microsoft Entra Admin Console
- Go to Enterprise apps > New application > Create your own application
- Name the application (e.g. Spruce Health SCIM)
- Select Integrate any other application you don’t find in the gallery (Non-gallery)
- Click Create
-
Next, Configure provisioning
- Go to Provisioning > New configuration
- Ensure Bearer authentication is selected as the Authentication method
- Enter https://auth-api.sprucehealth.com/scim/v2 as the Tenant URL
- Copy the SCIM token from Spruce into the Secret token field
- Click Test connection - If a connection error occurs, verify that the Tenant URL and Secret token are correct
- Click Create
-
Next, Configure attribute mapping
- Go to Attribute mapping
- On the default attribute mapping, click the edit button on the userPrincipalName to userName mapping, change the Matching precedence to 2, and click Apply
- Click the edit button on the mailNickname to externalId mapping
- Change the Source attribute to objectId, check the Match objects using this attribute box, set the Matching precedence to 1, and click Apply
- Click Save
-
Next, Configure scoping filters
- Go to scoping filters > Edit
- In the Object actions drop down menu, uncheck Delete - Create and Update should remain checked
- Go to Review and Create and click Save
-
Next, Assign users to application
- Go to Users and Groups > Add user/group
- Click None Selected, then assign existing users and groups to the application.
-
Finally, Turn on Provisioning
- Go to Provisioning
- Set Provisioning Status to On and click Save
Restoring Teammates with SSO
Restoring a teammate in Microsoft Entra ID does not automatically restore their Spruce account. An Admin must also manually restore the teammate in Spruce. Once restored in both systems, the teammate can log in to Spruce again using SSO.
Similarly, if a teammate is restored in Spruce before they are restored in Microsoft Entra ID, they will not be able to log in to Spruce until they are also restored in Microsoft Entra ID.
Learn more about restoring teammates in Spruce.
Learn more about the following in the Single Sign-On SSO article:
- Inviting Teammates to Spruce with SSO
- Removing Teammates from Spruce with SSO
- Disabling SSO for your Organization
-
Managing other SSO settings
Microsoft Entra ID SSO FAQs
Can teammates join automatically with our Microsoft Entra ID domain?
No, teammates must be manually invited through Spruce.
Does Spruce automatically create teammate accounts from Microsoft Entra ID?
No, Spruce does not support automatic provisioning with Microsoft Entra ID at this time.
Does deactivating a teammate from Microsoft Entra ID automatically remove them from Spruce?
If you have enabled Automatic Teammate Suspension with Spruce and Microsoft Entra ID, then removing a teammate from Microsoft Entra ID will automatically suspend that teammate’s account in Spruce. They will no longer be able to log in to their Spruce account, and you will no longer be charged for their teammate seat on your monthly Spruce bill.
If you have not enabled Automatic Teammate Suspension, then removing a teammate from Microsoft Entra ID will not remove the teammate from Spruce. Admins will need to manually remove or suspend teammates in Spruce, and your organization will continue to be charged for this seat until they are removed.
Does suspending a teammate from Microsoft Entra ID automatically remove them from Spruce?
No. Even if Automatic Teammate Suspension is set up with Microsoft Entra ID, Microsoft Entra ID teammates must specifically be Deleted or Unassigned from the SCIM app in Microsoft Entra ID in order to automatically suspend their account in Spruce. If a Microsoft teammate is only suspended in Microsoft Entra ID, their account will remain active in Spruce and they will still be able to log in.
Does adding a teammate back to Microsoft Entra ID automatically give them access to Spruce again?
No. Restoring a teammate in Microsoft Entra ID does not automatically restore their Spruce account. An Admin must also manually restore the teammate in Spruce. Once restored in both systems, the teammate can log in to Spruce again using SSO.
If SSO is enabled, are admins able to sign in to Spruce using an email and password?
No. Once SSO is enabled, all teammates must sign in to Spruce with their authenticated Microsoft Entra ID email address.
Will enabling Microsoft Entra ID SSO overwrite the name/title/display name of an existing Spruce account?
No. It will only pull this information from Microsoft Entra ID for new Spruce accounts.
How does changing/updating an email address in Microsoft Entra ID affect the same Spruce account using SSO?
If a Spruce teammate’s email address is changed in Microsoft Entra ID, they will not be able to log in. Contact Spruce support to have this information updated.
What happens if my Microsoft Entra ID Client Secret expires?
If your Microsoft Entra ID Client Secret expires, teammates will begin to be logged out of Spruce within 4 hours and will be unable to sign back in until the secret is updated.
To avoid interruptions, Admins should create a new Client Secret in Microsoft Entra ID and update it in Spruce before the current secret expires.
If all Admins lose access, contact Spruce Support for assistance restoring access. Once the Client Secret is updated, all Admins will receive an email confirming who made the change and when.
What if an error is generated due to lack of email, First name or last name?
If a Spruce account cannot be created from the information available on the Entra ID user, a descriptive error message will be displayed on the Spruce login page. It will inform the user what information is missing and to ask an administrator to add it to the Entra ID user.