Configure a SAML identity provider using the Search API
Configure a SAML identity provider using the Search API
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:
-
{provider}
is thename
of your Search API SAML authentication provider (see Create a Search API SAML Authentication Provider). -
{organizationId}
is the unique identifier of your Coveo organization (e.g.,mycoveoorganizationg8tp8wu3
).
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 thename
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:
-
{provider}
is thename
of your Search API SAML authentication provider (see Create a Search API SAML Authentication Provider with the Coveo Search API). -
{organizationId}
is the unique identifier of your Coveo organization (e.g.,mycoveoorganizationg8tp8wu3
).
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:
-
Open the AD FS 2.0 Management console.
-
Expand the Trust Relationships node.
-
Select Relying Party Trusts.
-
In the panel on the right, click Add Relying Party Trust.
-
In the wizard that opens, click Start.
-
Select Enter data about the relying party manually, and then click Next.
-
Enter an appropriate display name (e.g.,
Coveo Search API
), and then click Next. -
Select AD FS 2.0 profile, and then click Next.
-
Click Next to skip specifying a token encryption certificate.
-
Check Enable support for the SAML 2.0 WebSSO protocol.
-
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.
-
Click Next.
-
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
-
Click Add, and then click Next.
-
Select Permit all users to access this relying party, and then click Next.
-
Click Next, check the Open the Edit Claim Rules dialog for this relying party trust when the wizard closes, and then click Close.
-
In the new dialog box that opens, in the Issuance Transform Rules tab, click Add Rule.
-
In the new wizard that opens, in the Claim rule template dropdown menu, select Send LDAP Attributes as Claims, and then click Next.
-
In Claim rule name, enter Send Name ID.
-
In the Attribute store dropdown menu, select Active Directory.
-
In the table below the dropdown menu, select SAM-Account-Name in the left column and Name ID in the right column.
-
Click Finish.
-
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:
-
The
assertionConsumerServiceUrl
parameter to the same value as the Relying party SAML 2.0 SSO service URL (see step 11). -
The
relyingPartyIdentifier
parameter to the same value as the Relying party trust identifier (see step 13). -
The
metadata
parameter to the properly escaped content of the XML metadata file (see Downloading the XML Metadata).
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:
-
Open the Okta administration site.
-
Click the Add Application shortcut.
-
Click Create New App.
-
In the popup, select SAML 2.0, and then click Create.
-
Enter a suitable name for the application (e.g.,
Coveo Search API
). -
Check the Do not display application icon to users checkbox.
-
Click Next.
-
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.
-
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
-
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:
-
The
assertionConsumerServiceUrl
parameter to the same value as the Single sign on URL (see Add an Application in Okta - Step 8) -
The
metadata
parameter to the properly escaped content of the XML metadata file (see Download the XML Metadata).
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).