Create a security identity provider for a secured Push source

Index Content Coveo Relevance Cloud Developer System Administrator Product Documentation

The security identity provider of a Push source that indexes the permissions ("sourceVisibility" "SECURED") 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 Create a Push Source), 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.

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:

  • Replace <MyOrganizationId> with the ID of the target Coveo organization (see Retrieve the Organization ID).

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

    This name must be identical to <MySecurityIdentityProviderName> in the request body.

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.

    Note

    You can’t 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 ID of the secured Push source you want to associate this security identity provider with.

Tip
Leading practice

Although doing so is optional, you should include 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 (see About the Email Security Provider).

For example, a Coveo organization has three secured sources of secured 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 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...
}

"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:

  1. Your security identity provider name is too long. Provide a name consisting of 255 characters or less.

  2. 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.

  3. Your cascading security identity provider doesn’t exist. Ensure that the name you provided is valid.

  4. Your security identity provider name is reserved for internal use.