Coveo Cloud V2 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 V2 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 V2 (see Identity Providers).

Identity Providers

Coveo Cloud V2 should support any SAML 2.0 SSO identity provider. The following table lists the providers for which Coveo provides step-by-step configuration documentation.

Identity provider Supports assertion encryption Supports group importation
ADFS
Azure    
Okta
OneLogin  
PingOne  

All other SAML 2.0 identity providers should also be supported, although they have not been tested. Browse the Coveo Cloud V2 SAML SSO documentation to grasp how to configure your identity provider and Coveo Cloud V2. If you encounter implementation issues, contact the Coveo Support team.

Depending on the identity provider, different names may be used for the endpoints to provide. The following table should cover most of them:

Typical endpoint names Addresses
  • Assertion Consumer Service (ACS)

  • 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

  • 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

  • Audience URI

  • Entity ID

  • Identifier URL

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

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

Coveo Cloud V2 SAML SSO Workflow

You can configure your Coveo Cloud V2 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 V2. 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 V2 organization, the service-provider-initiated authentication process is the following:

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

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

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

  • 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 SAML Authentication).

Deployment Overview

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

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

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

  4. Add your email address as an organization user (see Members - Page).

  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 Members - Page, Groups - Page, 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 V2). 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 V2 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 V2 always 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 V2 SSO context.

However, since a certificate 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 V2 public certificate (see Configuring Coveo Cloud V2 SAML SSO, Encrypt Okta Assertions, and Encrypt OneLogin Assertions).

  • Assertion encryption is automatic with ADFS if you import the Coveo Cloud V2 metadata file as described under Configuring ADFS for Coveo Cloud V2 SAML SSO.

  • Encryption assertion is not supported for assertions exchanged between PingOne and Coveo Cloud V2, though it is supported for assertions exchanged between PingOne and PingFederate.