Create or update a security identity provider for a secured Push source

This is for:

Developer System Administrator

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 for examples.

Once you’ve created a secured 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.

Coveo offers a POST call to create a security identity provider, and a PUT call to update a security provider.

Create a security provider

This POST call creates a security identity provider and associates it to your Push source.

Request template:

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

Payload:

{
  "id" : <MySecurityIdentityProviderId>,
  "displayName" : <MySecurityIdentityProviderDisplayName>,
  "nodeRequired": false,
  "type": "EXPANDED",
  "referencedBy": [
    {
      "id": <MyPushSourceId>,
      "type": "SOURCE"
    }
  ],
  "cascadingSecurityProviders": {
      "EmailSecurityProvider": {
        "id": "Email Security Provider",
        "type": "EMAIL"
    }
  }
}
Request and payload details

Request:

Payload:

  • id: Replace <MySecurityIdentityProviderId> 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 <MySecurityIdentityProviderDisplayName> 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 <MyPushSourceId> with the ID of the secured Push source 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 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:

    1. A Google Drive 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 Google Drive identity to execute a query against the Coveo organization index. In the Email Security Provider, her Google Drive 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 Google Drive 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.

Update a security provider

This PUT call updates a security identity provider that’s associated to your 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:

{
  "id" : <MySecurityProviderId>,
  "displayName" : <MySecurityIdentityProviderDisplayName>,
  "type": "EXPANDED",
  "nodeRequired": false,
  "cascadingSecurityProviders": {
    "EmailSecurityProvider": {
      "id": "Email Security Provider",
      "type": "EMAIL"
    }
  },
  "referencedBy": [
    {
      "type": "SOURCE",
      "id": <MyPushSourceId>
    }
  ]
}
Request and payload details

Request:

Payload:

  • id: Replace <MySecurityIdentityProviderId> with the desired security identity provider ID. name is deprecated.

  • displayName: Replace <MySecurityIdentityProviderDisplayName> 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 <MyPushSourceId> with the ID of the secured Push source 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 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:

    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

POST https://platform.cloud.coveo.com/rest/organizations/mycoveocloudv2organizationg8tp8wu3/securityproviders HTTP/1.1
​
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************

Payload:

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

{
  "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 id or name is too long. Provide an id or 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 id or name you provided is valid.

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