Configure a SAML identity provider using the Search API

This is for:

Developer

Many Single Sign-On (SSO) systems use the SAML 2.0 standard to allow external services to rely on authentication delivered by a central identity provider (IdP). The Search API and Coveo’s UI libraries support SAML authentication. This article explains how to create a SAML authentication provider using the Coveo Search API.

Note

When performing queries that leverage SAML authentication, you have to inform the Search API that you want to use the identities from a given provider. This is handled for you when you use the Headless package or JavaScript Search Framework component. If you’re not using either of these, however, you’ll have to add an additional authentication parameter to the query.

Various implementations of the SAML 2.0 standard are available, each of which has its own distinct configuration process. In addition to the generic guidelines explained in this section, this article provides specific instructions to configure the following IdPs:

If you want to configure another IdP (such as PingFederate or OneLogin), see your product documentation.

Search API login flow

Authentication often involves one or more redirections to accumulate identities from IdPs. The following schema illustrates the flow of redirections when an unauthenticated user accesses a secured search interface.

Search API login flow

  1. The user enters a query in the search box.

  2. The search page sends a call to the Search API at /rest/search.

    Important

    If you’re not using the Headless @coveo/auth package or JavaScript Search Framework AuthenticationProvider component, you’ll have to add the authentication=<YOUR_AUTHENTICATION_PROVIDER_NAME> parameter to the query. It tells the Search API that you want to use the identities from the given provider. Without this parameter, the search may fail, or it might not find the right documents because it’s anonymous.

  3. The user’s credentials are invalid, so the Search API returns an error.

  4. The search page sends a call to the Search API at /rest/search/login to begin the login process.

    This call includes the redirectUri parameter, which is typically set to the current URL of the search page:

    https://searchdev.cloud.coveo.com/rest/search/login/mySAMLAuthenticationProvider?organizationId=mycoveoorganizationg8tp8wu3&redirectUri=https://www.example.com

  5. The Search API redirects the user’s browser to the third-party authentication provider.

  6. The user logs in to the authentication provider.

  7. The authentication provider redirects the user’s browser back to the Search API at /rest/search/login. This call includes the user’s authenticated identities.

  8. The Search API temporarily stores these identities and returns a handshake token to the user by redirecting to the search page.

    1. The Search API doesn’t provide the search token directly, because it might be too long to fit into the URL.

    2. This redirection uses the URL stored in the redirectUri parameter.

  9. The search page sends a call to the Search API at /rest/search/login/handshake. This call includes the handshake token, and the response includes the search token.

  10. The authenticated user can now perform queries on the search page.

    Important

    If you’re not using the Headless @coveo/auth package or JavaScript Search Framework AuthenticationProvider component, you’ll have to add the authentication=<YOUR_AUTHENTICATION_PROVIDER_NAME> parameter to the query. It tells the Search API that you want to use the identities from the given provider. Without this parameter, the search may fail, or it might not find the right documents because it’s anonymous.

Assertion URL

At some point during the IdP configuration process, you’ll likely have to specify the URL to send the SAML assertions. This URL has the following format:

https://platform.cloud.coveo.com/rest/search/v2/login/{provider}?organizationId={organizationId}

where:

You’ll also pass this URL to the assertionConsumerServiceUrl parameter in a POST request to the Search API.

You may also need to define the username format to return when a user successfully authenticates. Make sure you specify a format that suits the provider of your Search API SAML authentication provider.

Example

When using Active Directory as a security identity provider, acceptable username formats would be domain\user or user@domain.

Obtain SAML metadata

Most of the information that’s required by a Search API SAML authentication provider comes from the SAML metadata which your IdP can deliver.

Create a Search API SAML authentication provider

To create a Search API SAML authentication provider, send a POST request to:

https://platform.cloud.coveo.com/rest/organizations/{organizationId}/authentication/saml

where you replace {organizationId} with the unique identifier of your Coveo organization (for example, mycoveoorganizationg8tp8wu3).

You can create many Search API SAML authentication providers if necessary. However, a single SAML authentication provider is usually enough.

