--- title: Configure Okta for Coveo SSO slug: '1602' canonical_url: https://docs.coveo.com/en/1602/ collection: manage-an-organization source_format: adoc --- # Configure Okta for Coveo SSO [Okta](https://www.okta.com/products/single-sign-on/) 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](https://docs.coveo.com/en/1979/) 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. This page explains how to proceed. To configure SSO in more than one Coveo organization, for example in a production organization and a [sandbox organization](https://docs.coveo.com/en/2959/), configure one of these organizations, and then follow [the instructions](#configure-sso-in-another-organization) at the end of this page. > **Note** > > If you're not the Okta administrator at your company, contact them so that they configure Okta using the following steps. > Provide them with the Coveo public certificate, which is needed to [encrypt assertions](#encrypt-okta-assertions). ## 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. . Log in to your [Okta Developer](https://developer.okta.com/) account. . In the navigation menu, select **Applications** > **Applications**. . Depending on your use case, determine whether you can use the pre-configured application or need to create an application manually: ** The [Coveo pre-configured application](https://docs.coveo.com/en/1602#coveo-pre-configured-application) doesn't allow assertion encryption, so you must [create an application manually](https://docs.coveo.com/en/1602#manual-application-configuration) to [encrypt assertions](https://docs.coveo.com/en/1979#assertion-encryption). ** To make only certain groups available for importation into Coveo, you can edit the [pre-configured application](https://docs.coveo.com/en/1602#coveo-pre-configured-application) to enter a single filtering expression. See [Group Attribute Statements](#Group_Attribute_Statements) for details. However, if you need to enter more than one expression, you must [create an application manually](https://docs.coveo.com/en/1602#manual-application-configuration). ### Coveo pre-configured application . In your [Okta Developer](https://developer.okta.com/) account, on the **Application** page, click **Browse App Catalog**. . Search for and click `Coveo Cloud`. . On the **Coveo Cloud** page, click **Add**. . On the **Add Coveo Cloud** page, consider editing the **General Settings**, and then click **Done**. . On the **Assignments** tab, use the **Assign** menu to assign your Coveo application to users or groups. . Optionally, [import your Okta groups](https://docs.coveo.com/en/1980#import-members) into Coveo to access them from the **Edit a Group** subpage. This allows you to add Okta users to your [Coveo organization](https://docs.coveo.com/en/185/) 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. . Enter an attribute statement regarding your user groups to [import into Coveo](https://docs.coveo.com/en/1980#import-members): .. On your Okta application page, select the **Sign On** tab. .. Next to **Settings**, click **Edit**. .. In the **user.groups** box, enter an [attribute](#Group_Attribute_Statements). > **Note** > > If you need to enter more than one expression, [create an application manually](#manual-application-configuration) instead of using the pre-configured one. .. Click **Save**. . [Retrieve data to import](#retrieve-data-to-import). ### Manual application configuration . In your [Okta Developer](https://developer.okta.com/) account, on the **Application** page, click **Create App Integration** to configure your application manually. . In the **Create a new app integration** dialog, select **SAML 2.0**, and then click **Next**. . On the **Create SAML Integration** page, in the **App name** box, enter an application name to display in your **Applications** page. . Select the **Do not display application icon to users** checkbox, and then click **Next**. . 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://docs.coveo.com/en/2976/): `+https://platform-.cloud.coveo.com/saml/SSO+`. . 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+`. . Leave the **Default RelayState** box empty and the **Name ID Format** dropdown menu on **Unspecified**. . In the **Application username** dropdown menu, select the kind of username you want to send through the assertion. . Click **Show Advanced Settings**, and then make sure that the **Response** is **Signed**. . Under **Attribute Statements**, fill the boxes using the following table values (see [Okta Expression Language](https://developer.okta.com/reference/okta_expression_language/)). |=== | Name | Name format | Value | `user.email` | Unspecified | `user.email` |=== . 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` |=== . [[Group_Attribute_Statements]]To [import your Okta groups](https://docs.coveo.com/en/1980#import-members) 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](https://docs.coveo.com/en/1821/)). 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. 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` |=== . 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 Assign your application to the Okta users you want to allow to log in to Coveo using Okta SSO, including yourself: . On the **Applications** Okta page, click **Assign Users to App**. . On the **Assign Applications** page: .. Under **Applications**, check the application you just created. .. Under **People**, check the box next to the users you want to allow to log in to Coveo using Okta SSO. .. Click **Next**. .. Review your application assignments, and then click **Confirm Assignments**. Alternatively, see [Assign Applications to users](https://help.okta.com/en/prod/Content/Topics/users-groups-profiles/usgp-assign-apps.htm). ### Assign application to groups You may want to [import your Okta groups](https://docs.coveo.com/en/1980#import-members) 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. . On the **Applications** Okta page, click the application you just created. . On the **Assignments** tab, click the **Assign** dropdown menu, and then click **Assign to Groups**. . 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](https://help.okta.com/en/prod/Content/Topics/users-groups-profiles/usgp-assign-app-group.htm). ### Retrieve data to import . On the **Applications** Okta page, click the application you just created (see [Configure Okta](#configure-okta)). . Select the **Sign On** tab. . 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. . With the [data required to fill the Coveo configuration form](#prepare-to-configure-coveo) in hand, access the **Settings** page: .. [Log in to Coveo](https://platform.cloud.coveo.com/login) ([platform-ca](https://platform-ca.cloud.coveo.com/login) | [platform-eu](https://platform-eu.cloud.coveo.com/login) | [platform-au](https://platform-au.cloud.coveo.com/login)) as a [member](https://docs.coveo.com/en/2869/) of a [group](https://docs.coveo.com/en/2867/) with the [required privileges](https://docs.coveo.com/en/1562#required-privileges) to manage settings in the target [Coveo organization](https://docs.coveo.com/en/185/). .. On the **Settings** page, select the **Organization** tab, and then select the **Single Sign-On** subtab. . 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](https://docs.coveo.com/en/1697/). . 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). . 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_. . 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. . 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**](https://docs.coveo.com/en/1562/) page of the [Coveo Administration Console](https://docs.coveo.com/en/183/). > > To avoid this error, a Coveo administrator can add a [notification](https://docs.coveo.com/en/1583#add-or-edit-an-organization-notification) as a reminder to update the certificate prior to the rotation date. ## Encrypt Okta assertions [Assertion encryption](https://docs.coveo.com/en/1979#assertion-encryption) is optional. To encrypt Okta assertions, retrieve the Coveo public certificate and import it into your Okta configuration: . On the **Settings** page, on the **Single Sign-On** tab, under **Advanced Option**, download the Coveo certificate. . Back on your Okta application page, select the **General** tab. . In the **SAML Settings** box, click **Edit**. . Click **Next**. . Under **General**, click **Show Advanced Settings**. . In the **Assertion Encryption** dropdown menu, select **Encrypted**. . Next to **Encryption Certificate**, click **Browse files**, and the select the Coveo certificate. . Click **Next**, and then complete the wizard. ## Test your configuration . [Add your email address as an organization member](https://docs.coveo.com/en/1821/). In the **Add a Member** dialog, under **Provider**, ensure to select **Single sign-on**. . [Log out of the Coveo Administration Console](https://docs.coveo.com/en/1841#user-menu), and then [log back in using the SSO option and your identity provider account](https://docs.coveo.com/en/1697#logging-in-with-sso). 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](https://docs.coveo.com/en/1697#multiple-accounts). > > Alternatively, if you must delete your original account, you can also create another non-SSO administrator account with the [required privileges](https://docs.coveo.com/en/1562#required-privileges) beforehand. > [Logging in via email](https://docs.coveo.com/en/1697#logging-in-with-email) is also an alternative. ## Invite SSO users or user groups Once you've verified that your SSO configuration works, [invite SSO users to join your Coveo organization](https://docs.coveo.com/en/1821/). > **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](https://docs.coveo.com/en/1697/). 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. ## Configure SSO in another organization If you have multiple Coveo organizations, such as a production organization and a [sandbox organization](https://docs.coveo.com/en/2959/), you must use the same SSO settings for all organizations. Users will then use the same SSO credentials to log in, regardless of the organization they are accessing. Follow these steps to configure SSO in additional organizations: . Ensure that the user identity you'll use to configure SSO: -- ** Is a [member](https://docs.coveo.com/en/2869/) of all [organizations](https://docs.coveo.com/en/185/) where the SSO configuration will be used, including the original organization where SSO is already configured. If it's not already a member, this user identity must be [invited](https://docs.coveo.com/en/1821#add-members) to the organizations and [accept the invitations](https://docs.coveo.com/en/1697#after-login). ** Has the [privilege](https://docs.coveo.com/en/228/) to edit SSO settings (**Edit** on the [**Single sign-on identity provider** domain](https://docs.coveo.com/en/1707#single-sign-on-identity-provider-domain)) in each of these organizations. -- . Using this identity, log in to the organization where you want to configure SSO. . In the [**Single Sign-On**](https://platform.cloud.coveo.com/admin/#/orgid/settings/organization/sso) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/settings/organization/sso) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/settings/organization/sso) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/settings/organization/sso)) tab of the **Settings** page, delete any existing SSO configuration. Save your change. This will also permanently delete the associated SSO members from your Coveo organization. . Copy the SSO settings from the first organization to the other. The SSO settings provided to Coveo must be identical across all organizations, including the identity provider name. > **Tip** > > Open the organization where SSO was originally configured in a private browser window. > This will let you copy and paste from one organization to the other without logging in and out to switch between them. . Follow the remainder of the deployment process above, starting at the assertion encryption step, for each organization where you copied the SSO settings.