CareValidate ADA SSO Guide

This document explains how to configure an external Identity Provider (IdP) to work with CareValidate Single Sign-On (SSO)

CareValidate supports, and strongly recommends, that our clients implement SSO integration with our ADA application. This provides the most secure way for users to authenticate into the ADA platform.

Supported SSO protocols

The two protocols supported are OpenID Connect (OIDC) and SAML 2.0, although not across all platforms, as outlined in the table below.

In order to experience ADA on all platforms (web + mobile), OIDC is the recommended protocol.

Environments available

By default, SSO is configured in the production environment, however CareValidate also offers a “staging” environment that can be used for testing purposes before going “live”. Separate integrations are needed in order to configure both environments.

To set up SSO, regardless of the IdP or protocol used, the only piece of information needed from CareValidate is the authentication callback URI, which differs by environment:

Azure Application Registration

The steps below illustrate how to create an OpenID Connect SSO integration for ADA in Azure.

Create a new app registration

In the list of Azure services, search for “App Registrations” and click that option.

On the next screen, click "+ New registration"

For Name, enter “ADA” (recommended). Select the Supported Account Types. Usually this will be Accounts in this Directory Only (Single Tenant). For Redirect URI, select Single-page application (SPA). Then enter the auth URI for the environment being set up, from the table above. Then click the "Register" button to create the application.

Configure Authentication

In the newly created application, click on “Authentication” on the left hand side menu. Scroll down till you see “Implicit grant and hybrid flows”. Select both Access tokens and ID tokens checkboxes (ADA supports both Code Flow and Implicit Flow grant types). Access tokens are optional but ID tokens are required.

Under “Who can use this application or access this API?” select the first radio button (<Your Org Directory> only - Single tenant).

No Advanced settings are required. There is no logout URL available at the moment.

At the top of the page, click the Save button to save this configuration.

Configure Permissions

On the left side menu, Click API permissions. You should see the permissions list pre-populated with User.Read. This allows ADA to read the user profile information to get user data.

Above the list of permissions, click on “Grant Admin Consent for <Your Org Name>”, then click Yes to confirm the grant.

Note: This is an optional step. Performing this step ensures a smoother user experience by not prompting each individual user to give permissions to the ADA app on sign in.

Share Identifiers with CareValidate

At this point your application is configured. To complete the SSO integration, please copy the following two GUIDs from the Overview page of the application and send these to CareValidate:

• Application (client) ID
• Directory (tenant) ID

In addition to the SSO identifiers above, CareValidate will need to know what email domain(s) will be registered with this IdP. The process of setting up the SSO mapping is very quick.

Sign-in

At this point your SSO integration with CareValidate is complete. In order to test the integration, browse to https://accommodations.carevalidate.com/ and log in with your Azure managed email account for your domain. Note: signing into ADA is Service Provider (SP) rather than IdP initiated.

Note: the “Use Phone Number” button is for phone-based authentication, which is not handled by your IdP.

Advanced Setup

Code Flow

If you prefer to set the grant type to Code Flow, rather than Implicit Flow, an additional piece of information is needed for the SSO setup: a client secret. On the left side menu, click on Certificates & secrets, then click “+ New client secret”. In the pop-up that opens, create the secret and then share it with CareValidate.

Configure OpenId scopes

To configure OpenID scopes to CareValidate via SSO, those scopes need to be added to the list of permissions in place of the "User.Read" generic permission.Click on API permissions again, then click “+ Add a permission”.

From the list that opens, choose “Microsoft Graph”, then “Delegated permissions”. You will immediately see a list of standard OpenID scopes (permissions) that can be configured. The “openId” and “email” scopes are required in order to sign users in, and the “profile” scope can also be configured to send additional fields from the user"s profile to ADA.

Once the scopes are added to API permissions, you must grant admin consent in the same way as described earlier for “User.Read”.

Send optional claims via the user token

You can configure optional claims to be included in the authentication token, in order to send information from the users" profiles to ADA. For example you might want to send a country or region code, address, preferred name, etc.

To configure optional claims, click on “Token configuration” on the left side menu, then click “+ Add optional claim”.

On the modal that opens, choose “ID” for Token type, then from the list of checkboxes that opens, choose all claims that you wish to transmit to ADA. Those fields will be mapped to the users" profiles in the ADA platform. Note that the list is provided by Azure based on the token type, and not every piece of information about a user may be added to a token.

Okta Application Registration

To use Okta as an IdP for SSO integration with CareValidate, you can follow this guide.

Create an OIDC app in Okta

On the “Getting Started with Okta” page, under the “Use SSO” heading you will see a button to Add App, click it and then at the top of the next page click “Create New App”. On the following screen, choose OIDC as the sign-in method, then choose SPA on the screen that displays below, then click Next.

On the page titled “New Single-Page App Integration” select the following options:

• For Sign-in redirect URI enter the URI corresponding to the environment being set up (see table on the first page of this document)
• Skip Sign-out URI and Trusted Origins
• For Assignments, if your entire organization’s user population will access ADA, select “Allow everyone in your organization to access”. On the other hand, if only a specific subset of your employees need to be given access to ADA, then you will need to create a user group, then select the option “Limit access to selected groups” and enter the name of the group(s) to allow access to

After clicking Save, you will land on the application page. Under the “General” tab, in the section titled “Client Credentials”, you will see the client ID for the newly created application. Provide this Client ID to CareValidate.

