Single Sign-On Configurations

Single Sign-On (SSO) can be configured as an optional—or enforced—authentication method for an organization’s users to log in to the VIP Dashboard.

Note

Only an identity provider (IdP) that supports Security Assertion Markup Language (SAML) can be configured for SSO in the VIP Dashboard.

Configuring SSO requires setting updates to be made in both the organization’s Single Sign-On panel in the VIP Dashboard as well in the account settings of the organization’s selected identity provider (IdP).

The required steps for configuring SSO are outlined in 3 separate tabs located on the Single Sign-On panel of the VIP Dashboard.

Identity Provider Data: Select the identity provider (IdP) that will be used for an organization’s SSO. Values that are required by the IdP’s account settings can be retrieved from this panel.
Service Provider Configuration: Values that are required by VIP to configure SSO for an organization can be retrieved from the IdP and pasted into the corresponding fields in this tab.
Email Domains: Add all email domains with which an organization’s IdP will allow users to log in to the VIP Dashboard.

Caution

Once SSO is enabled, the first time any user logs in to an organization’s VIP Dashboard with SSO their Org role will default to an Org guest role. This is true for new users granted access to the VIP Dashboard for the first time by being added to the IdP, as well as existing users who previously accessed the VIP Dashboard with non-SSO authentication methods. After logging in with SSO for the first time, the user will temporarily be unable to access any or the organization’s applications until an Org admin edits the user’s role and assigns them the correct Org role and App role.

Add or edit an SSO configuration

A user can leave the Single Sign-On panel and return later in order to complete all of the required steps for configuring SSO for an organization. A user must select the button labeled “Save Changes” in order for any added values or settings to persist between sessions.

To add a new SSO Configuration: Select the button labeled “Add Configuration” located in the upper right hand corner of the panel.
To edit an existing SSO Configuration: Select the link labeled “Edit” located in the column labeled “Actions”.

Identity Provider Data

The fields and values generated in this tab are provided for the purpose of configuring the identity provider (IdP) chosen by the organization.

Identity Provider (IdP) Settings

Select an IdP to be used for this SSO configuration:

In the section titled “Identity Provider (IdP) Settings”, select the name of the IdP for this configuration from the dropdown labeled “Provider Name“.
The value that appears in the field labeled “Configuration Name” is a read-only unique identifier generated automatically by VIP.
Select the button labeled “Save Changes“.

Assertion Encryption

To optionally enable encryption for Security Assertion Markup Language (SAML) assertions, an encryption certificate must be generated by VIP and submitted to the organization’s IdP.

Activate Assertion Encryption by enabling the toggle labeled “Encrypt SAML Assertions“.
Copy the generated encryption certificate by selecting the button labeled “Copy Encryption Certificate” or download the certificate as file by selecting the button labeled “Download Encryption Certificate (.crt)“.

As long as the SAML assertion encryption is successfully configured with the IdP, the “Assertion Encryption” setting in the VIP Dashboard must remain enabled. Disabling this setting in the VIP Dashboard will invalidate the encryption certificate and potentially break the IdP configuration.

SSO URL and Entity ID

Provide the IdP with the generated setting values:

Single Sign-On URL: An endpoint URL where the IdP sends a SAML response back to the service provider (VIP) after authenticating a user. An IdP might also refer to this endpoint as the Assertion Consumer Service (ACS) URL.
Service Provider Entity ID: A globally unique name for the service provider (VIP) that enables the IdP to recognize the VIP entity.

Mapping User Attributes

In order for VIP to create user records for users who log in to the VIP Dashboard with an SSO method, the IdP must send attribute values mapped to known keys.

The schemas (e.g. https://schemas.wpvip.com/email) listed below for each attribute are the values that should be mapped in the IdP’s settings. For example, the correct value to add to the IdP’s settings for sending the user’s email address should be https://schemas.wpvip.com/email, not email.

Attribute	Schema	Value
Email	`https://schemas.wpvip.com/email`	The user’s primary email address
Full name	`https://schemas.wpvip.com/name`	The user’s full name
First name	`https://schemas.wpvip.com/firstname`	The user’s first name; only necessary if no “Full name” record exists.
Last name	`https://schemas.wpvip.com/lastname`	The user’s last name; only necessary if no “Full name” record exists.

Export All IdP Settings

As an alternative to copying setting values individually, export all setting values displayed in this tab in a single file in the “Export All IdP Settings” section located at the base of the tab. The settings can be exported as a *.txt or an *.xml file by selecting either the button labeled “Generate .txt File” or “Generate .xml File“.

Service Provider Configuration

Required values that are generated by the IdP and must be added to the following fields:

Identity Provider Single Sign-On URL (SAML 2.0 Endpoint): An endpoint URL where the service provider (VIP) sends SAML requests to the IdP when a user attempts to log in.
Identity Provider Issuer (IdP Identifier): A value that is supplied by the IdP that allows it to verify that it is a trusted partner.
Signing Certificate (X.509 Certificate): Upload or paste the X. 509 certificate supplied by the IdP. The X. 509 certificate enables VIP to verify the authenticity of SAML responses from the IdP.

Save the values entered in all fields by selecting the button labeled “Save Changes“.

Email Domains

All email domains that have been added to the IdP and are expected to be used by an organization’s users to log in to the VIP Dashboard must be added to this field.

When adding more than one email domain, each domain must be entered on a separate line.

For example, to allow a group of users with an @example.com email address and a group of users with an @other-example.com email address, an organization would add the following domain values to the field labeled “Company Email Domains“:

example.com
other-example.com

After adding email domains to the field labeled “Company Email Domain(s)“, save the value(s) by selecting the button labeled “Save Domains“.

Status

The status of the completeness of an SSO configuration can be reviewed in the tab labeled “Status“. Remaining actions that are required for an SSO configuration to be complete and “Active” are listed under the label “Configuration Details“.

Incomplete: An SSO configuration has been created and some settings have been completed, but the IdP and the service provider are not yet able to connect.
Ready for login test: Settings are complete and the IdP and the service provider are able to connect. To verify that the SSO configuration is working as expected, a user with a profile added to the IdP must log in to the VIP Dashboard with SSO.
Active: The SSO configuration is complete, tested, and ready to be used by all users in an organization to log in to the VIP Dashboard.

Last updated: January 19, 2024