Covered by this topic
The following instructions provide users with the necessary procedural details to enable single sign-on (SSO) via SAML
For more information on login trust terminology, see our SSO Documentation .
WebChart _** and SAML Metadata
Beginning with RC201906, WebChart can natively import and export SAML metadata files commonly used for setup between IDPs and SPs. Older systems can utilize the Manually Creating the Login Trust from SAML Metadata instructions found below. The first step is an exchange of metadata files. The Login Trusts editor under Control Panel → SuperUser is the access point for importing and exporting these files.
The information used to populate a new login trust is found in the IDP’s SAML metadata file from the client. The client should provide a copy of this file to the WebChart Implementation Specialist. This file may be in the form of an internet URL, email attached file, or a block of text shared with the Specialist. For additional client requirements information, see our SAML-based SSO documentation .
WebChart _** -Provided Metadata
WebChart is able to publish it’s SAML SP metadata in three ways: an Internet URL, a file download which may be emailed to the client or block of text which may be copy/pasted in communications to the client.
Once this metadata has been shared with them, most IDPs will then share their metadata with us.
The IDP metadata file will be imported into the WebChart system via the Import Metadata link in the Login Trusts editor.
The relevant data will be extracted from the metadata file and displayed in the Add Login Trust screen, as described below in Login Trust Fields.
Verify the information and then click the Submit button at the bottom.
The SAML IDP will now be available on the system’s Login page under the Remote Log In heading.
Once an SSO connection has been configured and tested, the login page can now be disabled. This is accomplished by making an SSO server the system Default authentication mechanism. In the listing of the Login Trusts editor, there is an option for “Make Default”. This link is used to disable the login page and direct all authentication requests to that specific SSO server.
The WebChart Add Login Trust screen displays the following options:
The following list provides details and insight on using the fields available on the Add Login Trust screen: Domain – Required Field: URL for single sign-on service domain.
- Found in the SAML metadata file with label entityID.
- This string must be alphanumeric and no more than 255 characters in length. Description – Required Field: Text description of login trust.
- May be displayed to users at certain points during the login/logout process, and should be user-friendly.
- This string must be no more than 255 characters in length. Allowed Options: Selected checkboxes will change the behavior of the SSO system. The following options are available:
- Make this Domain active: Required for the MIE SSO method.
- Allow a(n otherwise) successfully processed login ticket to re-activate login-disabled users: Reactivates an inactive WebChart user when that user attempts to log in via the employer SSO system.
- Allow creation of new users from (otherwise) successfully processed login ticket: Creates a new
user when that person attempts to log in via the employer SSO system.
- XML Login Tickets or SAML assertions are recommended for use with this option.
- Allow this domain to be used for OpenID authentication: Processes OpenID SSO requests. Required for use with OpenID.
- Pass current page’s CGI variables to the login_url when re-authenticating: When a login session expires, the main window directs the user through the SSO server. If unchecked, expired sessions create a pop-up window to re-establish a valid user session.
- The SSO server (IDP) must support this option.
- Only allow translated users to login: Requires all login requests to reference a known username via translation. Login requests which do not have a translation to an established
username will be rejected. This is generally used in conjunction with a periodic user import process or HR feed.
- This option allows the WC system to dictate which users have access through SSO.
- Users may be, but need not be, translated: Translation allows lookup of the IDP-specified username against a lookup table. This allows the IDP and the WebChart system to use a different identifier (username) for a user.
- Allow SAML requests from this domain: Indicates that SAML requests (assertions) are allowed from the listed domain.
- Use |System| initiated SAML instead of server initiated: Utilize SP-initiated bindings instead of IDP-initiated.
- Close the window on logout: For IDPs that log the user into WebChart using a pop-up window; this closes that window once their session ends.
- Remove the question mark ( ? ) character from the target resource: For IDPs that require state variables be passed as part of the URL instead of as CGI variables to the URL. This is not common.
- Put a link to the domain on the login page: The login page will have a list of links to these IDPs, in addition to the standard non-SSO login form.
- Use RelayState instead of TargetResource in SAML requests: Some IDPs require a RelayState variable instead of a TargetResource variable.
- Use Shibboleth specific ‘target’ instead of TargetResource in SAML Requests: Use with Shibboleth systems. Login URL: The URL that users are redirected to for obtaining a new session when they do not have one, or when an existing session becomes invalid.
- If this URL forwards any additional CGI variables sent to it, make sure the Pass current page’s CGI Variables option is checked. This will present a more seamless experience to the user.
The following instructions account for a system that is Shibboleth IDP-initiated, so be sure to adjust configuration, accordingly for other solutions. To create a login trust for SSO:
Open the SAML metadata file provided by the client.
Log into the system.
Navigate to the Control Panel on the left side menu.
Click the Login Trusts tab.
Click the Add Login Trust link, in the top-right of the page.
In the received metadata file, search for entityID, to locate the Domain.
Enter that URL into the Domain field.
Enter the appropriate client information into the Description field.
Select the Allow SAML requests from this domain checkbox.
Select the Use Shibboleth specific target instead of TargetResource in SAML Requests checkbox. Skip this step if not a Shibboleth system.
Search the metadata file for IDPSSODescriptor, to find the remainder of the information necessary to populate the login trust form.
Sections after the heading AttributeAuthorityDescriptor, if present, can be collapsed by clicking the chevron in front of it. All information collected for the WC login trust (aside from the domain) appears under the heading IDPSSODescriptor.
In the metadata file, search for SingleSignOnService, to locate the login URL. The URL should indicate what type of SSO is used (in this case, IDP-initiated).
There may be multiple options for <strong>SingleSignOnService</strong>. It is important to pick the correct one. In most cases, and in this example, the link that includes the HTTP-redirect is correct.