Skip to main content

Introduction to Single Sign-On (SSO)

Single Sign-On (SSO) controls access to multiple related but independent software systems. It enables the user to log in to the corporate network once and gain access to all systems without being prompted to log in again by each of them. For further general information on SSO, consult the Wikipedia article on Single Sign-on.

The Chrome River system supports SSO by means of SAML, a standards-based method that facilitates the exchange of authentication messages contained in XML documents between the Identity Provider (IdP) or Service Provider (SP) and user. Authentication gives the user access to multiple software portals outside of an organization’s intranet access point without requiring repeated logins.

Currently, Chrome River provides IdP- and SP-initiated SAML service, including SAML versions 1.1 and 2.0. For SAML 2.0, we also support encryption of the IdP assertion in SAML Authentication Response, with the provision of an X.509 certificate. The ability to encrypt the IdP assertion resolves the vulnerability posed by unauthorized users impersonating an authorized user if the IdP assertion message is intercepted. For further information on SAML 2.0 in general, consult the Wikipedia article Wikipedia article SAML 2.0.

Configuring SSO with Chrome River

Step 1: Open a Support Case

To get started using a SAML authentication service for Chrome River, please submit a Chrome River Help Desk request. Please be sure to include the below as part of your request:

  • Identity Provider Name (e.g., Okta, Microsoft ADFS, OneLogin, Azure Active Directory)

  • SSO Metadata from Identity Provider

  • The metadata is commonly provided as an XML file within your identity provider settings.

  • At minimum, metadata must include the X.509 Certificate and IdP SAML Redirect URL.

Step 2: Validate Firewall Settings

In your Chrome River Help Desk case, you may request the Production and, if applicable, QA/UAT hostnames from which Chrome River messages will originate. Please ensure that your organization’s firewall allows them access.

Step 3: Complete Configuration Within Identity Provider Settings

1. In the identity provider server, establish a connection to the Chrome River system. Your Chrome River Help Desk contact will provide you with the below information:

  • Entity ID

  • Assertion Consumer Service (Reply URL)

2. Add an authentication attribute: Email, Unique ID, or User Name.

3. Ensure the newly created SSO app is assigned to the relevant users.

Additional Configuration Details for Common Identity Providers

Microsoft Azure Active Directory (AD)

  • Create a new custom SSO app using the Azure AD setup guide.

  • Identifier (Entity ID) and Reply URL (values will be provided by Chrome River).

  • For user Attributes & Claims: The selected attribute value must match the emailAddress, unique employeeID, or userName within your users’ Chrome River profiles.

  • For example, if you choose “user.userprincipalname,” this value must match either the email address, unique employee ID, or user name in Chrome River.

Microsoft Active Directory Federation Services (ADFS)

  • Create a new custom SAML SSO app.

  • Fill in Relying Party Identifiers (values will be provided by Chrome River).

  • Add SAML Assertion Consumer Endpoints (values will be provided by Chrome River).

  • Add Claim rules: Send user attribute as NameID (Outgoing type).

  • Ensure the selected attribute value in your Claim Rules matches the emailAddress, unique employeeID, or userName within your users’ Chrome River profiles.

  • For example, email within ADFS = Email within Chrome River.

Okta

  • Set up a new custom SAML app.

  • Fill in the ACS URL and Entity ID (values will be provided by Chrome River).

  • Specify the NameID format (either EmailAddress or unspecified).

  • Ensure that the selected attribute value matches the emailAddress, unique employeeID, or userName within your users’ Chrome River profiles.

  • For example, email within Okta = email within Chrome River.

OneLogin

  • Set up a new custom SAML app.

  • Add the CustomerID, Location, and Environment (values will be provided by Chrome River).

  • Specify attribute parameters, e.g., NameID (unspecified).

  • Ensure that the selected attribute value matches the emailAddress, unique employeeID, or userName within your users’ Chrome River profiles.

  • For example: Email within OneLogin = Email within Chrome River.

Workspace ONE

  • Create a new SAML SSO app.

  • Specify Single Sign-On URL, Recipient URL, and Application ID (values will be provided by Chrome River).

  • Advanced Properties: Include Assertion Signature = Yes.

  • Sign Assertion = No

  • Sign Response = Yes

  • Ensure that the selected attribute value matches the emailAddress, unique employeeID, or userName within your users’ Chrome River profiles.

