Configure Okta for Coveo SSO

This is for:

System Administrator

Okta is a service providing single sign-on (SSO) for web and mobile applications.

As a Coveo administrator, you can implement Security Assertion Markup Language (SAML) 2.0 SSO when your company uses Okta. 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 Okta session.

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

Note

If you’re not the Okta administrator at your company, contact them so that they configure Okta using the following steps. If you want to encrypt Okta assertions, you must provide this person with the Coveo public certificate as well.

Configure Okta

Both Okta and Coveo must be configured to work together and provide a SAML SSO service to your Coveo users. First configure Okta so that it can provide Coveo with user authentication data.

  1. Log in to your Okta Developer account.

  2. In the navigation menu, select Applications > Applications.

  3. Depending on your use case, determine whether you can use the pre-configured application or need to create an application manually:

Coveo Pre-Configured Application

  1. In your Okta Developer account, on the Application page, click Browse App Catalog.

  2. Search for and click Coveo Cloud.

  3. On the Coveo Cloud page, click Add.

  4. On the Add Coveo Cloud page, consider editing the General Settings, and then click Done.

  5. In the Assignments tab, use the Assign menu to assign your Coveo application to users or groups.

  6. Optionally, import your Okta groups into Coveo to access them from the Edit a Group subpage.

    This allows you to add Okta users to your Coveo organization in groups rather than individually.

    Note

    Only groups in which your Okta account is included are available on the Edit a Group subpage; as an administrator, you may therefore want to be a member of all groups.

  7. Enter an attribute statement regarding your user groups to import into Coveo:

    1. On your Okta application page, select the Sign On tab.

    2. Next to Settings, click Edit.

    3. In the user.groups box, enter an attribute.

      Note

      If you need to enter more than one expression, create an application manually instead of using the pre-configured one.

    4. Click Save.

  8. Retrieve data to import.

Manual Application Configuration

  1. In your Okta Developer account, on the Application page, click Create App Integration to configure your application manually.

  2. In the Create a new app integration dialog, select SAML 2.0, and then click Next.

  3. On the Create SAML Integration page, in the App name box, enter an application name to display in your Applications page.

  4. Select the Do not display application icon to users checkbox, and then click Next.

  5. In the Single sign-on 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://platformhipaa.cloud.coveo.com/saml/SSO.

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

  6. In the Audience URI (SP Entity ID) 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.

  7. Leave the Default RelayState box empty and the Name ID Format dropdown menu on Unspecified.

  8. In the Application username dropdown menu, select the kind of username you want to send through the assertion.

  9. Click Show Advanced Settings, and then make sure that the Response is Signed.

  10. Under Attribute Statements, fill the boxes using the following table values (see Okta Expression Language).

    Name Name format Value

    user.email

    Unspecified

    user.email

  11. If you want to add additional statements, click Add Another.

    Note

    All optional attributes should be in Unspecified format.
    Example

    You could choose to add the following rules:

    Name Name format Value

    user.firstName

    Unspecified

    user.firstName

    user.lastName

    Unspecified

    user.lastName

  12. If you want to import your Okta groups into Coveo, under Group Attribute Statements, enter an attribute statement regarding your user groups.

    Note

    Importing your Okta groups into Coveo allows you to associate several Okta users to a Coveo group. If you don’t import your Okta groups, you must add your Okta users to your Coveo organization one by one (see Manage Members).

    The Filter parameter allows you to specify which Okta groups must be imported into Coveo. Associate an operator (Starts with, Equals, Contains, or Matches regex) with a string.

    If you want to add additional group statements, click Add Another.

    Examples

    • The following statement makes all Okta groups available for importation into Coveo.

      Name Name format Filter

      user.groups

      Unspecified

      Matches regex .*

    • The following statement makes the Human Resources Department, Engineering Department, and Sales Department groups available for importation, but not the Engineering Interns and Okta Administrators groups.

      Name Name format Filter

      user.groups

      Unspecified

      Contains Department

    • The following statements make only the Support Agents, Software Developers, and User Interface Designers groups available for importation. Any other group is unavailable.

      Name Name format Filter

      user.groups

      Unspecified

      Equals Support Agents

      user.groups

      Unspecified

      Equals Software Developers

      user.groups

      Unspecified

      Starts with User

  13. Click Next and complete the application creation wizard.

Prepare to Configure Coveo

Once you’ve configured Okta so that it passes user authentication information to Coveo, you must configure Coveo to enable federation between Coveo and Okta. To do so, you must assign your Okta users and/or groups to your Coveo application, and then retrieve the data required to configure Coveo.

Assign Application to Users

You must assign your application to the Okta users you want to allow to log in to Coveo using Okta SSO, including yourself.

  1. On the Applications Okta page, click Assign Users to App.

  2. On the Assign Applications page:

    1. Under Applications, check the application you just created.

    2. Under People, check the box next to the users you want to allow to log in to Coveo using Okta SSO.

    3. Click Next.

    4. Review your application assignments, and then click Confirm Assignments.

Alternatively, see Assign Applications to users.

Assign Application to Groups

You may want to import your Okta groups into Coveo and access them from the Edit a Group subpage. This allows you to add Okta users to your Coveo organization in groups rather than individually.

Note

Only groups in which your Okta account is included are available on the Edit a Group subpage; as an administrator, you may therefore want to be a member of all groups.

  1. On the Applications Okta page, click the application you just created.

  2. In the Assignments tab, click the Assign dropdown menu, and then click Assign to Groups.

  3. In the dialog that appears, click Assign for each group you want to import into Coveo, and then click Done.

Alternatively, see Assigning a single app to groups.

Retrieve Data to Import

  1. On the Applications Okta page, click the application you just created (see Configure Okta).

  2. Select the Sign On tab.

  3. Under Sign on methods, click View Setup Instructions.

    This opens a page displaying the data required to configure Coveo.

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 may also be 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 may also be 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 Okta Assertions

Assertion encryption is optional. To encrypt Okta assertions, you must retrieve the Coveo public certificate and import it into your Okta configuration.

  1. On the Settings page, in the Single Sign-On tab, under Advanced Option, download the Coveo certificate.

  2. Back on your Okta application page, select the General tab.

  3. In the SAML Settings box, click Edit.

  4. Click Next.

  5. Under General, click Show Advanced Settings.

  6. In the Assertion Encryption dropdown menu, select Encrypted.

  7. Next to Encryption Certificate, click Browse files, and the select the Coveo certificate.

  8. Click Next, and then complete the wizard.

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 or User Groups

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.