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 Emburse Enterprise 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, Emburse Enterprise 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 Emburse Enterprise

Step 1: Open a Support Ticket

To get started using a SAML authentication service for Emburse Enterprise, please submit a Support ticket. 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 Support ticket, you may request the Production and, if applicable, QA/UAT hostnames from which Emburse Enterprise 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 Emburse Enterprise system. Your Support 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 Emburse Enterprise).

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

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

Microsoft Active Directory Federation Services (ADFS)

• Create a new custom SAML SSO app.

• Fill in Relying Party Identifiers (values will be provided by Emburse Enterprise).

• Add SAML Assertion Consumer Endpoints (values will be provided by Emburse Enterprise).

• 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’ Emburse Enterprise profiles.

• For example, email within ADFS = Email within Emburse Enterprise.

Okta

• Set up a new custom SAML app.

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

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

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

• For example, email within Okta = email within Emburse Enterprise.

OneLogin

• Set up a new custom SAML app.

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

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

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

• For example: Email within OneLogin = Email within Emburse Enterprise.

Workspace ONE

• Create a new SAML SSO app.

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

• 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’ Emburse Enterprise profiles.

Shibboleth

• Create a new SAML SSO app.

• Add Entity ID and ACS URL (values will be provided by Emburse Enterprise).

• 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’ Emburse Enterprise profiles.

• For example, EmployeeID within Shibboleth = UniqueID within Emburse Enterprise.

• 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 Emburse Enterprise and your identity provider.

2. Ensure that within your identity provider settings, the newly configured Emburse Enterprise 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 Emburse Enterprise via your original SSO support ticket to request that the SSO connection be enabled for testing.

When the SSO connection is enabled for testing, the manual Emburse Enterprise 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 Emburse Enterprise via your SSO support ticket 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 Emburse Enterprise application in their desktop browsers. The SSO login URL is different from the generic URL that directs users to the manual Emburse Enterprise 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, Emburse Enterprise 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 Emburse Enterprise 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 Emburse Enterprise via SSO, please notify Emburse Enterprise via your Support ticket to begin coordinating the SSO activation for your organization.

Please note that once SSO is fully activated:

• The manual Emburse Enterprise login screen will become disabled and all login requests will be handled exclusively through SSO authentication.
• The same SSO login URL that was used during validation and testing can be used by your users to log into Emburse Enterprise via SSO.
• Your users might need to log out and back in to the Emburse Enterprise mobile app on their devices (iOS and Android). The log in flow automatically updates with your SSO.
• Admins will be able to update your organization's SSO certificate via the Single Sign-On Admin Screen.

Emburse Enterprise 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 Support with any SSO activation or deactivation requests.

“Incorrect UserID, CompanyID, or Password” Error Message

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

Cause 1: Matching User Could Not Be Found in Emburse Enterprise

1. Ensure that the person has a user account in Emburse Enterprise 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 Emburse Enterprise.

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

• A configuration change at Emburse Enterprise might be needed to support authentication by userName. Please let us know if you are transmitting this value so that Emburse Enterprise 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 Emburse Enterprise 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 Emburse Enterprise user account."

Update the X.509 certificate through the Emburse Enterprise Single Sign-On Admin Screen:

1. Inside Emburse Enterprise, 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 Support 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 Emburse Enterprise, 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 Emburse Enterprise SSO application within your identity provider settings.

“System Error 500” Message

Cause: Invalid IdP URL

• Open a Support ticket to double-check that the IdP URL configured within the Emburse Enterprise system is valid and starts with “http://”

“This site can’t be reached” Browser Error

Cause: Invalid SP-initiated Login URL

• Open a Support ticket to double-check that the SP-initiated Login URL is valid.

Certificate Authentication for the Chrome River Mobile App

The legacy 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 Emburse Enterprise app via certificate.

SSO for the Chrome River Mobile App

Once you have set up SSO for Emburse Enterprise 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 Emburse Enterprise 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 Support ticket.

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 Emburse Enterprise 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.

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 Emburse Enterprise access via web browser. By default this is 1 hour, with a maximum configurable session length of 12 hours.

SSO for the Emburse Enterprise Mobile App

Once you have set up SSO for Emburse Enterprise following the steps above, you may set configure it for the Emburse Enterprise Mobile app. The app can read different SSO configurations and handle multiple IdPs. When a user enters their email address into Emburse Enterprise Mobile, they will be given a list of IdP domains to select from. Once the user selects a domain, the login page for that SSO/IdP will appear to allow the user to log in with their credentials.

SP vs. IdP

SP-initiated is the recommended way to implement SSO for Emburse Enterprise Mobile, 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 Emburse Enterprise Mobile during your implementation of SSO. If it does not work, your organization can set up an additional SP-initiated integration for Emburse Enterprise Mobile or use SP-initiated on both web and mobile.

For complete details on logging in to Emburse Enterprise Mobile, 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.

Email Authentication for Emburse Enterprise Mobile

Customers who have mobile device management policies that make it challenging for personal devices to log in to Emburse Enterprise Mobile via SSO may choose to have users log in using Email Authentication instead.

If you activate this for your organization, users will enter their email address and receive a One-Time Passcode (OTP) that they must enter into the mobile app in order to log in. Users remain logged in to Emburse Enterprise Mobile with all the receipt-capture capabilities for a 30- to 90-day session length similar to SSO login.

Note that Email Authentication must be enabled for all users at your organization; it is not possible to enable it for just certain users and allow other users to continue logging in via SSO. Additionally, users will only have access to receipt-capture-related features of Emburse Enterprise Mobile, not the features related to expense reporting, pre-approvals reporting, and approval capabilities that will be added to Emburse Enterprise Mobile in future releases.

If you are interested in taking advantage of this enhancement, please submit open a Support ticket.

Deauthorize a Departed User's Chrome River App or Emburse Enterprise Mobile 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 Emburse Enterprise 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.