---
title: Configure ADFS for Coveo SSO
slug: '1895'
canonical_url: https://docs.coveo.com/en/1895/
collection: manage-an-organization
source_format: adoc
---
# Configure ADFS for Coveo SSO
[Active Directory Federation Services](https://en.wikipedia.org/wiki/Active_Directory_Federation_Services) (ADFS) is a Windows Server software providing single sign-on (SSO) for external applications such as Coveo.

As a Coveo administrator, you can [implement Security Assertion Markup Language (SAML) 2.0 SSO](https://docs.coveo.com/en/1979/) when your company uses ADFS. 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 session.

To allow users to log in via SAML SSO, Coveo must be able to trust and rely on ADFS to authenticate users wanting to log in.
To establish this trust relationship, you must configure ADFS and Coveo so that both parties can exchange authentication information.
This page explains how to proceed.

To configure SSO in more than one Coveo organization, for example in a production organization and a [sandbox organization](https://docs.coveo.com/en/2959/), configure one of these organizations, and then follow [the instructions](#configure-sso-in-another-organization) at the end of this page.

> **Note**
>
> If you're not the ADFS administrator at your company, contact them so they configure ADFS using the following steps.

## Configure ADFS

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

. On Windows Server, open your Windows Control Panel, and then click **System and Security**.
. Click **Administrative Tools**, and then click **ADFS Management**.
. In the **AD FS** console, on the left side of the page, click **Relying Party Trusts**.
. On the left side of the page, under **Actions** > **Relying Party Trusts**, click **Add Relying Party Trust**.
. In the **Add Relying Party Trust** wizard, select **Claims aware**, since the service provider to which you want to connect, that is, Coveo, supports Claims, and then click **Next**.
. [[ImportMetadata]]Select **Import data about the relying party published online or on a local network**, and then under **Federation metadata address**:
 ** For a regular (non-HIPAA) organization, enter `+https://platform.cloud.coveo.com/saml/metadata+`.

OR

 ** For a HIPAA organization, enter `+https://platformhipaa.cloud.coveo.com/saml/metadata+`.

OR

 ** For an organization with [data residency outside the U.S.](https://docs.coveo.com/en/2976/), enter `+https://platform-<REGION_ABBREVIATION>.cloud.coveo.com/saml/metadata+`.


> **Note**
>
> [Assertion encryption](https://docs.coveo.com/en/1979#assertion-encryption) is automatically enabled if you import the Coveo metadata file. However, it's possible to deactivate encryption if you prefer to have unencrypted assertions.
. Click **Next**.

. [[displayname]]Under **Display name**, enter a service provider name to display in your list of relying party trusts, for example, `Coveo`.

. Optionally add **Notes**, and then click **Next**.
. Under **Configure Multi-Factor Authentication Now?**:
 ** If you don't need a specific configuration, select **I don't want to configure multi-factor authentication settings for this relying party trust at this time**.

OR

 ** If you do need a specific configuration:
  ... Select **Configure multi-factor authentication settings for this relying party trust**.
  ... Click **Next**.
  ... Under **Configure Multi-factor Authentication**, configure your desired multi-factor authentication settings, and then click **Next**.
. Under **Choose Issuance Authorization Rules**, select **Permit all users to allow users to access this relying party** to allow all users right now and later pick users to whom access should be forbidden.
Alternatively, choose **Deny all users access to this relying party** to deny all users right now and create an access rule later.
Click **Next**.
. Under **Ready to Add Trust**, you don't need to do anything, click **Next**.
. Under **Finished**, leave the **Configure claim rules for this application** checkbox selected, and then click **Close**.
. [[Step14]]In the dialog that appears, on the **Issuance Transform Rules** tab, click **Add Rule**.
. In the **Add Transform Claim Rule** wizard, in the **Claim rule template** dropdown menu, select **Send LDAP Attributes as Claims**, and then click **Next**.


> **Note**
>
> You can also access the **Add Transform Claim Rule** wizard by clicking **Edit Claim Rules** in the **AD FS** console.
. [[Step16]]Under **Configure Claim Rule**, fill the boxes using the following table values, and then click **Finish**.


|===
| Claim Rule Name | Attribute Store | LDAP Attribute | Outgoing Claim Type

| `Email`
| `Active Directory`
| `E-Mail-Addresses`
| `E-Mail Address`
|===

. [[Step17]]To [import your ADFS groups](https://docs.coveo.com/en/1980#import-members) into Coveo, click **Add new attribute** again, and then fill the boxes using the following table values.


> **Note**
>
> Importing your ADFS groups into Coveo allows you to create several Coveo organization members at once.
> If you don't import your ADFS groups, you must add your users to your Coveo organization one by one (see [Manage Members](https://docs.coveo.com/en/1821/)).


|===
| Claim Rule Name | Attribute Store | LDAP Attribute | Outgoing Claim Type

| `Groups`
| `Active Directory`
| `Token-groups - Unqualified Names`
| `Group`
|===
. If needed, repeat steps [14](#Step14) to [16](#Step16) for optional rules, depending on the claims you're already using to authenticate users, and then click **Finish**.


> **Important**
>
> Make sure you have a Send LDAP Attributes as Claims rule for each optional Transform Claim rule you plan on adding, so that all attributes and claims are handled smoothly.
> 
> For example, if you plan on adding a `Group to user.groups` Transform Claim rule, you must set up a `Token-groups - Unqualified Names` to `Group` Send LDAP Attributes as Claims rule in the first place.
. [[Step19]]Back in the dialog, on the **Issuance Transform Rules** tab, click **Add Rule**.
. In the **Add Transform Claim Rule** wizard, in the **Claim rule template** dropdown menu, select **Transform an Incoming Claim**, and then click **Next**.


> **Note**
>
> You can also access the **Add Transform Claim Rule** wizard by clicking **Edit Claim Rules** in the **AD FS** console.
. [[Step21]]Under **Configure Claim Rule**, fill the boxes using the values provided in the following table, and then click **Finish**. See [Assertion Settings](https://docs.coveo.com/en/2706#assertion-settings) for details.


[cols=",,,,,^"]
|===
| Claim Rule Name | Incoming Claim Type | Incoming Name ID Format | Outgoing Claim Type | Outgoing Name ID Format | Pass Through All Claim Values

| `Email to User ID`
| `E-Mail Address`
| Unspecified
| `Name ID`
| Unspecified
| [check]

| `Email to user.email`
| `E-Mail Address`
| Unspecified
| `user.email`
| Unspecified
| [check]
|===


> **Notes**
>
> * The `NameID` attribute must contain a unique representation of the user and shouldn't change over time.
> This attribute is used to match the Coveo username.
> The `NameID` can be up to 229 characters long.
> 
> * Coveo forbids the `Transient` format for the `NameID` attribute, since `NameID` shouldn't change over time.
. If you chose to import your ADFS groups in Coveo in step [17](#Step17), add the following rule (see [user.groups](https://docs.coveo.com/en/2706#user-groups) for details):


[cols=",,,,,^"]
|===
| Claim Rule Name | Incoming Claim Type | Incoming Name ID Format | Outgoing Claim Type | Outgoing Name ID Format | Pass Through All Claim Values

| `Group to user.groups`
| `Group`
| Unspecified
| `user.groups`
| Unspecified
| [check]
|===
. For additional optional rules, repeat steps [19](#Step19) to [21](#Step21).


> **Note**
>
> All optional attributes should be in `Unspecified` format.


> **Important**
>
> Make sure you have a Send LDAP Attributes as Claims rule for each optional Transform Claim rule you added, so that all attributes and claims are handled smoothly.
> 
> For example, if you add a `Group to user.groups` Transform Claim rule, you must set up a `Token-groups - Unqualified Names` to `Group` Send LDAP Attributes as Claims rule in the first place.


**Example**

You could choose to add the following rules:
[cols=",,,,,^"]
|===
| Claim Rule Name | Incoming Claim Type | Incoming Name ID Format | Outgoing Claim Type | Outgoing Name ID Format | Pass Through All Claim Values

| `GivenName to user.firstName`
| `Given Name`
| Unspecified
| `user.firstName`
| Unspecified
| [check]

| `Surname to user.lastName`
| `Surname`
| Unspecified
| `user.lastName`
| Unspecified
| [check]
|===

. In the **Edit Claim Rules for** the platform address dialog, click **OK**.

. If you left [assertion encryption](https://docs.coveo.com/en/1979#assertion-encryption) enabled, you must ensure that ADFS signs its responses.
To do so, in [PowerShell](https://learn.microsoft.com/en-us/powershell/module/adfs/set-adfsrelyingpartytrust?view=windowsserver2019-ps), enter the following command, and then replace `Coveo` with the [display name](#displayname) you chose earlier:

```text
Set-AdfsRelyingPartyTrust -TargetName "Coveo" -SamlResponseSignature MessageAndAssertion
```

Signed responses prevent potential attacks on CBC-mode algorithms.

## Prepare to configure Coveo

Once you've configured ADFS so that it passes the right information about user authentication to Coveo, you must configure Coveo to enable federation between Coveo and ADFS.
To do so, retrieve data to later import into Coveo:

. In the **AD FS** console, on the left side, right-click **AD FS**, and then select **Edit Federation Service Properties**.
Alternatively, you may click **AD FS**, and then, in the **Actions** panel on the right, click **Edit Federation Service Properties**.
. Copy the **Federation Service Identifier** (also called identity provider issuer URL, or identity provider entity ID) address and paste it somewhere so you can access it later when configuring Coveo. This address ends with `/trust`.

. In the **AD FS** console, on the left side, under **Service**, click **Certificates**.
. Under **Token-signing**, select the **CN=ADFS Signing** certificate and then, in the **Actions** panel on the right, click **View Certificate**
. In the **Certificate** dialog, click the **Details** tab, and then click **Copy to File**
. In the **Certificate Export** wizard, select the **Base-64 encoded X.509 (.CER)** format, and then click **Next**.
. Browse to the location where you want to save the certificate, and then click **Finish**.

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

. With the [data required to fill the Coveo configuration form](#prepare-to-configure-coveo) in hand, access the **Settings** page:

.. [Log in to Coveo](https://platform.cloud.coveo.com/login) ([platform-ca](https://platform-ca.cloud.coveo.com/login) | [platform-eu](https://platform-eu.cloud.coveo.com/login) | [platform-au](https://platform-au.cloud.coveo.com/login)) as a [member](https://docs.coveo.com/en/2869/) of a [group](https://docs.coveo.com/en/2867/) with the [required privileges](https://docs.coveo.com/en/1562#required-privileges) to manage settings in the target [Coveo organization](https://docs.coveo.com/en/185/).

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

. 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](https://docs.coveo.com/en/1697/).

. In the **Single sign-on URL** box, enter the URL where Coveo must send an authentication request.
The SSO URL may also be called _Assertion Consumer Service_ (ACS).

. In the **Identity provider issuer URI** box, enter the identity provider issuer unique URI.
The identity provider issuer URI may also be called _entity ID_ or _federation service identifier_.

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

. Click **Add**.

. Plan a certificate update following the SSO roll over or expiration schedule.

> **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**](https://docs.coveo.com/en/1562/) page of the [Coveo Administration Console](https://docs.coveo.com/en/183/).
> 
> To avoid this error, a Coveo administrator can add a [notification](https://docs.coveo.com/en/1583#add-or-edit-an-organization-notification) as a reminder to update the certificate prior to the rotation date.

## Test your configuration

. [Add your email address as an organization member](https://docs.coveo.com/en/1821/).
In the **Add a Member** dialog, under **Provider**, ensure to select **Single sign-on**.

. [Log out of the Coveo Administration Console](https://docs.coveo.com/en/1841#user-menu), and then [log back in using the SSO option and your identity provider account](https://docs.coveo.com/en/1697#logging-in-with-sso).
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](https://docs.coveo.com/en/1697#multiple-accounts).
> 
> Alternatively, if you must delete your original account, you can also create another non-SSO administrator account with the [required privileges](https://docs.coveo.com/en/1562#required-privileges) beforehand.
> [Logging in via email](https://docs.coveo.com/en/1697#logging-in-with-email) is also an alternative.

## Invite SSO users or user groups

Once you've verified that your SSO configuration works, [invite SSO users to join your Coveo organization](https://docs.coveo.com/en/1821/).

> **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](https://docs.coveo.com/en/1697/). 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.

## Configure SSO in another organization

If you have multiple Coveo organizations, such as a production organization and a [sandbox organization](https://docs.coveo.com/en/2959/), you must use the same SSO settings for all organizations.
Users will then use the same SSO credentials to log in, regardless of the organization they are accessing.

Follow these steps to configure SSO in additional organizations:

. Ensure that the user identity you'll use to configure SSO:

--
** Is a [member](https://docs.coveo.com/en/2869/) of all [organizations](https://docs.coveo.com/en/185/) where the SSO configuration will be used, including the original organization where SSO is already configured.
If it's not already a member, this user identity must be [invited](https://docs.coveo.com/en/1821#add-members) to the organizations and [accept the invitations](https://docs.coveo.com/en/1697#after-login).
** Has the [privilege](https://docs.coveo.com/en/228/) to edit SSO settings (**Edit** on the [**Single sign-on identity provider** domain](https://docs.coveo.com/en/1707#single-sign-on-identity-provider-domain)) in each of these organizations.
--

. Using this identity, log in to the organization where you want to configure SSO.

. In the [**Single Sign-On**](https://platform.cloud.coveo.com/admin/#/orgid/settings/organization/sso) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/settings/organization/sso) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/settings/organization/sso) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/settings/organization/sso)) tab of the **Settings** page, delete any existing SSO configuration.
Save your change.
This will also permanently delete the associated SSO members from your Coveo organization.

. Copy the SSO settings from the first organization to the other.
The SSO settings provided to Coveo must be identical across all organizations, including the identity provider name.

> **Tip**
>
> Open the organization where SSO was originally configured in a private browser window.
> This will let you copy and paste from one organization to the other without logging in and out to switch between them.

. Follow the remainder of the deployment process above, starting at the assertion encryption step, for each organization where you copied the SSO settings.