--- title: Configure a SAML identity provider using the Search API slug: '91' canonical_url: https://docs.coveo.com/en/91/ collection: build-a-search-ui source_format: adoc --- # 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 and Coveo's UI libraries support SAML authentication. This article explains how to create a SAML authentication provider using the Coveo Search API. * If you're using the [Coveo Headless library](https://docs.coveo.com/en/lcdf0493/), you can use the [`@coveo/auth`](https://github.com/coveo/ui-kit/tree/main/packages/auth) package to configure SAML authentication for the search engine component. * If you're using the [Coveo JavaScript Search Framework](https://docs.coveo.com/en/187/), you can use the [`AuthenticationProvider`](https://coveo.github.io/search-ui/components/authenticationprovider.html) component to enable SAML authentication. > **Note** > > When performing [queries](https://docs.coveo.com/en/231/) 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](https://docs.coveo.com/en/lcdf0493/) package or [JavaScript Search Framework](https://docs.coveo.com/en/187/) 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: * [AD FS](#configure-for-ad-fs) * [Okta](#configure-for-okta) 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](https://docs.coveo.com/en/assets/images/coveo-platform/search-api-redirections.svg) . The user enters a query in the search box. . The search page sends a call to the Search API at `/rest/search`. > **Important** > > If you're not using the [Headless](https://docs.coveo.com/en/lcdf0493/) `@coveo/auth` package or [JavaScript Search Framework](https://docs.coveo.com/en/187/) `AuthenticationProvider` component, you'll have to add the `authentication=` parameter to the [query](https://docs.coveo.com/en/231/). > 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. . The user's credentials are invalid, so the Search API returns an error. . The search page sends a request 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: ```text https://searchdev.cloud.coveo.com/rest/search/login/mySAMLAuthenticationProvider?organizationId=mycoveoorganizationg8tp8wu3&redirectUri=https://www.example.com ``` . The Search API redirects the user's browser to the third-party authentication provider. . The user logs in to the authentication provider. . The authentication provider sends back an HTML form that automatically makes a POST request to the Search API. . The search page then sends a POST request at `/rest/search/login/handshake`. . The Search API validates the request and redirects the user to the search page with a handshake token. .. The Search API doesn't provide the search token directly, because it might be too long to fit into the URL. .. This redirection uses the URL stored in the `redirectUri` parameter. . Once the handshake is complete, the search page sends a request to the Search API at `/rest/search/login` with the user's authenticated identities to obtain the search token. . The Search API returns a response with the search token. . The authenticated user can now perform queries on the search page. > **Important** > > If you're not using the [Headless](https://docs.coveo.com/en/lcdf0493/) `@coveo/auth` package or [JavaScript Search Framework](https://docs.coveo.com/en/187/) `AuthenticationProvider` component, you'll have to add the `authentication=` parameter to the [query](https://docs.coveo.com/en/231/). > 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](https://docs.coveo.com/en/242/)?organizationId={organizationId}+` where: * `+[provider](https://docs.coveo.com/en/242/)+` is the [`name`](#name-string-required) of your [Search API SAML authentication provider](#create-a-search-api-saml-authentication-provider). * `{organizationId}` is the unique identifier of your [Coveo organization](https://docs.coveo.com/en/185/) (for example, `mycoveoorganizationg8tp8wu3`). You'll also pass this URL to the [`assertionConsumerServiceUrl`](#assertionconsumerserviceurl-string) 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](#create-a-search-api-saml-authentication-provider). **Example** When using `Active Directory` as a [security identity provider](https://docs.coveo.com/en/242/), 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](https://en.wikipedia.org/wiki/SAML_2.0#SAML_2.0_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** ```http POST https://platform.cloud.coveo.com/rest/organizations/mycoveoorganizationg8tp8wu3/authentication/saml HTTP/1.1 ​ Content-Type: application/json Authorization: Bearer **********-****-****-****-************ ``` **Payload** ```json { "name": "mySAMLAuthenticationProvider", "assertionConsumerServiceUrl": "https://platform.cloud.coveo.com/rest/search/v2/login/mySAMLAuthenticationProvider?organizationId=mycoveoorganizationg8tp8wu3", "metadata": " **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](https://en.wikipedia.org/wiki/SAML_2.0#SAML_2.0_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 ``` becomes ```xml ``` and ```xml mUqDy0cEfgTDUGcUcFY1By4n9Y/VsBDFGiH0HwIDAQAB5A0GCSqGSIb3DQEBBQU4BCrTy147Fhcv s1GeQOQvibBc76Q6FuTGQaBrV00nYQByzr8T[...] ``` becomes ```xml mUqDy0cEfgTDUGcUcFY1By4n9Y/VsBDFGiH0HwIDAQAB5A0GCSqGSIb3DQEBBQU4BCrTy147Fhcv\ns1GeQOQvibBc76Q6FuTGQaBrV00nYQByzr8T[...] ``` Sample value (excerpt): `` ### `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](https://docs.coveo.com/en/242/)?organizationId={organizationId}+` where: * `+[provider](https://docs.coveo.com/en/242/)+` is the [`name`](#name-string-required) 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](#authorize-redirections) to improve the security of your Coveo-powered search implementation. > **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](#authorize-redirections) section and create a list of trusted URIs first. Sample value: `true` ### `relyingPartyIdentifier` (string) The [relying party](https://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0-cd-02.html#3.1.SAML%20Participants|outline) identifier. Set this parameter to the corresponding value from your IdP Administration Console. > **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](#configure-for-okta). 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](#view-recent-untrusted-redirections) and [configure allowed redirections](#configure-allowed-redirections). > **Important** > > Untrusted redirections are allowed by default in the Search API. > For now, you must set the [`enforceTrustedUris`](#enforcetrusteduris-boolean) parameter to `true` in your SAML authentication provider to authorize redirections. > > In the future, however, the default behavior will be to prevent untrusted redirections. > 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: ```json { "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: ```json { "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** ```http POST https://platform.cloud.coveo.com/rest/organizations/mycoveoorganizationg8tp8wu3/authentication/trusteduris HTTP/1.1 ​ Content-Type: application/json Authorization: Bearer **********-****-****-****-************ ``` **Payload** ```json { "trustedUri": { "uriPrefix": "https://www.example.com" } } ``` **201 Created response body** ```json { "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. :leveloffset!: ## 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](https://docs.coveo.com/en/242/)?organizationId={organizationId}+` where: * `+[provider](https://docs.coveo.com/en/242/)+` is the [`name`](#name-string-required) of your [Search API SAML authentication provider](#create-a-search-api-saml-authentication-provider). * `{organizationId}` is the unique identifier of your Coveo organization (for example, `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](https://docs.coveo.com/en/2120/) Search API calls through SAML 2.0, 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, such as `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**. . [[relying-party-saml-2_0-sso-service-url]] 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](#create-an-ad-fs-authentication-provider) once your IdP has been configured, and it must include the unique identifier of your Coveo organization in the query string. ```text 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](https://docs.coveo.com/en/1979/). . Click **Next**. . [[relying-party-trust-identifier]] Enter the **Relying party trust identifier**. This can be any string, as long as it matches the [`relyingPartyIdentifier`](#relyingpartyidentifier-string) argument you use when creating your Search API SAML authentication provider. > **Leading practice** > > 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, on 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 under 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 AD FS XML metadata On a typical AD FS setup, you can download the XML metadata file from the following address: ```text https://{myserver}/FederationMetadata/2007-06/FederationMetadata.xml ``` where you replace `{myserver}` with the host name of your AD FS server. The [XML metadata](https://en.wikipedia.org/wiki/SAML_2.0#SAML_2.0_metadata) contains information such as the certificates that validate the responses. You must use the content of this file as the [`metadata`](#metadata-string-required) argument when [creating your SAML authentication](#create-an-ad-fs-authentication-provider). ### Create an AD FS authentication provider Follow the standard procedure to [create a Search API SAML authentication provider](#create-a-search-api-saml-authentication-provider) for your AD FS IdP. You must set: * The [`assertionConsumerServiceUrl`](#assertionconsumerserviceurl-string) parameter to [the same value](#relying-party-saml-2_0-sso-service-url) as the **Relying party SAML 2.0 SSO service URL**. * The [`relyingPartyIdentifier`](#relyingpartyidentifier-string) parameter to [the same value](#relying-party-trust-identifier) as the **Relying party trust identifier**. * The [`metadata`](#metadata-string-required) parameter to the properly escaped content of the [XML metadata file](#download-the-ad-fs-xml-metadata). After you create an authentication provider, you should [authorize redirections](#authorize-redirections). Once your Search API SAML authentication provider has been created and you've authorized redirections, you can [test your setup](#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, 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, such as `Coveo Search API`. . Check the **Do not display application icon to users** checkbox. . Click **Next**. . [[single-sign-on-url]] Enter the **Single sign-on URL**. This URL must point to the Search API SAML authentication provider [that you'll create](#create-an-okta-authentication-provider) once your IdP has been configured, and it must include the unique identifier of your Coveo organization in the query string. ```text 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](https://docs.coveo.com/en/1979/). . [[audience-uri]] In **Audience URI**, enter a suitable relying party identifier. > **Leading practice** > > Use the Coveo host name as a relying party identifier: `+https://platform.cloud.coveo.com+`. . 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](https://en.wikipedia.org/wiki/SAML_2.0#SAML_2.0_metadata) contains information such as the certificates that validate the responses. You must use the content of this file as the [`metadata`](#metadata-string-required) argument when [creating your SAML authentication](#create-an-okta-authentication-provider). ### Create an Okta authentication provider Follow the standard procedure to [create a Search API SAML authentication provider](#create-a-search-api-saml-authentication-provider) for your Okta IdP. You must set: * The [`assertionConsumerServiceUrl`](#assertionconsumerserviceurl-string) parameter to [the same value](#single-sign-on-url) as the **Single sign-on URL**. * The [`metadata`](#metadata-string-required) parameter to the properly escaped content of the [XML metadata file](#download-the-okta-xml-metadata). > **Note** > > Specifying a [`relyingPartyIdentifier`](#relyingpartyidentifier-string) 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](#audience-uri) as the **Audience URI**. After you create an authentication provider, you should [authorize redirections](#authorize-redirections). Once your Search API SAML authentication provider has been created and you've authorized redirections, you can [test your setup](#test-your-setup).