Shibboleth

  • Create a new SAML SSO app.

  • Add Entity ID and ACS URL (values will be provided by Chrome River).

  • Specify that the NameID value should match CR Profile.

  • Ensure that the selected NameID attribute value matches the emailAddress, unique employeeID, or userName within your users’ Chrome River profiles.

  • For example, EmployeeID within Shibboleth = UniqueID within Chrome River.

  • Please provide the authentication factor for NameID.

  • For example, urn:oid:0.9.2342.19200300.100.1.3 (this is not needed if NameID format is unspecified).

Testing and Validation Steps

1. Confirm User Account Setup

  1. Validate that the users who will be testing SSO have accounts in both Chrome River and your identity provider.

  2. Ensure that within your identity provider settings, the newly configured Chrome River SSO app is assigned to the users who will be testing it.

2. Request SSO Connection Be Enabled for Validation Testing

After you complete the configuration steps, contact Chrome River via your original SSO case in the Help Desk to request that the SSO connection be enabled for testing.

When the SSO connection is enabled for testing, the manual Chrome River login screen will remain functional to ensure current users’ access is not affected.

Note: The SSO test connection is automatically disabled after a few days.

If the testing window elapses before you can validate the setup, reach out to Chrome River via your SSO Help Desk case to have the test connection re-enabled.

3. Validate the Configuration by Testing with SSO Login Link

Have your test users follow an SSO login URL for the Chrome River application in their desktop browsers. The SSO login URL is different from the generic URL that directs users to the manual Chrome River login page.

SSO can be tested with either of two login links:

  • For IdP-Initiated SSO, you can use the login URL provided by your identity provider. Depending on your identity provider, this option might be displayed on an intranet dashboard with your other SaaS applications.

  • For SP-initiated SSO, Chrome River will provide you with a special SSO login URL.

Note: A desktop browser should be used when validating the SSO configuration

The SSO connection is considered valid if your test users are successfully launched into the Chrome River application after clicking the SSO login link.

Validating SSO on desktop should ensure that SSO will also function on iOS and Android, as the underlying authentication protocol and the servers involved are the same.

4. Request Full Activation of SSO and Final Wrap-Up

After validating that your test users can successfully authenticate into Chrome River via SSO, please notify Chrome River via your Help Desk case to begin coordinating the SSO activation for your organization.

Please note that once SSO is fully activated:

  1. The manual Chrome River login screen will become disabled and all login requests will be handled exclusively through SSO authentication.

  2. The same SSO login URL that was used during validation and testing can be used by your users to log into Chrome River via SSO.

  3. Your users will need to uninstall and reinstall the Chrome River mobile app on their devices (iOS and Android).

Chrome River can toggle SSO on and off as needed. Assuming that the configuration has been previously tested and validated, activating and deactivating SSO should not require changes to the underlying setup.

Please reach out via the Chrome River Help Desk with any SSO activation or deactivation requests.

“Incorrect UserID, CompanyID, or Password” Error Message

After users click the SSO login URL, a Chrome River login screen appears with the error message “Incorrect UserID, CompanyID or Password.”

Cause 1: Matching User Could Not Be Found in Chrome River

1. Ensure that the person has a user account in Chrome River and it is set to “Active” or “Pending.”

2. Confirm that your identity provider is configured to transmit an attribute that matches the emailAddress, unique employeeID, or userName within Chrome River.

  • If the email address includes foreign characters or letters with accents, try using the employeeID instead, if possible.

  • A configuration change at Chrome River might be needed to support authentication by userName. Please let us know if you are transmitting this value so that Chrome River can update its configuration accordingly.

3. Ensure that only a single attribute is transmitted by the identity provider.

  • Only one of the following is needed: emailAddress, unique employeeID, or userName that matches that of the Chrome River user profile.

  • The NameID field can be used for any of the three options.

Cause 2: Certificate Mismatch — "Access Restricted. User does not exist. Please contact your administrator to set up a Chrome River user account."

Update the X.509 certificate through the Chrome River Single Sign-On Admin Screen:

  1. Inside Chrome River, navigate to the Admin Settings and select SECURITY > SINGLE SIGN-ON.

  2. Scroll down to your security certificate and click UPDATE.

  3. Enter your X.509 certificate key.

  4. If there is a mismatch, please ensure that no line breaks or extra spaces are present.

  5. Click SAVE.

If you do not have access to this screen, one of your organization’s admin users can make the update for you. Alternatively, contact the Chrome River Help Desk and provide a current version of your SSO metadata XML file, which commonly includes the X.509 certificate.

Identity Provider Error

This type of error happens on a web page that is not hosted by Chrome River, i.e., a page hosted by your identity provider. When this happens, the URL in the address bar does not include “chromeriver.com.”

