Configuring a Custom SAML Identity Provider for Coveo Cloud SSO

If you want to implement single sign-on (SSO) in your Coveo organization using an identity provider other than those for which Coveo offers detailed setup instructions, you can use this page to configure your own custom identity provider (see Identity Providers).

As a Coveo Cloud administrator, you can implement Security Assertion Markup Language (SAML) 2.0 SSO with your preferred identity provider (see Coveo Cloud V2 SAML SSO). Users can then log in to Coveo Cloud 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 Cloud 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 Cloud so that both parties can exchange authentication information.

  • If you’re not the identity provider administrator at your company, contact them so they configure the identity provider using the following steps. If you want to encrypt assertions, you will have to provide them with the Coveo Cloud public certificate as well.

  • Coveo supports HTTP POST binding only.

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


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) URL

  • POST Binding Endpoint


  • For a regular (non-HIPAA) organization:

  • For a HIPAA organization:

  • For an organization with data residency outside the US: https://platform-<REGION_ABBREVIATION>

  • Recipient URL

  • Reply URL

  • For a regular (non-HIPAA) organization:

  • For a HIPAA organization:

  • For an organization with data residency outside the US: https://platform-<REGION_ABBREVIATION>

  • Audience URI

  • Entity ID

  • Identifier URL

  • For a regular (non-HIPAA) organization or an organization with data residency outside the US:

  • For a HIPAA organization:

Assertion Settings

Coveo Cloud SAML SSO requires assertions with the following settings.


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

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

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

<saml2:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified" Name="">
    <saml2:AttributeValue xsi:type="xs:string" xmlns:xsi=""></saml2:AttributeValue>

Optional Attributes


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

<saml2:Attribute Name="user.groups" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
    <saml2:AttributeValue xmlns:xs=""
    <saml2:AttributeValue xmlns:xs=""

user.firstName And user.lastName

The user.firstName and user.lastName attributes provide Coveo Cloud with the user’s name, which is then displayed in the Coveo Administration Console header.

<saml2:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"
<saml2:AttributeValue xsi:type="xs:string"
<saml2:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
<saml2:AttributeValue xsi:type="xs:string"


The user.emailAliases attribute provides Coveo Cloud with the other email addresses a user may have. Use a comma to separate many addresses.

<saml2:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified" Name="user.emailAliases">
    <saml2:AttributeValue xsi:type="xs:string" xmlns:xsi="">,</saml2:AttributeValue>

Prepare to Configure Coveo Cloud

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

  • SSO URL (also called assertion consumer service (ACS))
  • Identity provider issuer URL (also called entity ID or federation service identifier)
  • The identity provider X.509 public certificate

Configure Coveo Cloud

Once you have configured your identity provider to provide Coveo Cloud with user authentication data, you must configure Coveo Cloud to trust your identity provider and accept to rely on it for user authentication.

  1. With the data required to fill the Coveo Cloud configuration form in hand, access the Settings panel:

    1. Log in to the Coveo Platform as a member of a group with the required privileges to manage settings in the target Coveo organization, if not already done.

    2. In the Administration Console upper-right corner, click Settings.

    3. In the Settings panel, select the Organization tab, and then, in the left-hand pane, click Single Sign-On.

  2. In the Single Sign-On tab, in the Identity provider name box, enter the identity provider name as you want it to appear on your Coveo organization login page (see Logging in to Coveo Cloud).

  3. In the Single sign-on URL box, enter the URL where Coveo Cloud must send an authentication request.

    The SSO URL is also called assertion consumer service (ACS).

  4. In the Identity provider issuer URL box, enter the identity provider issuer unique URL.

    The identity provider issuer URL is also called entity ID or federation service identifier, and must be unique across all platform organizations using SSO.

  5. Provide Coveo Cloud with the identity provider public certificate to validate the identity provider signature:

    • Paste the X.509 public certificate in the Public certificate box.


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

    The certificate must be Base64-encoded and may contain the -----BEGIN CERTIFICATE----- and ----END CERTIFICATE----- tags.

  6. Click Add.

  • 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 in the Settings panel of the Coveo Cloud Administration Console.
  • To avoid this error, a Coveo administrator can add a notification as a reminder to update the certificate prior to the rotation date.

Encrypt Assertions

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

  1. In the Settings panel, in the Single Sign-On tab, under Advanced Option, download the Coveo Cloud certificate.

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

Test Your Configuration

  1. Add your email address as an organization member (see Adding and Managing Members). In the Add a Member dialog, under Provider, ensure to select Single sign-on.

  2. Log out of Coveo Cloud, and then log in using SSO and your identity provider account. By doing so, you make sure Coveo Cloud and your identity provider work together smoothly.

    We strongly recommend that you do not delete the account with which you first logged in to Coveo Cloud and implemented SAML SSO. This original account is a “backdoor” that prevents you to be locked out if the SAML SSO doesn’t work as expected: at any time, you can log in via the regular, non-SSO login page, and then edit the Coveo Cloud configuration. Alternatively, if you must delete your original account, you can also create another non-SSO administrator account with the required privileges beforehand.

Invite SSO Users or User Groups

Once your have verified that your SSO configuration works, invite SSO users or user groups to your organization (see Adding and Managing Members and Import Members).

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. 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 Cloud SSO user corresponding to the provided credentials.

Recommended Articles