Configure OneLogin for Coveo SSO

This is for:

System Administrator

OneLogin is a service providing single sign-on (SSO) for web applications.

As a Coveo administrator, you can implement Security Assertion Markup Language (SAML) 2.0 SSO when your company uses OneLogin. Users can then log in to Coveo without having to provide their authentication credentials since their identity has previously been validated when logging in to their OneLogin session.

To allow users to log in via SAML SSO, Coveo must be able to trust and rely on OneLogin to authenticate users wanting to log in. To establish this trust relationship, you must configure OneLogin and Coveo so that both parties can exchange authentication information.

Note

If you’re not the OneLogin administrator at your company, contact them so they can configure OneLogin using the following steps.

If you want to encrypt OneLogin assertions, you will also have to provide the Coveo public certificate to this person.

Configure OneLogin

Both OneLogin and Coveo must be configured to work together and provide a SAML SSO service to your Coveo users.

First configure OneLogin so that it can provide Coveo with user authentication data.

  1. Log in to your OneLogin developer account.

  2. In the Apps dropdown menu, select Add Apps.

  3. In the search box, type connector.

  4. If you want to encrypt the assertions, select SAML Test Connector (IdP w/ encrypt). Otherwise, select SAML Test Connector (IdP w/ attr w/ signed response).

  5. In the Display name box, you can change the application name.

  6. Click Save.

  7. Select the Configuration tab.

  8. In the Audience box, enter one of the following:

    • For a regular (non-HIPAA) organization or an organization with data residency outside the US: https://platform.cloud.coveo.com/saml/metadata.

    • For a HIPAA organization: https://platformhipaa.cloud.coveo.com/saml/metadata.

  9. In the Recipient box, enter one of the following:

    • For a regular (non-HIPAA) organization: https://platform.cloud.coveo.com/saml/SSO.

    • For a HIPAA organization: https://platformhipaa.cloud.coveo.com/saml/SSO.

    • For an organization with data residency outside the US: https://platform-<REGION_ABBREVIATION>.cloud.coveo.com/saml/SSO.

  10. In the ACS URL Validator box, enter one of the following:

    • For a regular (non-HIPAA) organization: https://platform.cloud.coveo.com/saml/SSO.

    • For a HIPAA organization: https://platformhipaa.cloud.coveo.com/saml/SSO.

    • For an organization with data residency outside the US: https://platform-<REGION_ABBREVIATION>.cloud.coveo.com/saml/SSO.

  11. In the ACS URL box, enter one of the following:

    • For a regular (non-HIPAA) organization: https://platform.cloud.coveo.com/saml/SSO.

    • For a HIPAA organization: https://platformhippa.cloud.coveo.com/saml/SSO.

    • For an organization with data residency outside the US: https://platform-<REGION_ABBREVIATION>.cloud.coveo.com/saml/SSO.

  12. In the Parameters tab, click Add parameter.

  13. In the New Field dialog, create a field:

    1. In the Field name box, enter user.email.

    2. Select the Include in SAML assertion checkbox.

    3. Click Save.

  14. Back in the parameter list, click the field you just created.

  15. In the Edit Field User.Email dialog, in the Value dropdown menu, select Email, and then click Save.

  16. If you want to add optional parameters, repeat steps 12 to 15.

    Example

    You could choose to add the following rules:

    Field Name Value Include in SAML Assertion

    user.firstName

    Given Name

    check

    user.lastName

    Surname

    check

    user.groups

    Group

    check

  17. Click Save.

Prepare to Configure Coveo

Once you’ve configured OneLogin so that it passes the right information about user authentication to Coveo, you must configure Coveo to enable federation between Coveo and OneLogin. To do so, you need to retrieve data to later import into Coveo.

  1. Access your application configuration console, if not already done:

    1. Log in to your OneLogin developer account.

    2. In the Apps dropdown menu, select Company Apps.

    3. Click the app you just created.

  2. Select the SSO tab.

    This tab displays the data required to configure Coveo.

    Note

    In the Coveo interface, fill the Single sign-on URL box with the SAML 2.0 Endpoint link provided in the OneLogin SSO tab.

  3. Under X.509 Certificate, click View Details to display or download the OneLogin public certificate.

  4. Assign your OneLogin users to your application:

    1. Click Users, and then All users.

    2. Click a user.

    3. Click Applications.

    4. Click the plus sign (+).

    5. Select your application, and then click Continue.

    6. In the dialog that appears, click Cancel.

    7. Repeat the procedure for every application user.

