Managing Batches of Security Identities

It is 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 forward many push operations to the service using only a few Push API calls, rather than performing hundreds (or thousands) of individual Push API calls to achieve the same results. Managing security identities in batches is thus 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).

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

Step 1 - Create a File Container

See Creating a File Container.

Step 2 - Upload the Security Identity Update into the File Container

Perform the following PUT request to upload the push operations required for your security identity update into the Amazon S3 file container you got from Step 1 - Create a File Container.

Request template

PUT <MyUploadURI> HTTP/1.1
 
<HTTPHeaders>

Payload (see Security Identity Models - BatchIdentityModel)

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

Replace:

  • <MyUploadUri> with the value of the uploadUri property you got in the response when you created your file container in Step 1 - Create a File Container.

  • <HTTPHeaders> with the keys-value pairs of the requiredHeaders object property you got in the response when you created your file container in Step 1 - Create a File Container.

In the request body (see Security Identity Models - BatchIdentityModel):

You must make consistent use of the wellKnowns parameter among different push API calls. That is, for any API operation which sets wellKnowns, like Adding or Updating a Single Security Identity or Adding or Updating 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).

A successful response (200 OK) has no content, but indicates that security identity update push operations were successfully uploaded into the Amazon S3 file container.

Sample Request

Uploading a batch of security identity update operations into a file container

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

Payload

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

Successful response - 200 OK

{}

Step 3 - Push the File Container into a Security Identity Provider

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

Request template

PUT https://api.cloud.coveo.com/push/v1/organizations/<MyOrganizationId>/providers/<MySecurityIdentityProviderId>/permissions/batch?fileId=<MyFileId> HTTP/1.1
 
Content-Type: application/json
Accept: application/json
Authorization: Bearer <MyAccessToken>

Payload

{}

For legacy reasons, the request path of this operation includes the word permissions instead of identities. While those two concepts are related, they have entirely different meanings.

Remember that this operation actually allows you to interact with security identities (not item permissions).

In the request path:

In the query string:

In the Authorization HTTP header:

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 (i.e., it has been disabled), but one or several item permission models still refer to it. To address this error, you must perform the necessary push operations on the secured Push source to ensure that item permission models and security identities are perfectly in sync.

Sample Request

Pushing 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
 
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************

Payload

{}

Successful response - 202 Accepted

null
Recommended Articles