In the section titled “General Settings” you will see a field called “Okta domain”. On the CareValidate side, we call this the Issuer URL. Provide this URL to CareValidate.

On the “Okta API Scopes” tab, there will be a list of consents under “Any”. Scroll down to “okta.users.read” and click Grant to allow the standard oidc scopes to be passed to ADA. Additional claims could be passed if needed, but at the very least the one above is required.

Congratulations, your Okta SSO integration with ADA is complete!

Advanced Setup

To set up additional profile fields to send to ADA via SSO token claims, on the left side navigation bar expand Directory, then choose Profile Editor. Under the Users tab, click on the Apps link, which will list the registered application(s).

Next to the app name there is a link called “Mappings”, click it and it will open a rather large modal which maps Okta user properties to fields that are transmitted to ADA through ID tokens. These profile fields are configurable in Okta and can be mapped to optional claims as needed. When finished, click “Save Mappings” at the bottom of the modal.

Configuring optional claims allows you to pass profile information to ADA which will be mapped to similarly named fields, as well as custom fields that can be configured on demand. For example, employee ID is a popular field to be passed, or address fields for the purpose of shipping COVID tests directly to your employees.

To add attributes to the Okta user profile, click on the “All” or “Okta” filter on the previous screen, and click “User (default)” next to the Okta widget.

That brings up a page where all currently defined attributes in Okta reside, and clicking on

“+ Add Attribute” allows you to define custom fields associated with your users" profiles.

Ping Application Registration

To use Ping One as an IdP for SSO integration with CareValidate, you can follow this guide.

Create an OIDC app in Ping

Once inside PingOne, select the Connections tab on the left side navigation bar, then select Applications. Click on the big “Plus” button at the top to create a new application. Select the card labeled “Single Page App” and click “Configure”. Give the app a name (ADA) and optionally a description and a logo (CareValidate can provide a logo file on demand). On the next screen configure the redirect URL for the environment desired (see table on the first page of this document). Then click “Save and Continue”.

On the next screen add the scopes that you want transmitted to ADA. There are 4 openid scopes pre-defined and a bunch of PingOne API scopes. At a minimum, include the “profile” scope, but you can include additional ones at this time as well, such as illustrated below. Save and Continue.

On the next screen you will need to map OIDC attributes. The sub attribute is required and it should map to a User ID. For authentication in ADA you will also need to send email and name. This is also a great time to add custom attributes which will be included in the user token as claims. Ping has a predefined list of attributes that can be added and mapped to claims. When done adding attributes, click “Save and Close”.

At this point, the application will be created and a side window will open to allow further configuration. Under the “Profile” tab inside that window there will be the Client ID for this app. Provide this field to CareValidate.

On the tab titles “Configuration” you will see a list or URLs. The last one, typically named Issuer, is the URL you will need to provide to CareValidate as well. The format is https://auth.pingone.com/<UUID>/as

On the same tab there is a collapsed list titled “General”. Expand it and you will see the Client ID again, as well as a Client Secret. If you would prefer that the SSO grant type be Code Flow rather than Implicit Flow (default), provide the secret to CareValidate as well.

The Resources tab reveals the openid scopes granted. The AttributeMappings tab will show the attributes mapped earlier, and the list can be edited here if needed.

You are almost done. By default, the newly created application is disabled. Toggle the switch at the top of the window to enable the app, and you are ready to login from the ADA side!

Create a SAML app in Ping

To create a SAML SSO integration to ADA in Ping, start on the Connections tab in the main navigation, then on the application type selection screen choose “Advanced Configuration”. In the popup that opens choose SAML instead of OIDC (default).

On the next screen set the app name, click next and then you will need to configure the SAML metadata manually. CareValidate does NOT provide a metadata file, or a URL, for SAML SSO integration.

For ACS URLS, enter the authentication URL from the table at the beginning of this document. For Entity ID, you can use the URL of the ADA app based on the environment being set up:

http://accommodations.carevalidate.com (production)

This is basically a unique identifier for the application. The other fields on this page are either default values provided by Ping, or specific to your organization. Leave “SLO Binding” set to HTTP Post and “Signing” set to Assertion..

You will need to import a certificate for encryption. A default certificate is usually provided by Ping and can be located under the “Certificates and KeyPairs” section of the Connections tab. Import a certificate then Save and Continue.

The last configuration screen is for setting the value of the “saml_subject” attribute. This attribute MUST be mapped to the email address of the user, otherwise logging into ADA will not be possible via SAML! Click “Save and Close”.

On the Configuration tab of the application settings window you will see a field called Issuer ID. Provide this value to CareValidate (we typically call it Entity ID).

On the same tab there will be a “Single Signon Service” value, an URL that typically has the format https://auth.pingone.com/<UUID>/saml20/idp/sso which also needs to be provided to CareValidate.

Finally, click on “Download Signing Certificate” and send the entire certificate to CareValidate. Note that the certificate will look similar to this:

-----BEGIN CERTIFICATE-----

MIIDejNJAmKgAwIBAgIGAX47Yg35MA0BVSqGSIb3DQEBCwUAMH4xCzAJBgNVBAYT

……………………………

-----END CERTIFICATE-----

Make sure that the beginning and end of certificate marks above are included.

Additional attributes

On the Attribute Mappings tab, you can optionally configure additional attributes to be sent to CareValidate. An example is illustrated below.

Congratulations! Your SAML SSO integration with CareValidate is complete!