Single Sign-On (SSO): Okta

Single Sign-On (SSO) allows your organization to securely access Spruce using your existing identity provider (Okta), 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 Okta SSO in Spruce. 

IN THIS ARTICLE

• Introduction to Single Sign-On (SSO)
• How to Enable SSO with Okta (Web Browser Only)
  • Purchase SSO Add-On 
  • Enable SSO for your organization
• Editing Your Client Secret 
• Automatic Teammate Suspension in Spruce
  • Enable Automatic Teammate Suspension
• Restoring Teammates with SSO
• FAQs
   

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. Okta). SSO is only available on the Communicator Plan with the purchase of an add-on. 

This article specifically covers how to enable Okta SSO in Spruce. Learn more about Single Sign-On (SSO) management at Spruce.

How to Enable SSO with Okta (Web Browser 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. 

1. Navigate to Settings > Organization Preferences > Single Sign-On (SSO) Authentication
2. Click “Purchase SSO Add-On.” A dialog will appear on your screen. 
3. Check the checkbox to confirm you understand that your Spruce plan and monthly pricing will be adjusted. 
4. 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 Okta SSO 

To begin, log in to your Okta Admin Console and create an OIDC web application for Spruce. You must be a Super Administrator or Application Administrator in Okta in order to complete this process.

• Go to Okta Admin Console > Applications and Resources > Applications 

• Create App integration > under Sign-in Method, Choose OIDC - OpenID Connect
• Under Application Type > choose Web Application and tap Next. A New Web App Integration will be created. 

• Name your App Integration. 
• Under Grant Type > Core grants > Ensure that Refresh Token is selected. 
  • This is important because the refresh token will allow Okta teammates to securely log in to Spruce with Okta. If this is not checked, teammates will not be able to log in to Spruce. 

• Go to Sign-in redirect URIs > enter the following URL: https://app.sprucehealth.com/sso/callback

• Go to the last section, Assignments > Controlled Access. 
  • If you'd like all your teammates in Okta to be able to use Spruce, select "Allow everyone in your organization to access".
  • If you only want select Okta groups to access Spruce, select "Limit access to selected groups". 

• Under the same section, Assignments > Enable immediate access > check Enable Immediate Access with Federation Broker Mode. Then tap Save. 

• Once set up is complete, your Spruce app integration will be created in Okta. You will now be able to find your Okta client ID, client secret, and issuer URI that will need to be copy/pasted into Spruce. 
  • Your Client ID is located under > Client Credentials. 
  • Your Client Secret is located under the Client Secrets section. 
  • Your issuer URI is located in the upper right corner by tapping your name in the dropdown. It will be the link underneath your email. (ex: yourcompany.okta.com)

Next, return to Spruce to complete Okta SSO set up. 

You must be an Administrator in Spruce to complete SSO set up, and your Spruce account email must match the email from the Okta account that you’d like to connect to.

1. In Spruce, go to Settings > Organization Preferences > Single Sign-On (SSO) Authentication
2. Tap Connect next to Okta to be taken to the Okta SSO page where you can begin the connection process. 

Begin Step 1 > Enter your Okta organization information

• Note - you must follow the above steps and create an OIDC app integration within your Okta Admin Console before proceeding. 
• Enter your Client ID. 
  • This is the client ID of the Okta application you have created for Spruce in your Okta Admin Console.
• Enter your Client Secret. 
  • This is the client secret of the Okta application. Spruce stores it securely and never displays it again.
• Enter your Issuer URI. 
  • This is the OIDC issuer URI of your Okta organization. (ex: yourcompany.okta.com).

Continue with Step 1 > Authenticate with Okta SSO 

• Tap Save and Log in to Okta. 
  • You must log in using the same email from Okta that you’d like to connect to Spruce. 
  • The domain of your Okta 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 Okta 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 Okta 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 Okta 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 Okta email, and will authenticate through Okta. 
• 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.

Important: Teammates must be invited to Spruce. Spruce does not support automatic provisioning with Okta. Admins must still manually invite teammates to Spruce.
 

Editing Your Client Secret

After connecting Okta SSO, you will have the ability to edit your Okta Client Secret in Spruce, if needed. The Client Secret is a secure credential that allows Spruce to authenticate its connection with Okta. Updating your Okta Client Secret will not disable SSO or change how your teammates sign in.

Before updating your Okta Client Secret in Spruce, you will need to retrieve the new Client Secret from Okta. You can find your Client Secret in the Okta Admin Console on the app page that you created for Spruce. 

To update your Client Secret in Spruce:

1. In Spruce, go to Settings > Organization Preferences > Single Sign-On (SSO) Authentication.
2. On the Connected SSO Provider card, select Edit Client Secret. The dialog will display the last four characters of your current Client Secret.
3. Enter the new Client Secret from Okta and select Save.
4. 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.

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 Okta SSO setup process again.

Automatic Teammate Suspension in Spruce

Automatic Teammate Suspension ensures that teammate access is securely synced between Okta and Spruce. When enabled, deactivating a teammate in Okta automatically suspends their account in Spruce. 

Important: Teammates must be specifically deactivated in Okta for this automatic suspension in Spruce to function. If teammates are only suspended in Okta, they will not be suspended in Spruce. 

When a teammate is deactivated in Okta:

• 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 Okta 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 Okta to support this functionality. The Okta OIDC app that was created for enabling the Spruce SSO connection will not support this. 

• Go to Okta Admin Console > Applications and Resources > Create App Integration 

• Select SWA > Secure Web Application 

• Name the app "Spruce Health SCIM" or something distinctive from the other Spruce app integration. 
• For the app login page URL > enter https://app.sprucehealth.com 
• Select Finish, and the application will be created. 

• Next, configure the application. Go to the General tab > App Settings. 
• Tap Edit and change the Provisioning setting to SCIM, and tap Save. 

• Go to the Provisioning tab > SCIM Connection. Tap the Edit button and update the SCIM connector base URL to: https://auth-api.sprucehealth.com/scim/v2 
• Under Unique identifier fields for users > enter "email"
• Under Supported provisioning actions > select "Import New Users and Profile Updates" and "Push Profile Updates" 
• Under Authentication Mode > select HTTP Header. 
• Next, under the HTTP Header > Authorization section, copy and paste the SCIM token from Spruce into this field. 
• Next, tap Test Connector Configuration. This will ensure that the connection is successful. Then, tap Save on this page. 

• Under the Provisioning tab > Settings > To App, tap Edit next to Provisioning to App and Select Deactivate Users. Then tap Save. 

• The final step is to add all applicable Okta users to this SCIM application. Go to the Assignments tab > Tap the Assign dropdown, and select who you would like to add to the SCIM application. This should include all teammates that will be using Spruce. 
  • Each new user in Okta will need to be added to the SCIM application in order to support automatic teammate suspension. Please note: Teammates must successfully create a Spruce account before being added to the SCIM app in Okta. 

If you have generated an error in Okta (“An error occurred while assigning this app”), when attempting to add a teammate:

• The teammate will need to create their account in Spruce first
• Then, you will need to open the Okta Admin Console and go to Dashboard > Tasks. 
• Click the “Edit Assignment” button, then click the “Saved Assignment” button, and then “Try Again”. This should successfully add the teammate to the SCIM app and support automatic teammate suspension. 
   

Restoring Teammates with SSO

Restoring a teammate in Okta 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 Okta, they will not be able to log in to Spruce until they are also restored in Okta. 

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
   

Okta SSO FAQs

See here for General SSO FAQs
 

Can teammates join automatically with our Okta domain?

No, teammates must be manually invited through Spruce.
 

Does Spruce automatically create teammate accounts from Okta?

No, Spruce does not support automatic provisioning with Okta at this time.
 

Does deactivating a teammate from Okta automatically remove them from Spruce?

If you have enabled Automatic Teammate Suspension with Spruce and Okta, then removing a teammate from Okta 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 Okta 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 Okta automatically remove them from Spruce?

No. Even if Automatic Teammate Suspension is set up with Okta, Okta teammates must specifically be deactivated in Okta in order to automatically suspend their account in Spruce. If an Okta teammate is only suspended in Okta, their account will remain active in Spruce and they will still be able to log in.
 

Does adding a teammate back to Okta automatically give them access to Spruce again?

No. Restoring a teammate in Okta 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 Okta email address. 
 

Will enabling Okta SSO overwrite the name/title/display name of an existing Spruce account? 

No. It will only pull this information from Okta for new Spruce accounts.
 

How does changing/updating an email address in Okta affect the same Spruce account using SSO? 

If a Spruce teammate’s email address is changed in Okta, they will not be able to log in. Contact Spruce support to have this information updated.