Skip to end of metadata
Go to start of metadata

In this topic:

Many Single Sign-On (SSO) systems use the SAML 2.0 standard to allow external services to rely on the authentication that a central Identity Provider (IdP) entity delivers. The Coveo Search API supports SAML authentication. In addition, the Coveo JavaScript Search Framework provides a component to enable SAML authentication in search pages (see the AuthenticationProvider component).

Important:

It is not currently possible to log usage analytics events in the Coveo Cloud V2 platform using a cookie generated by a Search API SAML provider.

If you are using SAML authentication in your search page, you must therefore specify a distinct access token when logging usage analytics events (i.e., an API key with the Analytics data - Edit privilege).

In a Coveo JavaScript Search Framework search page, this implies that you must specify a value for the token option of your Analytics component. Usage analytics events will then be logged anonymously.


Configuring SAML Authentication

Configuring SAML authentication involves configuring a SAML IdP and creating a SAML Authentication Provider using the Coveo Search API.

Configuring your SAML IdP

Many implementations of the SAML 2.0 standard are available. Each implementation has its own distinct configuration process. See your product documentation for specific information on how to configure your IdP.

Specific instructions for certain identity providers are available

Icon

At some point during your IdP configuration process, you may have to specify the URL where to send the SAML assertions. This URL has the following format: https://platform.cloud.coveo.com/rest/search/login/{provider}, where you must replace {provider} with the name of your SAML authentication provider (see Creating a SAML Authentication with the Coveo Search API).

During IdP configuration, it is also likely that you must define the username format to return when a user successfully authenticates. Make sure you select a format that suits your SAML authentication provider.

Example:
When using an Active Directory security provider, an acceptable username format would be domain\user or user@domain.

Obtaining the SAML Metadata

Most of the configuration that the Coveo Search API requires comes from the SAML Metadata which your IdP can deliver (see SAML Metadata). The metadata should be stored in an XML file that will be referenced in the Windows Service Configuration File.

Creating a SAML Authentication Provider with the Coveo Search API

To configure a SAML authentication provider, you must send a POST request to https://platform.cloud.coveo.com/rest/organizations/{organizationId}/authentication/saml where you must replace {organizationId} by your Coveo Cloud V2 organization ID. The body of your POST request should look like the following example.

Example:
Typical Body of a SAML Authentication Provider POST Request

Parameters

Icon

name (string): Specifies the name of the SAML authentication provider. This value should match the last part of the assertionConsumerServiceUrl path.

provider (string): Specifies the name of the security provider. This value should match the corresponding value from your IdP administration console.

assertionConsumerServiceUrl (string): Specifies the URI where the browser should redirect after the user authenticates. The last part of the path of this value should match the name parameter value.

metadata (string): Specifies the SAML XML Metadata (see SAML Metadata). You can get this metadata from your IdP.

relyingPartyIdentifier (string): Specifies the relying party identifier (see Relying Party). This value should match the corresponding value from your IdP administration console. Specifying a value for this parameter is not mandatory when using Okta as an IdP.

expiration (number): Specifies how much time (in milliseconds) it takes for the browser cookie that stores the SAML information to expire. If you set this parameter to 0, the cookie expires at the end of a browser session.

Icon

Do not forget to escape all double quote (") characters with backslashes (\) in the XML value of the metadata parameter.

 Also remember to add the mandatory new lines (\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>

A successful request returns a Status 201 Created containing the id of the SAML authentication.

Example:
A sample successful SAML authentication creation POST response

You can create multiple SAML authentication providers if necessary. However, in most cases, a single SAML authentication provider is sufficient.

Testing the Setup

Once you have created your SAML authentication provider using the Coveo Search API and configured your SAML IdP, you can test the setup by directing your browser to https://platform.cloud.coveo.com/rest/search/login/{provider}, where you must replace {provider} with the name of your SAML authentication provider (see Creating a SAML Authentication Provider with the Coveo Search API). You should also specify your access_token in the query string.

If everything is setup properly, the Coveo Search API should return a statusCode 200 containing a success message, along with the name of the user who authenticated.

Example:
Testing the setup
  • No labels