Configure Coveo SAML SSO

This is for:

System Administrator

The Security Assertion Markup Language (SAML) is an XML-based, open-standard data format for exchanging authentication and authorization data between an identity provider and a service provider. Many single sign-on (SSO) systems support SAML 2.0 to allow an external service provider to rely on the user authentication performed by a trusted identity provider. SSO therefore allows users to log in to several systems with a single ID and password.

As an administrator, you can implement SAML 2.0 SSO so that users can log in to Coveo without having to provide their username and password. A third-party identity provider is then responsible for validating and confirming their identity to Coveo.

Identity Providers

Coveo supports any SAML 2.0 SSO identity provider. The following table lists the providers for which Coveo provides step-by-step configuration documentation. If you want to use a different identity provider, see Configuring a Custom SAML Identity Provider.

Identity provider Supports assertion encryption Supports group importation

ADFS

check

check

Microsoft Entra ID

check

check

Okta

check

check

OneLogin

check

x

PingOne

check

check

Custom

check

check

Coveo SAML SSO Workflow

You can configure your Coveo organization to rely on a trusted third party for providing user authentication information, and allow already authenticated users to log in without re-entering their credentials.

The main entities involved in the SAML protocol are:

  • The user wanting to log in to the service provider. The user may also be called principal by some identity providers.

  • The service provider, which is Coveo. The term service provider may be shortened to SP by some identity providers.

  • The identity provider, the third party issuing a user authentication assertion. The term identity provider may be shortened to IdP by some identity providers.

With SAML SSO embedded in your Coveo organization, the service-provider-initiated authentication process is the following:

  1. A user accesses your Coveo organization and, on the login page, clicks Log in with [identity provider].

  2. Coveo sends a SAML authentication request to the identity provider.

  3. Upon reception of the authentication request, if the user doesn’t already have an active session with the identity provider, the identity provider redirects the user to a login page.

  4. Upon successful user authentication, the identity provider writes a SAML response.

    The first part of the response contains information regarding the service provider and the identity provider, and the second part consists of an assertion containing statements, which contain attributes regarding the user identity. The identity provider signs the response and sends it to the service provider to confirm the authentication.

    Note

    If you choose to encrypt assertions, you must provide your identity provider with the Coveo public certificate.

  5. Coveo verifies the SAML response signature using the identity provider public certificate provided during configuration. This confirms the SAML assertion was emitted by the trusted identity provider.

  6. Coveo grants the user access to its content since the user identity was verified.

Notes

  • Coveo supports both service-provider-initiated login (explained in the above steps) and identity-provider-initiated login, which starts with the user logging in to the identity provider, and then accessing Coveo.

  • The RelayState parameter isn’t required.

  • Coveo applies a clock skew adjustment of plus-minus (±) 60 seconds.

Deployment Overview

  1. Choose and configure an identity provider.

  2. Retrieve the info required to configure Coveo to rely on your trusted identity provider for providing user authentication information.

  3. Configure your Coveo organization.

  4. If you want the identity provider to encrypt its assertions, provide it with the Coveo public certificate.

  5. Add your email address as an organization user and test your configuration by logging in.

  6. Invite SSO users or user groups to your organization and optionally include them in groups with appropriate privileges.

Important

Once you configure 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, you must promptly invite your users as SSO users of this organization. Otherwise, users will try to log in with their identity provider credentials, but access to the hosted search page won’t be allowed since there will be no SSO user corresponding to the provided credentials.
Notes

  • You’re responsible for maintaining your list of users and/or groups. Once they’re deleted from your identity provider, Coveo can’t restore them.

  • When you disable or delete a user in the SSO, the user still appears in your Coveo organization. However, this isn’t a security issue because the organization relies on the SSO provider to validate the user’s credentials. Therefore, the user is denied when trying to log in.

  • When you delete an SSO configuration from your Coveo organization, the SSO users are automatically deleted from Coveo because the user credentials can no longer be validated.

  • Linking to a OneLogin identity set isn’t supported yet.

Assertion Encryption

Identity providers configured to work together with Coveo sign the assertions they issue to confirm they indeed sent this data.

In addition to the assertion signature, you could choose to configure your identity provider so that it also encrypts its assertions. An encrypted assertion can only be decrypted by parties that have the required certificate to do so; this protects the private user data that may be included in this assertion, such as the user’s name and email address. Such protection reinforces the trust between the identity provider and the service provider, but it’s not required in the Coveo SSO context since all communications happen on a secured TLS channel.

However, since Coveo’s private key is required to decrypt an assertion, you can’t use a debugging tool and inspect the assertion content. Assertion encryption may therefore hinder debugging.

You can implement assertion encryption by providing your identity provider with the Coveo public certificate (see Encrypt Okta Assertions, Encrypt OneLogin Assertions, Encrypt PingOne Assertions, and Encrypt Custom Identity Provider Assertions).

If you choose to encrypt assertions, ensure that the response is signed. This prevents potential attacks on CBC-mode algorithms.

Note

Assertion encryption is automatically enabled with ADFS if you import the Coveo metadata file as described under Configuring ADFS for Coveo SAML SSO. It’s also possible to deactivate encryption if you prefer to have unencrypted assertions.

Reusing an SSO configuration in multiple organizations

It is possible to use your SSO configuration in more than one Coveo organization.

This is especially useful if you have users switching between multiple organizations, for example, a production and a sandbox organization.

As a result, users can log in to both organizations with the same SSO credentials.

To configure SSO in additional organizations

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

    If it’s not already a member, this user identity must be invited to the organizations and accept the invitations.

  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 (steps 4 to 6) for each organization where you copied the SSO settings.