Configure ADFS for Coveo SSO

This is for:

System Administrator

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

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.

  1. On Windows Server, open your Windows Control Panel, and then click System and Security.

  2. Click Administrative Tools, and then click ADFS Management.

  3. In the AD FS console, on the left side of the page, click Relying Party Trusts.

  4. On the left side of the page, under Actions > Relying Party Trusts, click Add Relying Party Trust.

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

  6. 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., enter https://platform-<REGION_ABBREVIATION>.cloud.coveo.com/saml/metadata.

    Note

    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.

  7. Click Next.

  8. Under Display name, enter a service provider name to display in your list of relying party trusts, for example, Coveo.

  9. Optionally add Notes, and then click Next.

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

      1. Select Configure multi-factor authentication settings for this relying party trust.

      2. Click Next.

      3. Under Configure Multi-factor Authentication, configure your desired multi-factor authentication settings, and then click Next.

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

  12. Under Ready to Add Trust, you don’t need to do anything, click Next.

  13. Under Finished, leave the Configure claim rules for this application checkbox selected, and then click Close.

  14. In the dialog that appears, in the Issuance Transform Rules tab, click Add Rule.

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

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

  17. If you want to import your ADFS groups 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).

    Claim Rule Name Attribute Store LDAP Attribute Outgoing Claim Type

    Groups

    Active Directory

    Token-groups - Unqualified Names

    Group

  18. If needed, repeat steps 14 to 16 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 need to set up a Token-groups - Unqualified Names to Group Send LDAP Attributes as Claims rule in the first place.

  19. Back in the dialog, in the Issuance Transform Rules tab, click Add Rule.

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

  21. Under Configure Claim Rule, fill the boxes using the values provided in the following table, and then click Finish. See Assertion Settings for details.

    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.

  22. If you chose to import your ADFS groups in Coveo in step 17, add the following rule (see user.groups for details):

    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

  23. For additional optional rules, repeat steps 19 to 21.

    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 need to 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:

    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

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

  25. If you left assertion encryption enabled, you must ensure that ADFS signs its responses. To do so, in PowerShell, enter the following command, and then replace Coveo with the display name you chose earlier:

    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, you need to retrieve data to later import into Coveo.

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

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

  3. In the AD FS console, on the left side, under Service, click Certificates.

  4. Under Token-signing, select the CN=ADFS Signing certificate and then, in the Actions panel on the right, click View Certificate

  5. In the Certificate dialog, click the Details tab, and then click Copy to File

  6. In the Certificate Export wizard, select the Base-64 encoded X.509 (.CER) format, and then click Next.

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

  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 may also be 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 may also be 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.

  7. 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 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. Logging in via email is also an alternative.

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.