Example
POST https://platform.cloud.coveo.com/rest/organizations/mycoveoorganizationg8tp8wu3/authentication/saml HTTP/1.1
​
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************

Payload

{
  "name": "mySAMLAuthenticationProvider",
  "assertionConsumerServiceUrl": "https://platform.cloud.coveo.com/rest/search/v2/login/mySAMLAuthenticationProvider?organizationId=mycoveoorganizationg8tp8wu3",
  "metadata": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><md:EntityDescriptor xmlns:md=\"urn:oasis:names:tc:SAML:2.0:metadata\"[...]",
  "relyingPartyIdentifier": "https://platform.cloud.coveo.com",
  "expiration": 3600000,
  "enforceTrustedUris": true
}

201 Created response body

{
  "id": "g4t85744-769b-4885-p9w0-4m0hk49n674i"
}
Important

The provider request body property is obsolete and has been removed.

Request body properties

expiration (unsigned integer, required)

How much time (in milliseconds) it takes for the browser cookie that stores the SAML information to expire. Setting this parameter to 0 means that the cookie will expire at the end of a browser session.

Sample value: 3600000

metadata (string, required)

The SAML XML Metadata. You can get this metadata from your IdP.

Important

Don’t forget to escape all double quote (") characters with backslashes (\) when specifying the metadata argument.

Also remember to add the mandatory new lines characters (\n) in the certificate.
Example
<?xml version="1.0" encoding="UTF-8"?>

becomes

<?xml version=\"1.0\" encoding=\"UTF-8\"?>

and

<ds:X509Certificate>
  mUqDy0cEfgTDUGcUcFY1By4n9Y/VsBDFGiH0HwIDAQAB5A0GCSqGSIb3DQEBBQU4BCrTy147Fhcv
  s1GeQOQvibBc76Q6FuTGQaBrV00nYQByzr8T[...]
</ds:X509Certificate>

becomes

<ds:X509Certificate>mUqDy0cEfgTDUGcUcFY1By4n9Y/VsBDFGiH0HwIDAQAB5A0GCSqGSIb3DQEBBQU4BCrTy147Fhcv\ns1GeQOQvibBc76Q6FuTGQaBrV00nYQByzr8T[...]</ds:X509Certificate>

Sample value (excerpt): <?xml version=\"1.0\" encoding=\"UTF-8\"?><md:EntityDescriptor xmlns:md=\"urn:oasis:names:tc:SAML:2.0:metadata\"[…​]>

name (string, required)

The name of the Search API SAML authentication provider.

Sample value: mySAMLAuthenticationProvider

assertionConsumerServiceUrl (string)

The URL the browser should redirect to after the user authenticates. Set this parameter to:

https//platform.cloud.coveo.com/rest/search/v2/login/{provider}?organizationId={organizationId}

where:

  • {provider} is the name of the Search API SAML authentication provider.

  • {organizationId} is the unique identifier of the Coveo organization.

Sample value: https://platform.cloud.coveo.com/rest/search/v2/login/mySAMLAuthenticationProvider?organizationId=mycoveoorganizationg8tp8wu3

enforceTrustedUris (Boolean)

Whether redirections to the search page are limited to a list of trusted URIs. You can authorize redirections to improve the security of your Coveo-powered search implementation.

Important
Important

This feature is currently turned off by default to avoid breaking existing implementations. When this parameter is set to true, it prevents all redirections until you’ve configured a list of trusted URIs.

If you would like to enable this feature, we recommend that you follow the instructions in the Authorize redirections section and create a list of trusted URIs first.

Sample value: true

relyingPartyIdentifier (string)

The relying party identifier. Set this parameter to the corresponding value from your IdP Administration Console.

Tip
Leading practice

A good choice is to use the Coveo host name as relyingPartyIdentifier:

https://platform.cloud.coveo.com

This parameter isn’t required when using Okta as an IdP.

Sample value: https://platform.cloud.coveo.com

Authorize redirections

To ensure the security of your search implementation, every redirection to your search page should come from an authorized URL. If you’re using an SSO system through the Search API, you can view a list of recent untrusted redirections and configure allowed redirections.

Important
Important

Untrusted redirections are allowed by default in the Search API. For now, you must set the enforceTrustedUris parameter to true in your SAML authentication provider to authorize redirections.

In the future, however, the default behavior will be to prevent untrusted redirections. We recommend that you configure allowed redirections now to improve the security of your implementation and ensure a smooth transition when unauthorized redirections become blocked by default.

View recent untrusted redirections

Before you authorize any redirections, you should view the list of recent untrusted redirections by sending a GET request to:

https://platform.cloud.coveo.com/rest/organizations/{organizationId}/authentication/trusteduris/recentuntrusted?page=0&perPage=20

where {organizationId} is the unique identifier of your Coveo organization (for example, mycoveoorganizationg8tp8wu3).

If there have been any recent untrusted redirections, you’ll receive a response similar to the following:

{
  "totalCount": 1,
  "items": [
    {
      "uriPrefix": "https://www.example.com",
      "date": "INSERT DATE"
    }
  ]
}

You can use this list to determine which redirections you want to allow.

Configure allowed redirections

To view the current list of trusted URIs, send a GET request to:

https://platform.cloud.coveo.com/rest/organizations/{organizationId}/authentication/trusteduris?page=0&perPage=20

where {organizationId} is the unique identifier of your Coveo organization (for example, mycoveoorganizationg8tp8wu3).

If you haven’t added any trusted URIs yet, you’ll receive an empty array. If you have, you’ll receive a response similar to the following:

{
  "totalCount": 1,
  "items": [
    {
      "id": "371af96a-18a2-11e8-accf-0ed5f89f718b",
      "uriPrefix": "https://www.example.com"
    }
  ]
}

Add a trusted URI

To add a trusted URI, send a POST request to:

https://platform.cloud.coveo.com/rest/organizations/{organizationId}/authentication/trusteduris

where {organizationId} is the unique identifier of your Coveo organization (for example, mycoveoorganizationg8tp8wu3).

Example
POST https://platform.cloud.coveo.com/rest/organizations/mycoveoorganizationg8tp8wu3/authentication/trusteduris HTTP/1.1
​
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************

Payload

{
  "trustedUri": {
    "uriPrefix": "https://www.example.com"
  }
}

201 Created response body

{
  "trustedUri": {
    "id": "371af96a-18a2-11e8-accf-0ed5f89f718b",
    "uriPrefix": "https://www.example.com"
  }
}

Remove a trusted URI

To remove a trusted URI, send a DELETE request to:

https://platform.cloud.coveo.com/rest/organizations/{organizationId}/authentication/trusteduris/{uriId}

where:

  • {organizationId} is the unique identifier of your Coveo organization (for example, mycoveoorganizationg8tp8wu3).

  • {uriId} is the unique identifier of the URI that you want to remove from the list of trusted URIs.

Test your setup

Once you’ve configured your SAML IdP and created your Search API SAML authentication provider, you can test your setup by directing your browser to:

https://platform.cloud.coveo.com/rest/search/v2/login/{provider}?organizationId={organizationId}

where:

Configure for AD FS

Configure a relying party trust in AD FS

To use Active Directory Federation Services (AD FS) as an identity provider (IdP) to authenticate Search API calls through SAML 2.0, you must first configure a Relying Party Trust in the AD FS Microsoft Management Console (MMC) snap-in:

  1. Open the AD FS 2.0 Management console.

  2. Expand the Trust Relationships node.

  3. Select Relying Party Trusts.

  4. In the panel on the right, click Add Relying Party Trust.

  5. In the wizard that opens, click Start.

  6. Select Enter data about the relying party manually, and then click Next.

  7. Enter an appropriate display name, such as Coveo Search API, and then click Next.

  8. Select AD FS 2.0 profile, and then click Next.

  9. Click Next to skip specifying a token encryption certificate.

  10. Check Enable support for the SAML 2.0 WebSSO protocol.

  11. Enter the Relying party SAML 2.0 SSO service URL.

    This URL must point to the Search API SAML authentication provider that you’ll create once your IdP has been configured, and it must include the unique identifier of your Coveo organization in the query string.

    https://platform.cloud.coveo.com/rest/search/v2/login/mySAMLAuthenticationProvider?organizationId=mycoveoorganizationg8tp8wu3
    Important

    If you’ve created a SAML authentication provider for your Coveo organization as a whole, be careful not to confuse this provider with your Search API SAML authentication provider.

  12. Click Next.

  13. Enter the Relying party trust identifier. This can be any string, as long as it matches the relyingPartyIdentifier argument you use when creating your Search API SAML authentication provider.

    Tip
    Leading practice

    Use the Coveo host name when specifying the Relying party trust identifier: https://platform.cloud.coveo.com

  14. Click Add, and then click Next.

  15. Select Permit all users to access this relying party, and then click Next.

  16. Click Next, check the Open the Edit Claim Rules dialog for this relying party trust when the wizard closes, and then click Close.

  17. In the new dialog box that opens, in the Issuance Transform Rules tab, click Add Rule.

  18. In the new wizard that opens, in the Claim rule template dropdown menu, select Send LDAP Attributes as Claims, and then click Next.

  19. In Claim rule name, enter Send Name ID.

  20. In the Attribute store dropdown menu, select Active Directory.

  21. In the table under the dropdown menu, select SAM-Account-Name in the left column and Name ID in the right column.

  22. Click Finish.

  23. Close the dialog by clicking OK.

Download the AD FS XML metadata

On a typical AD FS setup, you can download the XML metadata file from the following address:

https://{myserver}/FederationMetadata/2007-06/FederationMetadata.xml

where you replace {myserver} with the host name of your AD FS server.

The XML metadata contains information such as the certificates that validate the responses. You must use the content of this file as the metadata argument when creating your SAML authentication.

Create an AD FS authentication provider

Follow the standard procedure to create a Search API SAML authentication provider for your AD FS IdP.

You must set:

After you create an authentication provider, you should authorize redirections.

Once your Search API SAML authentication provider has been created and you’ve authorized redirections, you can test your setup.

Configure for Okta

Add an application in Okta

To use Okta as an IdP to authenticate Search API calls through SAML 2.0, you must first add an Application in the Okta administration site. Follow these steps:

  1. Open the Okta administration site.

  2. Click the Add Application shortcut.

  3. Click Create New App.

  4. In the popup, select SAML 2.0, and then click Create.

  5. Enter a suitable name for the application, such as Coveo Search API.

  6. Check the Do not display application icon to users checkbox.

  7. Click Next.

  8. Enter the Single sign-on URL.

    This URL must point to the Search API SAML authentication provider that you’ll create once your IdP has been configured, and it must include the unique identifier of your Coveo organization in the query string.

    https://platform.cloud.coveo.com/rest/search/v2/login/mySAMLAuthenticationProvider?organizationId=mycoveoorganizationg8tp8wu3
    Important

    If you’ve created a SAML authentication provider for your Coveo organization as a whole, be careful not to confuse this provider with your Search API SAML authentication provider.

  9. In Audience URI, enter a suitable relying party identifier.

    Tip
    Leading practice

    Use the Coveo host name as a relying party identifier: https://platform.cloud.coveo.com.

  10. Click Next and complete the wizard.

Download the Okta XML metadata

When viewing your application in the Okta administration site, under the Sign On tab, click the Identity Provider metadata link to download the XML metadata file.

The XML metadata contains information such as the certificates that validate the responses. You must use the content of this file as the metadata argument when creating your SAML authentication.

Create an Okta authentication provider

Follow the standard procedure to create a Search API SAML authentication provider for your Okta IdP.

You must set:

Note

Specifying a relyingPartyIdentifier argument when creating a Search API SAML authentication provider is optional when using Okta as an IdP. However, if provided, the relyingPartyIdentifier parameter should be set to the same value as the Audience URI.

After you create an authentication provider, you should authorize redirections.

Once your Search API SAML authentication provider has been created and you’ve authorized redirections, you can test your setup.