Configure Coveo

Once you’ve configured your identity provider to provide Coveo with user authentication data, you must configure Coveo to trust your identity provider and accept to rely on it for user authentication.

  1. With the data required to fill the Coveo configuration form in hand, access the Settings page:

    1. Log in to Coveo (platform-ca | platform-eu | platform-au) as a member of a group with the required privileges to manage settings in the target Coveo organization.

    2. On the Settings page, select the Organization tab, and then select the Single Sign-On subtab.

  2. In the Single Sign-On subtab, in the Identity provider name box, enter the identity provider name as you want it to appear on your Coveo organization login page.

  3. In the Single sign-on URL box, enter the URL where Coveo must send an authentication request. The SSO URL is also called Assertion Consumer Service (ACS).

  4. In the Identity provider issuer URI box, enter the identity provider issuer unique URI. The identity provider issuer URI is also called entity ID or federation service identifier.

  5. Using one of the following methods, provide Coveo with the identity provider’s Base64 public certificate to validate the identity provider signature:

    • Paste the certificate in the Enter your public certificate box.

    • If you saved the certificate on your computer, click Choose File to browse your files and upload the certificate.

  6. Click Add.

Note

If you encounter a SAML Authentication Error while logging in to the hosted search page, it’s typically because the SSO configuration has not been updated prior to the scheduled rotation of the certificate. To resolve this issue, the Coveo administrator can update the certificate on the Settings page of the Coveo Administration Console.

To avoid this error, a Coveo administrator can add a notification as a reminder to update the certificate prior to the rotation date.

Encrypt OneLogin Assertions

Assertion encryption is optional.

To encrypt OneLogin assertions, you must have set up a SAML Test Connector (IdP w/ encrypt) application. You must then retrieve the Coveo public certificate and import it into your OneLogin configuration.

  1. On the Settings (platform-ca | platform-eu | platform-au) page, in the Organization tab, under Single Sign-On, download the Coveo certificate.

  2. Access your application configuration console, if not already done:

    1. Log in to your OneLogin developer account.

    2. In the Apps dropdown menu, select Company Apps.

    3. Click the app you just created.

  3. Select the Configuration tab.

  4. Under SAML Encryption, in the Public key box, paste the Coveo public certificate.

  5. Click Save.

Test Your Configuration

  1. Add your email address as an organization member. In the Add a Member dialog, under Provider, ensure to select Single sign-on.

  2. Log out of the Coveo Administration Console, and then log back in using the SSO option and your identity provider account. By doing so, you ensure Coveo and your identity provider work together properly.

    Important

    We strongly recommend that you don’t delete the account with which you first logged in to the Administration Console and implemented SAML SSO. This original account is a "backdoor" that prevents you from being locked out if the SAML SSO doesn’t work as expected. At any time, you can log in with your original, non-SSO identity provider, and then edit the Coveo configuration. For details on how accounts belonging to the same individual are separated, see Multiple Accounts.

    Alternatively, if you must delete your original account, you can also create another non-SSO administrator account with the required privileges beforehand. Logging in via email is also an alternative.

Invite SSO Users

Once you have verified that your SSO configuration works, invite SSO users to join your Coveo organization.

Important

Once you set up an SSO for your organization, users accessing a hosted search page of this organization are automatically redirected to the SSO login page. Therefore, after configuring your SSO, promptly invite your users as SSO users of this organization. Otherwise, users will enter their identity provider credentials, but access to the hosted search page won’t be allowed since there will be no Coveo SSO user corresponding to the provided credentials.