TABLE OF CONTENTS

Overview

In this release, we added support for Single Sign-On (SSO) using the Security Assertion Markup Language (SAML) 2.0 protocol. Vendor organizations can now configure FedConnect to work with their identity provider (IdP) to enable SAML 2.0–based SSO. Throughout the remainder of this article, this is referred to simply as "SSO" or "new sign on feature."


This new sign on feature is in addition to the existing traditional FedConnect sign on (with a FedConnect user ID and password). This also means that there is now a concept of two sign in paths in FedConnect:

  1. The existing traditional sign in—using FedConnect credentials (user ID and password)
  2. The new SSO sign in—using credentials issued by your identity provider (IdP)


For both sign-in paths, FedConnect runs authentication checks to determine whether the user is a traditional sign in user or an SSO user. 


At that junction:

  • SSO users are redirected to their IdP
  • Traditional sign in users are prompted for their password


The system also checks that the SSO users who are in an inactive, pending, or rejected status are not redirected to their IdP, and therefore are not permitted to sign in. In this scenario, the Sign In page displays again, but the user must contact your organization's vendor administrator to determine the next course of action if they believe this to be an incorrect result.


SSO users are always prompted to authenticate via your IdP every time they attempt FedConnect sign in. If your organization's SAML certificate is invalid, SSO users are not permitted to sign in to FedConnect.


Whereas the existing traditional sign in is a secure sign in, the new SSO option provides additional security and a centralized authentication experience. There is some new required configuration that vendor administrators must perform for organizations that want to start using SSO for FedConnect.


"" Important

Your organization must choose which sign-in path to use. If they decide to enable SSO in FedConnect, then ALL users in your organization must use SSO. There is no concept of "split" or "mixed" sign in. The system does not support mixed sign in where some users have the traditional sign in and others have SSO. It is an everyone-on-traditional or everyone-on SSO choice.


The new SSO method requires that your organization uses an identity provider (IdP). An IdP is a secure service company that manages your employee sign ins on your behalf. The IdP checks user names and passwords and determines whether access should be permitted. Some examples of IdPs include (in no particular order, and with no implied endorsement or preference) Okta, Google Workspace, and Microsoft Entra ID (formerly Azure AD). When your company enables SSO in FedConnect, and after everything is correctly set up, upon attempting to sign in to FedConnect, your organization's users are automatically redirected to your IdP to sign in — so, FedConnect never sees or stores your password.


""Important

After SSO is enabled, configured, and officially up and running, your organization's users must contact your IdP—not FedConnect Customer Care—for help with sign-in issues.


