Creating a Security Identity Provider for a Secured Push Source

The security identity provider of a secured Push source contains the definition of each security identity that can be referenced in the permission model of any given item in that source (see Security Identity Definition Examples and Simple Permission Model Definition Examples).

When you create a secured Push source (see Creating a Push Source), the next logical step is to create a security identity provider for that source in order to be able to replicate the security model of the secured enterprise system you want to index.

Use the Create or update a security provider for an organization operation to create a security identity provider and associate it to a secured Push source.

Request template

PUT https://platform.cloud.coveo.com/rest/organizations/<MyOrganizationId>/securityproviders/<MySecurityProviderId> HTTP/1.1
 
Content-Type: application/json
Accept: application/json
Authorization: Bearer <MyAccessToken>

Payload

{
  "name" : <MySecurityIdentityProviderName>,
  "nodeRequired": false,
  "type": "EXPANDED",
  "referencedBy": [
    {
      "id": <MyPushSourceId>,
      "type": "SOURCE"
    }
  ],
  "cascadingSecurityProviders": {
      "EmailSecurityProvider": {
        "name": "Email Security Provider",
        "type": "EMAIL"
    }
  }
}

In the request path:

In the Authorization HTTP header:

In the request body:

  • Replace <MySecurityIdentityProviderName> with the desired security identity provider name.

    This name must be identical to <MySecurityProviderId> in the request path.

    You cannot change the name of a security identity provider once it has been created, so make sure you choose a meaningful one.

    A good strategy is to include the name of the associated secured Push source in the security identity provider name.

  • In the referencedBy array, replace <MyPushSourceId> with the actual ID of the secured Push source you want to associate this security identity provider to (see Creating a Push Source and Retrieving the ID of a Source).

Although doing so is optional, you should be including the cascadingSecurityProviders sub-object in your request body and cascading your security identity provider to the Email Security Provider, as it allows you to conveniently define aliases between user entities that share the same email address in different secured enterprise systems.

A Coveo Cloud organization has three secured sources of content:

  1. A Gmail for Work source.
  2. A Salesforce source.
  3. 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 her Gmail for Work identity to execute a query against the Coveo Cloud organization index. In the Email Security Provider, her Google for Work identity resolves to the asmith@example.com corporate email address, which also maps to her identity in the Push source system, and in Salesforce. Consequently, even though Alice has only authenticated using her Gmail for Work account, she can get query result items 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

PUT https://platform.cloud.coveo.com/rest/organizations/mycoveocloudv2organizationg8tp8wu3/securityproviders/My%20Secured%20Push%20Source%20Security%20Identity%20Provider HTTP/1.1
 
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************

Payload

{
  "name" : "My Secured Push Source Security Identity Provider",
  "nodeRequired": false,
  "type": "EXPANDED",
  "referencedBy": [
    {
      "id": "mycoveocloudv2organizationg8tp8wu3-rp5rxzbdz753uhndklv2ztkfgy",
      "type": "SOURCE"
    }
  ],
  "cascadingSecurityProviders": {
    "Email Security Provider": {
      "name": "Email Security Provider",
      "type": "EMAIL"
    }
  }
}

Successful response - 200 OK

{
  "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...
}