Manage Batches of Security Identities

This is for:

In this article

Step 1: Create a File Container
Step 2: Upload the Security Identity Update into the File Container
Step 3: Push the File Container into a Security Identity Provider

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 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. Therefore, Manage 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).

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

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

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

In the members array Security Identity Models - IdentityBody):
- Replace <MySecurityIdentityDefinition>* by any number of security identity definitions to add or update in the target security identity provider (see Security Identity Definition Examples).
In the mappings array (see Security Identity Models - MappedIdentityBody):
- Replace <MyUserAliasDefinition>* by any number of user alias definitions to add or update in the target security identity provider (see User Alias Definition Examples).
For each security identity you include in the deleted array (see Security Identity Models - BaseIdentityBody):
- Replace <MySecurityIdentityName> by the name of the security identity to disable.
  
  The security identities included in the deleted array won’t actually be deleted, but rather disabled in the security identity cache.
- Replace <"GROUP"|"UNKNOWN"|"USER"|"VIRTUAL_GROUP"> by the corresponding entity type.

You must make consistent use of the wellKnowns parameter among different push API calls. In other words, for any API operation 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).

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

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:

Replace <MyOrganizationId> by the actual ID of the target Coveo organization (see Retrieve the organization ID).
Replace <MySecurityIdentityProviderId> by the actual ID of the target security identity provider (see Create a Security Identity Provider for a Secured Push Source).

In the query string:

Replace <MyFileId> by the filedId you got from Step 1: Create a File Container.

In the Authorization HTTP header:

Replace <MyAccessToken> by an access token that grants the Organization - View and Security identity providers - View/Edit privileges in the target Coveo organization (see Create an API key, Get the privileges of an access token, and Get your Coveo access token).

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, 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