--- title: Create or update a security identity provider for a secured Push source slug: '85' canonical_url: https://docs.coveo.com/en/85/ collection: index-content source_format: adoc --- # Create or update a security identity provider for a secured Push source The [security identity provider](https://docs.coveo.com/en/242/) of a Push [source](https://docs.coveo.com/en/246/) that [indexes the permissions](https://docs.coveo.com/en/1779#same-users-and-groups-as-in-your-content-system) (`"sourceVisibility" "SECURED"`) contains the definition of each [security identity](https://docs.coveo.com/en/240/) that can be referenced in the [permission model](https://docs.coveo.com/en/225/) of any given item in that source. See [Security identity definition examples](https://docs.coveo.com/en/42/) and [Simplified permission model](https://docs.coveo.com/en/107/) for examples. Once you've [created a secured Push source](https://docs.coveo.com/en/1546/), the next logical step is to create a security identity provider for that source to replicate the security model of the secured enterprise system you want to index. Coveo offers a [POST request to create a security identity provider](#create-a-security-provider), and a [PUT request to update a security provider](#update-a-security-provider). ## Create a security provider This [POST request](https://platform.cloud.coveo.com/docs?urls.primaryName=SecurityCache#/Security%20Providers/rest_organizations_paramId_securityproviders_post) creates a security identity provider and associates it to your Push source. **Request template:** ```http POST https://platform.cloud.coveo.com/rest/organizations//securityproviders HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer ``` Payload: ```json { "id" : , "displayName" : , "nodeRequired": false, "type": "EXPANDED", "referencedBy": [ { "id": , "type": "SOURCE" } ], "cascadingSecurityProviders": { "EmailSecurityProvider": { "id": "Email Security Provider", "type": "EMAIL" } } } ``` **Request and payload details**
Details Request: * **Organization ID:** Replace `` with your [organization ID](https://docs.coveo.com/en/148/). * Replace `` with an access token that grants the **Security identity providers - View/Edit** [privilege](https://docs.coveo.com/en/228/). See [Create an API key](https://docs.coveo.com/en/1718#create-an-api-key), [Get the privileges of an access token](https://docs.coveo.com/en/109/), and [Get your Coveo access token](https://docs.coveo.com/en/123/) for details. Payload: * `id`: Replace `` with the desired security identity provider ID. [TIP] **Leading practice**
A good practice is to include the name of the associated secured Push source in the security identity provider name. #### * `displayName`: Replace `` with the desired security identity provider name. This name appears in the Coveo Administration Console and can be edited. If you edit `displayName`, it won't change the URL in the Coveo Administration Console. * `referencedBy`: Replace `` with the [ID](https://docs.coveo.com/en/3390#copy-a-source-name-or-id) of the secured [Push source](https://docs.coveo.com/en/1546/) you want to associate this security identity provider with. > **Leading practice** > > Including your `cascadingSecurityProviders` sub-object in your request body and cascading your security identity provider to the [Email Security Provider](https://docs.coveo.com/en/87/) is recommended as it may be required depending upon how the user authentication is set up. Moreover, it allows you to conveniently define aliases between user entities that share the same email address in different secured enterprise systems. > > For example, a Coveo organization has three secured sources of secured content: > > . A Google Drive source. > > . A Salesforce source. > > . A Push source. > > Each source has its own security identity provider, which cascades to the Email Security Provider. > > Users have a distinct account in each system, but in all three cases, their account name is their corporate email address. > > Alice Smith, whose corporate email address is `asmith@example.com`, authenticates as the owner of a Google Drive identity to execute a query against the Coveo organization [index](https://docs.coveo.com/en/204/). > In the Email Security Provider, the Google Drive identity resolves to the `asmith@example.com` corporate email address, which also maps to the identity in the Push source system, and in Salesforce. > Consequently, even though Alice has only authenticated using the Google Drive account, she can get [query](https://docs.coveo.com/en/231/) result [items](https://docs.coveo.com/en/210/) from content she has access to in any of the three secured sources. ##### The body of a successful request (`200 OK`) contains information about the security identity provider that was created. ## Update a security provider This [PUT request](https://platform.cloud.coveo.com/docs?urls.primaryName=SecurityCache#/Security%20Providers/rest_organizations_paramId_securityproviders_paramId_put) updates a security identity provider that's associated to your Push source. **Request template:** ```http PUT https://platform.cloud.coveo.com/rest/organizations//securityproviders/ HTTP/1.1 ​ Content-Type: application/json Accept: application/json Authorization: Bearer ``` Payload: ```json { "id" : , "displayName" : , "type": "EXPANDED", "nodeRequired": false, "cascadingSecurityProviders": { "EmailSecurityProvider": { "id": "Email Security Provider", "type": "EMAIL" } }, "referencedBy": [ { "type": "SOURCE", "id": } ] } ``` **Request and payload details**
Details Request: * **Organization ID:** Replace `` with your [organization ID](https://docs.coveo.com/en/148/). * **Security Provider ID**: Replace `` with the desired security identity provider ID. * Replace `` with an access token that grants the **Security identity providers - Edit** [privilege](https://docs.coveo.com/en/228/). See [Create an API key](https://docs.coveo.com/en/1718#create-an-api-key), [Get the privileges of an access token](https://docs.coveo.com/en/109/), and [Get your Coveo access token](https://docs.coveo.com/en/123/) for details. Payload: * `id`: Replace `` with the desired security identity provider ID. `name` is deprecated. * `displayName`: Replace `` with the desired security identity provider name. This name appears in the Coveo Administration Console and can be edited. If you edit `displayName`, it won't change the URL in the Coveo Administration Console. * `referencedBy`: Replace `` with the [ID](https://docs.coveo.com/en/3390#copy-a-source-name-or-id) of the secured [Push source](https://docs.coveo.com/en/1546/) you want to associate this security identity provider with. [TIP] **Leading practice**
Including your `cascadingSecurityProviders` sub-object in your request body and cascading your security identity provider to the [Email Security Provider](https://docs.coveo.com/en/87/) is recommended as it may be required depending upon how the user authentication is set up. Moreover, it allows you to conveniently define aliases between user entities that share the same email address in different secured enterprise systems. For example, a Coveo organization has three secured sources of secured content: . A Gmail for Work source. . A Salesforce source. . A Push source. Each source has its own security identity provider, which cascades to the Email Security Provider. Users have a distinct account in each system, but in all three cases, their account name is their corporate email address. Alice Smith, whose corporate email address is `asmith@example.com`, authenticates as the owner of a Gmail for Work identity to execute a query against the Coveo organization [index](https://docs.coveo.com/en/204/). In the Email Security Provider, the Google for Work identity resolves to the `asmith@example.com` corporate email address, which also maps to the identity in the Push source system, and in Salesforce. Consequently, even though Alice has only authenticated using the Gmail for Work account, she can get [query](https://docs.coveo.com/en/231/) result [items](https://docs.coveo.com/en/210/) from content she has access to in any of the three secured sources. #### ===== The body of a successful request (`200 OK`) contains information about the security identity provider that was created. ### Sample request **Creating a security identity provider for a given secured Push source** ```http POST https://platform.cloud.coveo.com/rest/organizations/mycoveocloudv2organizationg8tp8wu3/securityproviders HTTP/1.1 ​ Content-Type: application/json Accept: application/json Authorization: Bearer **********-****-****-****-************ ``` Payload: ```json { "id" : "My Secured Push Source Security Identity Provider", "nodeRequired": false, "type": "EXPANDED", "referencedBy": [ { "id": "mycoveocloudv2organizationg8tp8wu3-rp5rxzbdz753uhndklv2ztkfgy", "type": "SOURCE" } ], "cascadingSecurityProviders": { "Email Security Provider": { "id": "Email Security Provider", "type": "EMAIL" } } } ``` **Successful response - 200 OK:** ```json { "id": "My Secured Push Source Security Identity Provider", "name": "My Secured Push Source Security Identity Provider", "displayName": "My Secured Push Source Security Identity Provider", "organizationClusterId": "mycoveocloudv2organizationg8tp8wu3-x3xz5hehgtdarowotab2oekcwa", "type": "EXPANDED", "nodeRequired": false, "caseSensitive": false, "parameters": {}, "cascadingSecurityProviders": { "Email Security Provider": { "id": "Email Security Provider", "name": "Email Security Provider", "type": "EMAIL" } }, // ...More information about the newly created security identity provider... } ``` ## `SECURITY_PROVIDER_INVALID_CONFIGURATION` error When creating or updating a security identity provider through the API, you might get a `SECURITY_PROVIDER_INVALID_CONFIGURATION` error. Possible causes are: . Your security identity provider id or name is too long. Provide an id or name consisting of 255 characters or less. . Your security identity provider configuration is invalid because it contains more than one reference to the same resource. A security identity provider can reference a resource only once. . Your [cascading security identity provider](#create-a-security-provider) doesn't exist. Ensure that the id or name you provided is valid. . Your security identity provider id or name is reserved for internal use.