Manage batches of security identities

This is for:

Developer System Administrator

It’s possible to add, update, and/or disable batches of security identities in the security identity provider of a secured Push source.

This means that you can update many security identities using only a few Push API requests, rather than performing numerous single security identity requests to achieve the same results. Therefore, managing security identities in batches is the best way to ensure that you never get throttled by the service. See Push API limits - Recommended maximum number of items/security identities per hour for details.

Performing batch security identity update requests is slightly more complex than performing single security identity requests, as doing so involves three distinct steps which are detailed in this article.

Step 1: Create a file container

See Create a file container for details.

Step 2: Upload the security identity update into the file container

Perform the following PUT uploadUri request to upload the security identity update into the Amazon S3 file container obtained in step 1.

Request template

PUT <MyUploadURI> HTTP/1.1
​
<HTTPHeaders>
Parameters

  • Replace <MyUploadUri> with the value of the uploadUri property you got in the response when you created your file container in step 1.

  • Replace <HTTPHeaders> with the key-value pairs of the requiredHeaders object property you got in the response when you created your file container in step 1.

Request body:

{
  "members": [
    <MySecurityIdentityDefinition>*
  ],
  "mappings": [
    <MyUserAliasDefinition>*
  ],
  "deleted": [
    {
      "identity": {
        "name": <MySecurityIdentityName>,
        "type": <"GROUP"|"UNKNOWN"|"USER"|"VIRTUAL_GROUP">
      }
    }*
  ]
}
Parameters

The request body must implement the BatchIdentityBody model.

In the members array:

  • Replace <MySecurityIdentityDefinition>* with any number of security identity definitions to add or update in the target security identity provider.

    Important

    When pushing a group, you overwrite the current version of that group. Therefore, to keep existing group members, be sure to include them in the new group configuration. If this isn’t viable, consider using granted security identities instead.

In the mappings array:

  • Replace <MyUserAliasDefinition>* with any number of user alias definitions to add or update in the target security identity provider.

In the deleted array:

  • Replace <MySecurityIdentityName> by the name of the security identity to disable for each security identity you include.

  • Replace <"GROUP"|"UNKNOWN"|"USER"|"VIRTUAL_GROUP"> by the corresponding entity type.

Important

Make consistent use of the wellKnowns parameter among different push API calls. In other words, for any API request which sets wellKnowns, like Add or update a single security identity or Add or update a single alias, make sure that the same wellKnowns are also sent when using that call to prevent involuntary disassociation of granted identities from their groups. See Group and granted security identities for details.

Successful response: 200 OK

{}

A successful response has no content, but indicates that the security identity update was successfully uploaded into the Amazon S3 file container.

Sample request

The following example shows how to upload a batch of security identity updates into a file container.

PUT link:https://coveo-nprod-customerdata.s3.amazonaws.com/proda/blobstore/mycoveocloudv2organizationg8tp8wu3/b5e8767e-8f0d-4a89-9095-1127915c89c7[...] HTTP/1.1
​
x-amz-server-side-encryption: AES256
Content-Type: application/octet-stream

Request body:

{
  "members": [
    {
      "identity": {
        "name": "SampleGroup",
        "type": "GROUP"
      },
      "members": [
        {
          "name": "asmith@example.com",
          "type": "USER"
        },
        // ...More members for this group...
      ],
      "wellKnowns": [
        {
          "name": "Domain Users",
          "type": "GROUP"
        },
        // ...More granted identities for this group...
      ]
    },
    // ...More security identity definitions...
  ],
  "mappings": [
    {
      "identity": {
        "name": "asmith@example.com",
        "type": "USER"
      },
      "mappings": [
        {
          "name": "alice_smith@example.com",
          "type": "USER",
          "provider": "Email Security Provider"
        },
        // ...More aliases for this user...
      ],
      "wellKnowns": [
        {
          "name": "Everyone",
          "type": "GROUP"
        },
        // ...More granted identities for this alias...
      ]
    },
    // ...More alias definitions...
  ],
  "deleted": [
    {
      "identity": {
        "name": "SampleGroup2",
        "type": "GROUP"
      }
    },
    {
      "identity": {
        "name": "bjones_alias",
        "type": "USER"
      }
    }
    // ...More security identities to disable...
  ]
}

Step 3: Push the file container into a security identity provider

Use the Add, update, and/or delete a batch of security identities request to push the Amazon S3 file container into the security identity provider of your secured Push source.

Request template

US East region 
PUT https://api.cloud.coveo.com/push/v1/organizations/<MyOrganizationId>/providers/<MySecurityIdentityProviderId>/permissions/batch?fileId=<MyFileId> HTTP/1.1
​
Accept: application/json
Authorization: Bearer <MyAccessToken>
Canada region 
PUT https://api-ca.cloud.coveo.com/push/v1/organizations/<MyOrganizationId>/providers/<MySecurityIdentityProviderId>/permissions/batch?fileId=<MyFileId> HTTP/1.1
​
Accept: application/json
Authorization: Bearer <MyAccessToken>
Ireland region 
PUT https://api-eu.cloud.coveo.com/push/v1/organizations/<MyOrganizationId>/providers/<MySecurityIdentityProviderId>/permissions/batch?fileId=<MyFileId> HTTP/1.1
​
Accept: application/json
Authorization: Bearer <MyAccessToken>
Australia region 
PUT https://api-au.cloud.coveo.com/push/v1/organizations/<MyOrganizationId>/providers/<MySecurityIdentityProviderId>/permissions/batch?fileId=<MyFileId> HTTP/1.1
​
Accept: application/json
Authorization: Bearer <MyAccessToken>

Request parameters:

Parameters

In the request path:

In the query string:

  • Replace <MyFileId> by the filedId you got from step 1.

In the Authorization HTTP header:

Request body:

{}

You may notice that certain security identities in a security identity provider are in error. Typically, this is because the security identity no longer exists in the security identity provider (that is, it has been disabled), but one or several item permission models still refer to it.

To address this error, perform the necessary push requests on the secured Push source to ensure that item permission models and security identities are perfectly in sync.

Tip

The contents of a file container can be pushed to multiple security identity providers or sources in the same Coveo organization. Just update the target providerId/sourceId and Authorization HTTP header access token in your other security identity or item batch requests.

The file container remains available for 4 days.

Sample request

This example shows how to push a file container into the security identity provider of a secured Push source.

PUT https://api.cloud.coveo.com/push/v1/organizations/mycoveocloudv2organizationg8tp8wu3/providers/My%20Secured%20Push%20Source%20Security%20Identity%20Provider/permissions/batch?fileId=b5e8767e-8f0d-4a89-9095-1127915c89c7 HTTP/1.1
​
Accept: application/json
Authorization: Bearer **********-****-****-****-************

Request body:

{}