Configuring ADFS for Coveo Cloud SSO

Active Directory Federation Services (ADFS) is a Windows Server software providing single sign-on (SSO) for external applications such as Coveo Cloud.

As a Coveo Cloud administrator, you can implement Security Assertion Markup Language (SAML) 2.0 SSO when your company uses ADFS (see Coveo Cloud V2 SAML SSO). Users can then log in to Coveo Cloud 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 Cloud must be able to trust and rely on ADFS to authenticate users wishing to log in. To establish this trust relationship, you must configure ADFS and Coveo Cloud so that both parties can exchange authentication information.

If you are not the ADFS administrator at your company, contact them so they configure ADFS using the following steps.

Configure ADFS

Both ADFS and Coveo Cloud must be configured to work together and provide a SAML SSO service to your Coveo Cloud users. First configure ADFS so that it can provide Coveo Cloud 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-hand side, click Relying Party Trusts.

  4. On the left hand side, 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, i.e., Coveo Cloud, 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

    Assertion encryption is automatically enabled if you import the Coveo Cloud metadata file (see Assertion Encryption). However, it is possible to deactivate encryption if you prefer to have nonencrypted assertions.

  7. Click Next.

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

  9. Optionally add Notes, and then click Next.

  10. Under Configure Multi-Factor Authentication Now?:
    • If you do not need a specific configuration, select I do not 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 do not need to do anything, click Next.

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

  14. In the Edit Claim Rules for [platform address] dialog, in the Issuance Transform Rules tab, click Add Rule.

  15. In the Add Transform Claim Rule wizard, in the Claim rule template drop-down menu, select Send LDAP Attributes as Claims, and then click Next.

    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 Cloud, click Add new attribute again, and then fill the boxes using the following table values.

    Importing your ADFS groups into Coveo Cloud allows you to create several Coveo Cloud organization members at once. If you do not import your ADFS groups, you must add your users to your Coveo Cloud organization one by one (see Adding and Managing 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 are already using to authenticate users, and then click Finish.

    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.

    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 Edit Claim Rules for [platform address] dialog, in the Issuance Transform Rules tab, click Add Rule

  20. In the Add Transform Claim Rule wizard, in the Claim rule template drop-down menu, select Transform an Incoming Claim, and then click Next.

    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
    Email to user.email E-Mail Address Unspecified user.email Unspecified
    • The NameID attribute must contain a unique representation of the user and should not change over time. This attribute is used to match the Coveo Cloud username. The NameID can be up to 229 characters long.

    • Coveo Cloud forbids the Transient format for the NameID attribute, since NameID should not change over time.

  22. If you chose to import your ADFS groups in Coveo Cloud at 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
  23. Repeat steps 19 to 21 for optional rules, and then, in the Edit Claim Rules for [platform address] dialog, click OK.

    All optional attributes should be in Unspecified format.

    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.

    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.

    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
    Surname to user.lastName Surname Unspecified user.lastName Unspecified

Prepare to Configure Coveo Cloud

Once you have configured ADFS 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 ADFS. To do so, you need to retrieve data to later import into Coveo Cloud.

  1. In the AD FS console, on the left-hand side, right-click AD FS, and then select Edit Federation Service Properties. Alternatively, you may click AD FS, and then, in the Actions pane 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 Cloud.

    This address ends with /trust.

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

  4. Under Token-signing, select the CN=ADFS Signing certificate and then, in the Actions pane 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 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.

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