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 supports SAML authentication, and the AuthenticationProvider component allows you to easily enable SAML authentication in a search page that relies on the Coveo JavaScript Search Framework. For the Coveo Headless library, the @coveo/auth package can be used to configure SAML for the search engine component.

This article explains how to create a SAML Authentication provider using the Coveo Search API.

Configure a SAML IdP

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

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

Assertion URL

At some point during the IdP configuration process, you will likely have to specify the URL where 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 will 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 (see Create a Search API SAML Authentication Provider).

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 a Search API SAML authentication provider requires comes from the SAML Metadata which your IdP can deliver (see SAML Metadata).

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 (e.g., mycoveoorganizationg8tp8wu3).

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

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

Payload

{
  "name": "mySAMLAuthenticationProvider",
  "provider": "Email Security Provider",
  "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
}

201 Created response body

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

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 (see SAML 2.0 Metadata). You can get this metadata from your IdP.

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.

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

provider (String, Required)

The name of the security identity provider. Set this parameter to the corresponding value from your IdP Administration Console.

Sample value: Email Security Provider

assertionConsumerServiceUrl (String)

The URL the browser should redirect to after the end 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

relyingPartyIdentifier (String)

The relying party identifier (see Relying Party). Set this parameter to the corresponding value from your IdP Administration Console.

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 (see Configure SAML for Use with Okta).

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

Test the Setup

Once you’ve configured your SAML IdP and created your Search API SAML authentication provider, you can test the 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 (e.g., 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 you will create once your IdP has been configured, and it must include the unique identifier of your Coveo organization in the query string (see Create an Authentication Provider).

    Coveo Relying party SAML 2.0 SSO service URL

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

    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.

    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 below 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 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 (see SAML 2.0 Metadata). You must use the content of this file as the metadata argument when creating your SAML authentication (see Create an Authentication Provider).

Create an authentication provider

Follow the standard procedure for creating a Search API SAML authentication provider for your AD FS IdP (see Create a Search API SAML Authentication Provider).

You must set:

Once your Search API SAML authentication provider has been successfully created, 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 (e.g., 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 you will create once your IdP has been configured (see Create an Authentication Provider) and 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

    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.

    A good choice is to use the Coveo host name as a relying party identifier: https://platform.cloud.coveo.com

  10. Click Next and complete the wizard.

Download the 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 (see SAML 2.0 Metadata). You must use the content of this file as the metadata argument when creating your SAML authentication (see Create an Authentication Provider).

Create an authentication provider

Follow the standard procedure to create a Search API SAML authentication provider for your Okta IdP (see Create a Search API SAML Authentication Provider).

Keep in mind that you must set:

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 (see Add an Application in Okta - Step 9).

Once your Search API SAML authentication provider has been successfully created, you can test your setup by following the standard procedure (see Test the Setup).