Healthy Roster’s Single Sign-On(SSO) features currently will function with most OAuth2-based Identity Providers(IdP). With OAuth2, we leverage the Authorization Code grant flow, which will include the following steps:

1. A user visits https://dashboard.healthyroster.com/Account/IdpLogin and is prompted to enter their email address.
2. The user enters their email address, and the system will look up the authentication information associated to their account.
3. The user will be redirected to the login page for their configured Identity Provider (IdP).
4. The user will authenticate using whatever means is required by their IdP.
5. The Identity Provider will redirect the user back to Healthy Roster, including an authorization code indicating the user has successfully authenticated.
6. The Healthy Roster system will submit the authorization code to the IdP in exchange for an identity token and access token.
7. The Healthy Roster system will validate the token and the supplied user account are valid, active accounts. If so, the login process will complete, and the user will be allowed access to the Healthy Roster system.

Important Considerations

Here are some important considerations when exploring the viability of SSO with your Healthy Roster usage.

First, Healthy Roster leverages this SSO process only for user authentication, not authorization. User roles, permissions, and feature access are managed within the Healthy Roster platform. These user accounts must first be provisioned within the Healthy Roster system.

Second, accounts must share the same email address between both the Healthy Roster system and the IdP.

Configuration

To support Single Sign On, customers will be required to configure their IdP to as an OAuth2-based Identity Provider. NOTE: Healthy Roster does not support SAML-based configuration at this time.

Your IdP configuration should include the following:

1. The Redirect URI for a successful login should be:
   1. Production: https://dashboard.healthyroster.com/account/idplogin
   2. Testing / Sandbox: https://dashboard-demo.healthyroster.com/account/idplogin
   3. Note! For some systems, the URI is case-sensitive.
2. The inclusion of an email claim for the user is required.
3. Note! If you choose to restrict authentication requests for specific browser types, you must permit the following for mobile access:
   1. iOS: User-Agent: Mozilla/5.0 (iPhone; CPU iPhone OS 12_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148

For Healthy Roster to complete SSO configuration for your account, we will require the following information:

1. The Client ID to user when making requests to your IdP
2. The Shared Secret to use when making requests to your IdP
3. The authorize and token URI endpoints to your IdP
   1. Example: https://sso.mydomain.com/adfs/oauth2/authorize
   2. Example: https://sso.mydomain.com/adfs/oauth2/token

Guidance and Configuration - Domain

In order to configure SSO for Non-Provider users, an account must first complete SSO configuration for your account. This will enable SSO for provider users and establish the proper IdP configuration to use for non-provider users.

To configure SSO for Non-Provider users, configuration of a managed domain is required. Managed domains (such as acme.org, or mydomain.co ) will be used to identify which users should be directed to use SSO. This method will require the use of email addresses (usernames) that match any configured domains on the account.

When configuring a managed domain, Healthy Roster must validate domain ownership. Successful validation will require the addition of a TXT record associated to your domain with a value unique to your account. A user with administrative access to your Healthy Roster account will be able to retrieve this unique value. To add this record, you will likely require assistance from an IT resource with access to your domain registrar and permissions to add DNS records.

Multiple domains may be registered with your account, provided ownership is properly validated via the process above.

STEPS TO ACTIVATING DOMAIN SPECIFIC SINGLE SIGN-ON

1. A Provider Administrator will log into Healthy Roster using SSO
2. Navigate to Admin Settings (left gear icon located on the home page)
3. Select the "Providers" (top most tab located under "Administrator") 

4. Click the shield icon (located next to the “Add” button) 

5. Click the “ADD” under Managed Domains
6. Your specific unique will be populated in the dialog. This value of the TXT record.  

7.  Add your domain in the text box provided (format example: healthyroster.com)
8. Click “OK”

FAQ

What information do I need to activate Single Sign-On for non-provider users?

You will likely need to involve your IT to configure SSO. Your organization will need verifiable domain ownership and the corresponding TXT record. For reference, “domain” generally means the end of your email address, such as @healthyroster.com.

How does it work if I’ve already invited users?

If a non-provider user already has an account where their email address matches the domain, they will be able to start using SSO as soon as the domain is verified.

How does it work when I invite users?

Users will create a Healthy Roster account the same way any new user would by creating a password. Once their account is created, the next time they log in, they will be directed to SSO login.

If we deactivate SSO, will our users lose access to Healthy Roster?

If the domain is removed, users will instead use their password to login.