For organizations that choose the SSO sign in method, if you are accustomed to the traditional FedConnect comfiguration, registration, and sign in, then you will see different workflows for:

  • SSO configuration (for vendor administrators)
  • User registration (for vendor administrators) 
  • Signing in (for all of your organization's users) 


This new SSO method can also be configured with a new certificate expiration alert for the required certificates. And we added a new sign in test tool to help vendor administrators troubleshoot potential issues with user sign in via the SSO method, before the point in the workflow when actual users are ready to sign in.


"" Important

For organizations that use SSO, passwords become irrelevant once SSO is activated (on). This is a feature, not a bug!



Once SSO is enabled for a vendor organization, that organization's user passwords are cleared from the FedConnect database. Your organization's users cannot sign in to FedConnect using their old traditional FedConnect user ID and password. Thereafter, any issues with sign in must be resolved with your IdP.


Vendor Administrator Changes

This section describes the changes that a vendor administrator will see if their organization has opted to use this new SSO version for their FedConnect sign in process. 


In this release there is now a new Single Sign On section on the existing Company Info page. The Single Sign On section includes several fields that display depending upon different SSO setup scenarios. The following is a list of all possible fields that can display in the Single Sign On section, depending upon setup on the Company Info page:

  • Enable Single Sign On for Users in My Company
  • Type
  • Description
  • IdP Entity ID
  • Login URL
  • Signing Certificate
  • Signing Certificate Thumbprint
  • Signing Certificate Expiration
  • Claim
  • Test SSO Login


In addition to those new fields and the new SSO setup features, the existing password reset feature has also changed. The new fields were listed in the bulleted list just above this paragraph. The new SSO setup is described in the section of this article titled Setting Up FedConnect SSO. The changes to password resetting are described in the section titled Password Reset. 


""Navigation

To access the Company Info page as a vendor administrator, follow these steps.

  1. Sign in to FedConnect. The Message Center - Inbox page displays.
  2. Click Company Profile. The Company Info page displays.


The following picture illustrates how the Company Info page might look after you select Yes in the Enable Single Sign On for Users in My Company field but before a certificate has been uploaded. Your results might vary.


New Single Sign On Section on Existing Company Info Page BEFORE Certificate Upload


The following picture illustrates how the Company Info page might look after you select Yes in the Enable Single Sign On for Users in My Company field and after a certificate has been uploaded. Your results might vary.


New Single Sign On Section on Existing Company Info Page AFTER Certificate Upload



Setting Up FedConnect SSO

This section describes what you need to do to set up the FedConnect SSO feature. There are some prerequisites to using the setup steps below. You must have an IdP. And your IdP must provide:

  • The IdP entity ID—a Uniform Resource Identifier (URI) value
  • A valid X.509 type certificate
  • The IdP SSO endpoint—a sign in Uniform Resource Locator (URL)


"" Important

The only valid certificate type is the X.509 certificate.


""Navigation

Use the steps below to set up your organization to use FedConnect SSO..

  1. Sign in to FedConnect. The Message Center - Inbox page displays.
  2. Click Company Profile. The Company Info page displays.
  3. Select Yes in the Enable Single Sign On for Users in My Company field. The Company Info page refreshes and the Single Sign On section expands to display more fields.
  4. The Type field is hard-coded to SAML 2.0.
  5. In the Description field, type up to 400 characters to add a clear, non-technical description of the principal purpose of the SSO configuration you are setting up. This is a required field.
  6. In the IdP Entity ID field, add the unique identifier (URI) provided to you by your IdP. This is a required field.
  7. In the Login URL field, type the IdP's sign on URL. This must be an HTTPS address.
  8. In the Signing Certificate field, click the Choose File button and navigate to and select the X.509 certificate from your IdP. All actions in the Signing Certificate field are required. The certificate must include a private key to be valid.
  9. Still in the Signing Certificate field, click the Upload Certificate button. Upon successful upload, the Signing Certificate Thumbprint and Signing Certificate Expiration fields display.
  10. Upon successful certificate upload, the Signing Certificate Thumbprint field is automatically filled with the unique has value (thumbprint) identifier from the digital certificate. This is used to verify sign in requests.
  11. Upon successful certificate upload, the Signing Certificate Expiration field is automatically filled with the the expiration date for the uploaded certificate. This value is extracted from the certificate is uploaded and is not editable.
  12. The Claim field is hard coded to Email Address and cannot be edited. FedConnect uses this value to match the email sent by your IdP.
  13. In the Test SSO Login field, click the Test button to verify that all of the settings (including the certificate you uploaded) were successfully configured in the Single Sign On section on the Company Info page. Upon successful testing, the message, "Connection to your IdP was successful and the assertion from your IdP was signed correctly," displays. If you do not see the successful testing confirmation message, this indicates that the test failed. A test failure message does not display.
  14. Click Continue. The Users page displays.



Repeat Testing

The test feature is coded with a positive confirmation for positive test results, but it does not display a negative test results message to indicate failure of the test. There are, however, field-level validations for each of the following fields:

  • The Description field to alert you that it is required
  • The IdP Entity ID field to alert you that it is required 
  • The IdP Entity ID field to let you know that the value you enter must be a URI
  • The Login URL field to alert you that it is required 
  • The Login URL field to let you know that the value you enter must be an HTTPS URL
  • The Signing Certificate field to alert you that it is required 


Repeat testing can be done, but if you want to re-test, you must first remove and then re-upload the certificate. The repeat testing steps look something like this:

  1. Click the Remove Certificate button in the Signing Certificate field the existing certificate.
  2. Click the Choose File button to upload the certificate again, and then click the Upload Certificate button.
  3. Click the Test button to re-run the test feature.


Certificate Removal and Replacement

After you have performed the initial setup and SSO is up and running and a certificate is in place, the Remove Certificate button displays in the Signing Certificate field. 


You may use this to remove a certificate in advance of its expiration date and replace it with the newer one. 



Certificate Expiration

After you successfully upload the certificate, it is added to the FedConnect certificate store. A scheduled job sends expiration warnings to all vendor administrators starting 30 days before the certificate expires. The remaining notifications are sent in intervals of 15, 10, 5, and 1 day.


In the unfortunate event that your certificate should expire, contact FedConnect Customer Care. A Unison representative must temporarily turn off the SAML SSO connection for you so that your vendor administrator can sign in and upload a new certification.


These actions are audited for accurate historical record keeping.



Password Reset

The password reset feature is now available ONLY for organizations that use the traditional FedConnect user ID and password sign in method. 


The Reset button is not available for SSO users because SSO users are not permitted to use the FedConnect password reset feature. SSO password reset must be done by your IdP. 


Likewise, the Forgot Password and Change Password options are not available for vendor administrator users or regular (non-vendor administrator) users.


All password reset features remain the same for traditional FedConnect sign in users (non-SSO users).


It is entirely by design that Unison administrators cannot reset SSO passwords, as the purpose of an IdP is to protect your organization and its users. In order to provide the highest level of security possible, such sensitive information must not be shared with anyone outside of your organization or the IdP.


New Sign In Process

Whether you use traditional FedConnect sign in, or SSO, everyone starts on the same Sign In page. To accommodate SSO it was necessary to update the existing Sign In workflow by hiding the Password field on the Sign In page until the user has entered their user ID. 


The following picture illustrates how the Sign In page looked for the old sign in workflow. Notice how it displays both the User ID field and the Password field. Your results might vary.


OLD Sign In Page



The following picture illustrates how the Sign In page might look now, for the new workflow. Notice that only the User ID field displays. This applies to both traditional sign in users and SSO users. Your results might vary.


NEW Sign In Page



This is how the updated sign in workflow goes:

  1. You type your user ID in the User ID field and click Sign In.
  • If you are a traditional FedConnect sign in user, then the Sign In page refreshes and the Password field displays, where you enter your password and click Sign In.
  • If you are an SSO user, then you are redirected to your IdP's for authentication, you enter your credentials there, and then you are signed in to FedConnect.



The following picture illustrates how the Sign In page might look now, for the new workflow. This applies only to traditional sign in users. Notice that now the User ID field is "greyed out" (not editable) and that the Password field displays. Your results might vary.


New Sign In Page Part 2


User Registration Process

For organizations that do not use SSO, there is no change to the registration process for the traditional FedConnect sign in method. New users associated with a vendor that is not configured for SSO will continue to register using the traditional FedConnect user ID and password method.



Possible Scenarios

Now that there is a choice between traditional FedConnect sign in and SSO, the vendor registration process and/or the configuration for your organization's choice of FedConnect sign in (including sign in choices for existing vendor organizations) can take one of three possible paths:

  • For new vendors when SSO is not yet configured—When a new vendor creates an account, SSO is, by default, disabled. Your organization must register as a vendor (which is described in Registering as a Vendor in the FedConnect online help). And your users must register using a FedConnect user ID and password. Upon official establishment of the account, vendor administrators will be able to update your organization's vendor record and enable the SSO feature. Users will then follow the sign-in described in this article.
  • Existing vendors that want to continue to use traditional FedConnect sign in—If your organization already has an account in FedConnect, and if you are already using the traditional sign in process and you add a new user, then you will follow the existing traditional user registration process (which is described in the "About the Add User Page" section on the Managing Your Company's Users page in the FedConnect online help). Each new user registration follows this process to obtain a FedConnect user ID and password.
  • Existing vendors that already use SSO—If your organization already uses an IdP and you already successfully use SSO to sign in on other platforms, then you're in luck, because half of the work has already been done (the part where you register with an IdP). After your organization has completed the process of officially switching over to the FedConnect SSO method, thereafter, the traditional FedConnect user ID and password method is no longer available for anyone associated with your organization. The Welcome to FedConnect email that FedConnect sends out to new users will reflect the SSO process and includes instructions specific to SSO.


System Email Messages

There are email messages that are sent automatically from FedConnect upon the various registration, activation, and password change/reset events. Going forward, now that SSO is an option, this is how those email messages will work:

  • SSO users will receive a new user activation email message.
  • SSO users will NOT receive the temporary password email message.
  • SSO users will receive a reactivation email message.


Traditional sign in users will continue to receive the temporary password email just as they did before this enhancement.

  • They will also still receive the activation email.
  • They will also still receive the new users email.


System Auditing

FedConnect stores audit logs for all of the following SSO and regular sign in actions:

  • When the Unison administrator turns off the SAML connection for any vendor
  • When SSO users sign in and sign out
  • When activation, inactivation, and rejection emails are sent to SSO users
  • When passwords are cleared from the database for SSO users
  • When SAML certificate expiration notices are sent
  • When SSO is enabled and disabled
  • When any of the SAML-related SSO field values are added or changed (edited)