Configure Azure for Coveo SSO

This is for:

System Administrator

Azure is a set of cloud services provided by Microsoft. You can use it to build single sign-on (SSO) applications, among other things.

Note

An Azure AD Premium subscription is required to build an SSO application for Coveo. The application creation feature used in the procedure below isn’t a feature of the basic Azure AD subscription.

As a Coveo administrator, you can implement Security Assertion Markup Language (SAML) 2.0 SSO when your company uses Azure Active Directory (AD). Users can then log in to Coveo without having to provide their authentication credentials since their identity has previously been validated when logging in to their Azure session.

To let users log in via SAML SSO, Coveo must be able to trust and rely on Azure to authenticate users wanting to log in. To establish this trust relationship, you must configure Azure and Coveo so that both parties can exchange authentication information.

Configure Your Azure Portal

Both Azure and Coveo must be configured to work together and provide a SAML SSO service to your Coveo users. First configure Azure so that it can provide Coveo with user authentication data.

  1. Log in to your Microsoft Azure Portal.

  2. At the upper-left corner, click the menu icon, and then click Azure Active Directory in the menu.

  3. In the navigation bar on the left, under Manage, click Enterprise applications.

  4. Click New application.

  5. On the Browse Azure AD Gallery subpage, click Create your own application.

  6. In the Create your own application blade, enter Coveo as a display name for your application, and then click Create.

  7. In the navigation bar on the left, under Manage, click Single sign-on.

  8. Select the SAML method.

  9. Under Set up Single Sign-On with SAML, click Edit in the Basic SAML Configuration box.

  10. In the Basic SAML Configuration blade:

    1. Under Identifier (Entity ID), click Add identifier, and then enter one of the following:

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

    2. Under Reply URL (Assertion Consumer Service URL), click Add reply URL, and then enter one of the following:

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

    3. Under Sign on URL, enter one of the following:

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

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

      • For an organization with data residency outside the US: https://platform-<REGION_ABBREVIATION>.cloud.coveo.com/login.

    4. Click Save.

  11. Back under Set up Single Sign-On with SAML, click Edit in the Attributes & Claims box.

  12. On the Attributes & Claims page:

    1. Click Add a new claim.

    2. On the Manage claim page, under Name, enter user.email.

    3. Under Source, select Attribute.

    4. Under Source attribute, select user.mail.

    5. Click Save.

  13. Back on the Attributes & Claims page:

    1. Click Add a group claim.

    2. In the Group Claims blade, select Group assigned to the application, and then sAMAccountName under Source attribute.

    3. Expand the Advanced options section, and then check the Customize the name of the group claim box.

    4. Under Name, enter user.groups.

    5. Click Save.

  14. Back on the Attributes & Claims page, click Unique User Identifier (Name ID) under Required claim:

    1. On the Manage claim page, under Source attribute, select user.mail.

    2. Click Save.

  15. In the page breadcrumb, click SAML-based Sign-on to return to the previous page.

  16. Back under Set up Single Sign-On with SAML, in the SAML Signing Certificate box, ensure that your certificate is active.

Prepare to Configure Coveo

In the previous section, you configured your Azure Portal so that it passes the right information about user authentication to Coveo.

You must now configure Coveo to enable federation between Coveo and your Azure Portal. To do so, you need to assign your Azure Active Directory users to the application you created, and retrieve data to later import into Coveo.

Assign Application to Users

Assign your application to the users you want to allow to log in to Coveo using Azure Portal SSO, including yourself.

Ensure that, in their profile, all users have their email address under Contact info. They’ll use this address to log in to Coveo.

Retrieve Data to Import

On your Azure application single sign-on page, the Set up Coveo box shows the URLs required to configure Coveo. The Login URL is your single sign-on URL, while the Azure AD Identifier is your identity provider issuer URI.

Similarly, the SAML Certificates box lets you download the required Base64 certificate.

Configure Coveo

Once you’ve 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 page:

    1. Log in to Coveo (platform-ca | platform-eu | platform-au) as a member of a group with the required privileges to manage settings in the target Coveo organization.

    2. On the Settings page, select the Organization tab, and then select the Single Sign-On subtab.

  2. In the Single Sign-On subtab, 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 URI box, enter the identity provider issuer unique URI. The identity provider issuer URI is also called entity ID or federation service identifier.

  5. Using one of the following methods, provide Coveo with the identity provider’s Base64 public certificate to validate the identity provider signature:

    • Paste the certificate in the Enter your public certificate box.

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

  6. Click Add.

Note

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 on the Settings page 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.

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

    Important

    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. For details on how accounts belonging to the same individual are separated, see Multiple Accounts.

    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.

Important

Once you set up an 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.