Cause 1: Incorrect Configuration Within Identity Provider Settings

  • Double-check that the ACS URL (redirect URL) and EntityID are set up as instructed.

  • Remove any spaces or slashes at the start or end of the above URLs.

  • Try to modify the EntityID or ReplyURL in your identity provider’s SSO settings using the URL shown in the error message.

  • In the example above, you would use http://www.chromeriver.com as the EntityID or ReplyURL.

  • Manually reconfigure the SSO app within your identity provider as a custom SAML SSO app instead of using a pre-built SSO template app.

Cause 2: Network Settings

  • Confirm any special network requirements with your IT team/systems administrator.

  • For example, your network might require a VPN or firewall permissions for SSO to function properly.

Cause 3: User Roles and Access

  • Make sure your users have been granted access to the Chrome River SSO application within your identity provider settings.

“System Error 500” Message

Cause: Invalid IdP URL

  • Open a Chrome River Help Desk case to double-check that the IdP URL configured within the Chrome River system is valid and starts with “http://”

“This site can’t be reached” Browser Error

Cause: Invalid SP-initiated Login URL

Certificate Authentication for the Chrome River Mobile App

The Chrome River app supports certificate-based authentication, which allows users to authenticate with your SSO and into the Chrome River app using an Identity Provider (IdP) or Service Provider (SP) certificate provided by your Mobile Device Management (MDM) instead of entering their SSO credentials.

Your organization will need to work with your MDM and IdP or SP to

  1. Install an IdP or SP certificate on users' devices.

  2. Configure your IdP or SP to accept the certificate via a web browser.

Once these two criteria are met, users will be able to log in to the Chrome River app via certificate.

SSO for the Chrome River Mobile App

Once you have set up SSO for Chrome River following the steps above, you may set configure it for the Chrome River app.

SP vs. IdP

SP-initiated is the recommended way to implement SSO for the Chrome River mobile app. Only customers who configure SP-initiated access (or use non-SSO login) will be able to take advantage of the enhanced user experience and security of the Chrome River mobile app.

For customers with IDP-initiated mobile configuration, users' web session length will be identical to the one your organization has configured for Chrome River access via web browser. This means users will need to log in more frequently.

To switch your organization's configuration from IdP to SP, open a case in the Chrome River Help Desk.

For complete details on logging in to the Chrome River mobile app, click here.

Login and Session Length

The length of a user's session in the Chrome River mobile app depends on how your organization has configured access.

Standard Login or SP-initiated SSO

If your organization uses the standard Chrome River login or SP-initiated Single Sign-On (SSO) login for the Chrome River mobile app, users will remain logged in for at least 30 days. The session will be extended by 30 days every time they use the app, up to a maximum of 90 days.

If the app remains idle for 15 minutes, users will need to unlock it via biometrics or their devices' PIN, but they will not be required to log back in.

  • Note: Users who have no security method set up on their devices will not be able to remain logged in using the 30-day session because the device will not be considered secure. Users will be completely logged out after 15 minutes of inactivity.

IDP-Initiated SSO 

If your organization uses IDP-initiated SSO login, the session length on the Chrome River mobile app will be identical to the one your organization has set for Chrome River access via web browser. By default this is 1 hour, with a maximum configurable session length of 12 hours.

SSO for the Emburse Chrome River Mobile App

Once you have set up SSO for Chrome River following the steps above, you may set configure it for the Emburse Chrome River mobile app.

SP vs. IdP

SP-initiated is the recommended way to implement SSO for the Emburse Chrome River app, but your organization may be able to use an IDP-initiated mobile configuration. You will need to test whether your IDP initiated setup works with the Emburse Chrome River app during your implementation of SSO. If it does not work, your organization can set up an additional SP-initiated integration for the Emburse Chrome River app or use SP-initiated on both web and mobile.

For complete details on logging in to the Emburse Chrome River app, click here.

Login and Session Length

Users will remain logged in for at least 30 days. The session will be extended by 30 days every time they use the app, up to a maximum of 90 days.

If the app remains idle for 15 minutes, users will need to unlock it via biometrics or their devices' PIN, but they will not be required to log back in.

  • Note: Users who have no security method set up on their devices will not be able to remain logged in using the 30-day session because the device will not be considered secure. Users will be completely logged out after 15 minutes of inactivity.

Deauthorize a Departed User's Chrome River App or Emburse Chrome River App Session

If a user has an active mobile session but has left your organization, their mobile session will be terminated and they will be logged out as soon as their Chrome River Person record is updated to Deleted or Departed status via the People Admin Screen, Person data feed or Person API. See People Admin Screen for more details.

Was this article helpful?