SAML Authentication

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.

It is not currently possible to authenticate calls to the Usage Analytics Write API using a cookie generated by a Search API SAML authentication provider.

Therefore, when SAML authentication is enabled in a search page, you must use a distinct access token to log usage analytics events (i.e., an API key that grants the Analytics data - Edit privilege in the target Coveo Cloud organization.

In a search page that relies on the Coveo JavaScript Search Framework, this implies that you must explicitly specify a value for the token option when configuring the Analytics component. Assuming you specify a valid API key for that option, the component will be able to log usage analytics events anonymously.

Configuring a SAML IdP

Many implementations of the SAML 2.0 standard are available. Each implementation has its own distinct configuration process. This guide provides specific instructions to configure the following IdPs:

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

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} on Coveo Cloud V2, or
  • https://cloudplatform.coveo.com/rest/search/login/{provider}?workgroup={organizationId} on Coveo Cloud V1.

where:

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

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

Creating 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 on Coveo Cloud V2, or
  • https://cloudplatform.coveo.com/rest/organizations/{organizationId}/authentication/saml on Coveo Cloud V1

where you replace {organizationId} with the unique identifier of your Coveo Cloud organization (e.g., mycoveocloudorganizationg8tp8wu3).

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/mycoveocloudorganizationg8tp8wu3/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/mySAMLAuthenicationProvider?organizationId=mycoveocloudorganizationg8tp8wu3",
  "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 Metadata). You can get this metadata from your IdP.

Do not 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} on Coveo Cloud V2 or
  • https//cloudplatform.coveo.com/rest/search/login/{provider}?workgroup={organizationId} on Coveo Cloud V1

where:

  • {provider} is the name of the Search API SAML authentication provider.
  • {organizationId} is the unique identifier of the Coveo Cloud organization.

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

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 Cloud platform hostname as relyingPartyIdentifier:

  • https://platform.cloud.coveo.com on Coveo Cloud V2, or
  • https://cloudplatform.coveo.com on Coveo Cloud V1.

This parameter is not required when using Okta as an IdP (see Configuring SAML for Use with Okta).

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

Testing the Setup

Once you have 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} on Coveo Cloud V2, or
  • https://cloudplatform.coveo.com/rest/search/login/{provider}?workgroup={organizationId} on Coveo Cloud V1

where:

  • {provider} is the name of your Search API SAML authentication provider (see Creating a Search API SAML Authentication Provider with the Coveo Search API).

  • {organizationId} is the unique identifier of your Coveo Cloud organization (e.g., mycoveocloudorganizationg8tp8wu3).

    If you are testing the SAML authentication setup for a Coveo Cloud V1 organization, remember to use the workgroup rather than the organizationId query string parameter to specify the unique identifier of your Coveo Cloud organization.

Recommended Articles