Coveo Cloud SAML SSO

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 (see Security Assertion Markup Language). 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 Cloud without having to provide their username and password. A third-party identity provider is then responsible for validating and confirming their identity to Coveo Cloud (see Identity Providers).

Identity Providers

Coveo Cloud 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 custom identity provider, see Configuring a Custom SAML Identity Provider.

Coveo Cloud SAML SSO Workflow

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

The main entities involved in the SAML protocol are:

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

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

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

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

  1. A user accesses your Coveo Cloud organization and, on the login page, clicks Log in with [identity provider] (see Logging in Using Single Sign-On).

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

  3. Upon reception of the authentication request, if the user does not 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.

  5. Coveo Cloud 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 Cloud grants the user access to its content since the user identity was verified.

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

  • For now, you can configure only one identity provider per Coveo Cloud organization and vice versa through the UI. However, you can assign more than one organization to your identity provider using API calls (see Assigning Multiple Coveo Cloud Organizations to a SAML Authentication Provider and SAML Authentication API documentation).

  • The RelayState parameter is not required.

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

Deployment Overview

  1. Choose and configure an identity provider (see Identity Providers).

  2. Configure your Coveo Cloud organization to rely on your trusted identity provider for providing user authentication information (see Configuring Coveo Cloud SAML SSO).

  3. If you want the identity provider to encrypt its assertions, provide it with Coveo Cloud public certificate (see Assertion Encryption, Encrypt Okta Assertions, Encrypt OneLogin Assertions, and Encrypt Custom Identity Provider Assertions).

  4. Add your email address as an organization user (see Adding and Managing Members).

  5. Test your setup by logging in (see Logging in Using Single Sign-On).

  6. Invite SSO users or user groups to your organization and optionally include them in groups with appropriate privileges (see Adding and Managing Members, Adding and Managing Groups, and Add Members Belonging to an Identity Set to a Group).

    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 (see Access a Search Page). Therefore, after configuring your SSO, promptly invite your users as SSO users of this organization (see Logging in to Coveo Cloud). Otherwise, users will enter their identity provider credentials, but access to the hosted search page will not be allowed since there will be no Coveo Cloud SSO user corresponding to the provided credentials.

    Linking to a OneLogin identity set is not supported yet.

Assertion Encryption

Identity providers configured to work together with Coveo Cloud 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 is not required in the Coveo Cloud SSO context since all communications happen on a secured TLS channel.

However, since Coveo’s private key is required to decrypt an assertion, you cannot 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 Cloud public certificate (see Configuring Coveo Cloud SAML SSO, Encrypt Okta Assertions, Encrypt OneLogin Assertions, Encrypt PingOne Assertions, and Encrypt Custom Identity Provider Assertions).

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