Configure a custom SAML identity provider for Coveo SSO

This is for:

System Administrator

Coveo provides detailed instructions to implement single sign-on (SSO) in your Coveo organization using a variety of identity providers. However, configuring SSO with your preferred identity provider is also possible. Users can then log in to Coveo without having to provide their authentication credentials since your identity provider has validated their identity before.

To allow users to log in via SAML SSO, Coveo must be able to trust and rely on your identity provider to authenticate users wanting to log in. To establish this trust relationship, you must configure your identity provider 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, configure one of these organizations, and then follow the instructions at the end of this page.

Notes

  • Only the identity provider administrator at your company can configure the identity provider using this article. Provide them with the Coveo public certificate, which is needed to encrypt assertions.

  • Coveo supports HTTP POST binding only.

  • If you encounter implementation issues, contact the Coveo Support team for troubleshooting help.

Endpoints

Depending on the identity provider, the endpoints to provide may be named differently. The Typical endpoint names column of the following table lists the most frequent names used.

Typical endpoint names Addresses

  • Assertion Consumer Service (ACS) URL

  • POST Binding Endpoint

  • SSO URL

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

  • Recipient URL

  • Reply URL

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

  • Audience URI

  • Entity ID

  • Identifier URL

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

Assertion settings

Coveo SAML SSO requires assertions with the following settings.

Subject

The NameID is a required setting and must be a permanent identifier unique to each user.

<saml2:Subject>
    <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">your-unique-nameid</saml2:NameID>
</saml2:Subject>

user.email attribute

The user.email attribute is a required setting that provides Coveo with user email addresses. Coveo can then associate the email address of authenticated users to item permissions indexed by your sources. This association allows Coveo to replicate the original repository permission system in your search interface.

<saml2:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified" Name="user.email">
    <saml2:AttributeValue xsi:type="xs:string" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">jsmith@example.com</saml2:AttributeValue>
</saml2:Attribute>

Optional attributes

user.groups

The user.groups attribute provides Coveo with the groups of which a user is a member. This allows you to import several members at once into a Coveo group.

<saml2:Attribute Name="user.groups" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
    <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:type="xs:string">GroupName1</saml2:AttributeValue>
    <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:type="xs:string">GroupName2</saml2:AttributeValue>
</saml2:Attribute>

user.firstName and user.lastName

The user.firstName and user.lastName attributes provide Coveo with the user’s name, which is available in the user menu of the Coveo Administration Console header.

<saml2:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"
    Name="user.firstName">
<saml2:AttributeValue xsi:type="xs:string"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">John</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
    Name="user.lastName">
<saml2:AttributeValue xsi:type="xs:string"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">Smith</saml2:AttributeValue>
</saml2:Attribute>

Prepare to Configure Coveo

Once you’ve configured your identity provider so that it passes the right information about user authentication to Coveo, you must configure Coveo to enable federation between Coveo and your identity provider. To do so, retrieve the following to later import into Coveo:

  • SSO URL (also called assertion consumer service (ACS))

  • Identity provider issuer URI (also called entity ID or federation service identifier)

  • The identity provider X.509 public certificate

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 (platform-ca | platform-eu | platform-au) 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 X.509 public certificate box.

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

  6. Click Add.

Encrypt assertions

Assertion encryption is optional. To encrypt your identity provider assertions:

  1. On the Settings page, in the Single sign-on (platform-ca | platform-eu | platform-au) tab, download Coveo’s certificate.

  2. Import the Coveo certificate into your identity provider configuration.

  3. Ensure that the identity provider will sign its responses. This prevents potential attacks on algorithms operating in CBC mode.

Test your configuration

Once you’ve completed the SSO configuration, test the login process to ensure it works as expected. To do so, you’ll need to add your SSO identity as a member of your Coveo organization. You can’t use the account you’ve used to configure SSO, as it’s associated with a different identity provider. See Login options and Multiple accounts for details.

  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’ve verified that your SSO configuration works, invite SSO users to join your Coveo organization.

Important

Once your SSO is active, promptly add your users to the organization as SSO users so they can log in successfully. When an organization has an SSO configured, users accessing a hosted search page of this organization are directed by default to the SSO login page. If a user hasn’t been added to Coveo as an SSO user, they can authenticate with their identity provider, but they won’t be able to access the hosted search page because no corresponding Coveo SSO user exists.

Add users to your Coveo organization by using either or both of these methods:

Configure SSO in another organization

If you have multiple Coveo organizations, such as a production organization and a sandbox organization, 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:

  1. Ensure that the user identity you’ll use to configure SSO:

  2. Using this identity, log in to the organization where you want to configure SSO.

  3. In the Single sign-on (platform-ca | platform-eu | platform-au) 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.

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

  5. Follow the remainder of the deployment process above, starting at the assertion encryption step, for each organization where you copied the SSO settings.

Required privileges

The following table indicates the privileges required to configure SSO on the Single sign-on (platform-ca | platform-eu | platform-au) page (see Manage privileges and Privilege reference).

Action Service Domain Required access level

View SSO configuration

Organization

Organization

View

Single sign-on identity provider

View

Edit SSO configuration

Organization

Organization

View

Single sign-on identity provider

Edit
Note

Granting the Edit access level on a domain also implicitly grants View on that domain.