Configure a Custom SAML Identity Provider for Coveo SSO

Coveo provides detailed instructions to implement single sign-on (SSO) in your Coveo organization using a variety of identity providers. However, configuring SSO with a 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.

  • Only the identity provider administrator at your company can configure the identity provider using the following steps. If you want to encrypt assertions, you must provide them with the Coveo public certificate as well.

  • Coveo supports HTTP POST binding only.

  • Should 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>

user.emailAliases

The user.emailAliases attribute provides Coveo 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:attrname-format:unspecified" Name="user.emailAliases">
    <saml2:AttributeValue xsi:type="xs:string" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">jsmith@example.com,john_smith@company.com</saml2:AttributeValue>
</saml2:Attribute>

Prepare to Configure Coveo

Once you have 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, you need to retrieve the following to later import into Coveo:

  • 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

Once you have 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 panel:

    1. Log in to the Coveo Administration Console 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 Settings page, select the Organization tab, and then, on the left side of the 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.

  3. In the Single sign-on URL box, enter the URL where Coveo 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.

  5. Using one of the following methods, provide Coveo 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 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 certificate.

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

Test Your Configuration

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

    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.

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

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

Recommended Articles