Configuring Okta for Coveo Cloud SSO

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

As a Coveo Cloud administrator, you can implement Security Assertion Markup Language (SAML) 2.0 SSO when your company uses Okta (see Coveo Cloud V2 SAML SSO). Users can then log in to Coveo Cloud 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 Cloud 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 Cloud so that both parties can exchange authentication information.

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

Configure Okta

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

  1. Log in to your Okta Developer account.

  2. Click Admin.

  3. Ensure that you’re using the Classic UI by looking at the upper-left corner of the page. If Developer Console is visible, click it and select Classic UI.

  4. Click Applications.

  5. Click Add Application.

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

Coveo Cloud Pre-Configured Application

  1. On the Add Application page, in the application search bar, type Coveo Cloud, and then click Add to add a pre-configured application.

  2. On the Add Coveo Cloud page, under General Settings, optionally edit the Application label, and then click Next.

  3. In the Assignments tab, in the Assign menu, select Assign to People.

  4. In the dialog that opens, click the Assign button corresponding to a user you want to allow to log in to Coveo Cloud using Okta SSO.

  5. Validate the user’s User Name, and then click Save and Go Back.

  6. Repeat for all users to assign, and then click Done.

  7. (Optional) Import your Okta groups into Coveo Cloud 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.

    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. Assign your application to groups:

      1. On your Okta application page, in the Assignment tab, click the Assign drop-down menu, and then select Assign to Groups.

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

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

      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 (see Group Attribute Statements).

        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. Click Create New App to configure your application manually.

  2. In the Create a New Application Integration dialog:

    1. Leave the Platform drop-down menu on Web.

    2. Next to Sign on method, select SAML 2.0.

    3. Click Create.

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

    Coveo Cloud

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

  5. In the Single sign-on URL box, enter:

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

      OR

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

      OR

    • 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:

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

      OR

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

  7. Leave the Default RelayState box empty and the Name ID Format drop-down menu on Unspecified.

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

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

    Name Name Format Value
    user.email Unspecified user.email
  10. If you want to add additional statements, click Add Another.

    All optional attributes should be in Unspecified format.

    You could choose to add the following rules:

    Name Name Format Value
    user.firstName Unspecified user.firstName
    user.lastName Unspecified user.lastName
    user.emailAliases Unspecified user.emailAliases
  11. If you want to import your Okta groups into Coveo Cloud, under Group Attribute Statements, enter an attribute statement regarding your user groups.

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

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

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

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

      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
  12. Click Next and complete the application creation wizard.

Prepare to Configure Coveo Cloud

Once you have configured Okta so that it passes user authentication information to Coveo Cloud, you must configure Coveo Cloud to enable federation between Coveo Cloud 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 Cloud.

Assign Application to Users

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

  1. On the Applications Okta page, click Assign Applications.

  2. On the Assign Applications page:

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

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

    3. Click Next.

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

Alternatively, see Assigning Applications.

Assign Application to Groups

You may want to import your Okta groups into Coveo Cloud 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.

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. Select the Assignments tab.

  3. In the Assignments tab, click the Assign drop-down menu, and then click Assign to Groups.

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

Alternatively, see Assigning Applications by Group.

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 Cloud.

Configure Coveo Cloud

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

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

    1. Log in to the Coveo Platform as a member of a group with the required privileges to manage settings in the target Coveo organization, if not already done.

    2. In the Administration Console upper-right corner, click Settings.

    3. In the Settings panel, select the Organization tab, and then, in the left-hand pane, click Single Sign-On.

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

  3. In the Single sign-on URL box, enter the URL where Coveo Cloud must send an authentication request.

    The SSO URL is also called assertion consumer service (ACS).

  4. In the Identity provider issuer URL box, enter the identity provider issuer unique URL.

    The identity provider issuer URL is also called entity ID or federation service identifier, and must be unique across all platform organizations using SSO.

  5. Provide Coveo Cloud with the identity provider public certificate to validate the identity provider signature:

    • Paste the X.509 public certificate in the Public certificate box.

      OR

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

    The certificate must be Base64-encoded and may contain the -----BEGIN CERTIFICATE----- and ----END CERTIFICATE----- tags.

  6. Click Add.

  • 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 in the Settings panel of the Coveo Cloud 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 Cloud public certificate and import it into your Okta configuration.

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

  2. Back in 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 drop-down menu, select Encrypted.

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

  8. Click Next, and then complete the wizard.

Test Your Configuration

  1. Add your email address as an organization member (see Adding and Managing Members). In the Add a Member dialog, under Provider, ensure to select Single sign-on.

  2. Log out of Coveo Cloud, and then log in using SSO and your identity provider account. By doing so, you make sure Coveo Cloud and your identity provider work together smoothly.

    We strongly recommend that you do not delete the account with which you first logged in to Coveo Cloud and implemented SAML SSO. This original account is a “backdoor” that prevents you to be locked out if the SAML SSO doesn’t work as expected: at any time, you can log in via the regular, non-SSO login page, and then edit the Coveo Cloud configuration. Alternatively, if you must delete your original account, you can also create another non-SSO administrator account with the required privileges beforehand.

Invite SSO Users or User Groups

Once your have verified that your SSO configuration works, invite SSO users or user groups to your organization (see Adding and Managing Members and Import Members).

Once you setup a 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 Cloud SSO user corresponding to the provided credentials.

Recommended Articles