Configuring a Custom SAML Identity Provider for Coveo Cloud SSO

If you want to implement single sign-on (SSO) in your Coveo Cloud 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 wishing 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 are 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 assistance.

Endpoints

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

  • 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

Assertion Settings

Coveo Cloud 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:2.0:nameid-format:unspecified">your-unique-nameid</saml2:NameID>
</saml2:Subject>

user.email Attribute

The user.email 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 and therefore show search results from secured sources to the appropriate users (see Coveo Cloud V2 Management of Security Identities and Item Permissions).

<saml2:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:nameid-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 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="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 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"
    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 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="http://www.w3.org/2001/XMLSchema-instance">jsmith@example.com,john_smith@company.com</saml2:AttributeValue>
</saml2:Attribute>

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 Cloud platform as a member of a group with the required privileges to manage settings in the target Coveo Cloud organization.

    2. In the administration console upper-right corner, click the Settings icon (Settings icon).

    3. In the Settings panel, click 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 Cloud 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.

      OR

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

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.

    It is strongly recommended not to 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 does not 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 will not be allowed since there will be no Coveo Cloud SSO user corresponding to the provided credentials.

Recommended Articles