Configuring Single Sign-On as User Authentication Type

This article explains how to configure a portal for the Single Sign-On authentication type for admins assigned with the portal management role. To learn more about SAML SSO in general, go to the article: About SSO.

To get to the configuration settings module:

• Go to the Settings section in the admin website
• Go to the Portal Management module
• Select the portal you want to configure or create a new portal

You are now on the portal management dashboard. From here:

• Select User Authentication from the menu on the left
• Click on the Single Sign-On option
• Select the Configure settings link

Configuring the Portal for SSO

The following steps must be taken to configure a portal for SSO:

• Download the metadata
• Add an Encryption Certificate
• Add a Signing Certificate
• Set the Field Mappings
• Single Logout (SLO) Settings

Downloading Metadata

The metadata is an X.509 file that contains the public key and the following configuration parameters: 

• Assertion Consumer Service (ACS) URL--this is the single sign-on endpoint
• The Single Logout (SLO) URL
• The Entity ID--this is a unique name that identifies the SP

Adding an Encryption Certificate

(Although certificates can be created in the SAML configuration tool, the best procedure is to create, manage, and delete certificates in the Certificate Manager in the Settings section.)

Select the "ADD CERTIFICATE" button and a box appears which allows you to either select an existing encryption certificate or create a new one:

If you do not have an existing certificate, select "Create new certificate" and a new box will appear in which you can enter a name for the certificate and then select "ADD CERTIFICATE."

You can assign two encryption certificates to a single portal.

Follow the same procedure in the next section for the Signing Certificates. 

Set Field Mappings

You can view the entire list of available member attributes and related details in the "Field Mapping: Attributes and Values List" article.

User related data that clients use to identify and authenticate members is organized in fields that have specific names. Configuring fields (aka "field mapping") is the process of aligning, or matching, client field names with the corresponding Engagement Rx field names. If you want to learn more about what field mapping is, see this article. 

In the field mapping input tool on the admin, the column titled "System Name" represents the naming conventions for Engagement Rx and the column titled "Assertion Attribute Name" represents the client's naming conventions. You will need to fill in only the fields that are in use for your company. 

Note that portals using SSO have the capability of embedding the Engagement Rx portal into the client website and/or mobile app, which is a process that requires field mapping. The entire list of system fields appears when you select the drop-down in the "System Name" box:

After selecting a field, you will need to fill in the "Assertion Attribute" box to map the naming convention your company uses with the Engagement Rx naming convention:

Select each of the fields that you want to map with their corresponding Assertion Attribute names. Note that PortalGroup and Key Field must be used in SAML SSO configuration. 

Single Logout (SLO) Settings

You have the option to enable single logout (SLO) when using SSO SAML 2.0 as your authentication method. When SLO is enabled, end-users who log out of the client system trigger a process that will automatically log them out of the SP system. 

Engagement Rx currently supports IdP-initiated SLO: this requires the IdP (the client) to provide the SP (Engagement Rx) with a URL called the "IdP SLO Endpoint." 

SSO Failures

The SSO failure handling process gracefully handles soft failures and informs clients of hard failures. You can see a full list of both failure types here.

Soft Failures

A soft failure occurs when something fails but the user should be allowed to proceed anyway, e.g. receive an incorrect birth date for a user. In this situation, the system removes the birth date data as if it was never received. For a returning user, this has no UI or system implication. For a new user, the birth date field would be blank on the portal registration page. At which point, Engagement Rx would collect the user's birth date.

Hard Failures

A hard failure occurs when something fails, and the user should not be able to proceed, e.g. authentication fails due to an invalid signature. The system displays an authentication error message along with a code representing the specific failure condition.