Push API tutorial 2: Manage secured content

This is for:

Developer System Administrator

In the previous tutorial, you created a public Push source in which you added, and then deleted, a simple item.

In this tutorial, you’ll configure your Push source to make it secure and create its associated security identity provider. You’ll then perform a small mock content update, followed by a small mock security identity update.

Note

This tutorial assumes that the permissions in the fictional content repository are entirely determined at the item level.

Prerequisites

You need the setup described in the Push API Tutorials article.

Optionally, use the Run in Postman shared HTTP requests. If you do, set the appropriate values for the organizationId, securityIdentityProviderId, and apiKey environment variables in Postman in order for the API requests to execute successfully (see Manage Globals).

Step 1: Secure your Push source

With a secured Push source, you can manage items with permission models. The index uses a permission model to evaluate whether a user can see a given item in their query results.

  1. Access the Sources (platform-ca | platform-eu | platform-au) page in the Coveo Administration Console.

  2. Click your Push source, and then click Edit in the Action bar.

  3. On the Edit a Push source page, select the Content security tab.

  4. Select Same users and groups as in your current permission system.

  5. Click Save.

Step 2: Create a security identity provider

The security identity provider of a secured source is a Coveo organization module whose main purpose is to crawl a specific secured enterprise system on a regular basis to retrieve its latest security identity relationships and forward this data to the security identity cache (see Security identity cache and provider). A security identity provider allows the items in a secured source to reference existing and valid security identities in their permission models. This ensures that only the users who are allowed to see a specific item in its original secured repository can see this item in their query results. See Typical Coveo secured search for more details.

Use the SecurityCache API POST /securityproviders HTTP request with the following configuration to create a security identity provider for your secured Push source.

Request body

{
  "name" : "MyPushAPITutorialSecurityIdentityProvider",
  "nodeRequired": false,
  "type": "EXPANDED",
  "referencedBy": [
    {
      "id": "<MyPushSourceId>",1
      "type": "SOURCE"
    }
  ],
  "cascadingSecurityProviders": {
      "EmailSecurityProvider": {
        "name": "Email Security Provider",
        "type": "EMAIL"
    }
  }
}
1 Replace <MyPushSourceId> with the ID of your secured Push source.
Note

Initially, your security identity provider has no means of automatically crawling its intended target secured content repository. You must eventually implement this behavior with your own code, but that’s beyond the scope of this tutorial.

Step 3: Add items to your source

You’ll now perform three Push API calls to add items to your secured Push source using the PUT /sources/{sourceId}/documents HTTP request.

  1. For the first HTTP request, use the following request body. Its permissions property indicates that any anonymous user can see the item in their query results.

    Request body

     {
   "data": "",
   "permissions": [
     {
       "allowAnonymous": true
     }
   ]
 }

    Set the documentId query parameter to file://folder/. This URI doesn’t exist, but that doesn’t matter as you’re only pushing dummy items for this tutorial.

  2. For the second HTTP request, use the following request body. Its permissions property indicates that only the users asmith@example.com and bjones@example.com can see the item in their query results. You’ll define these security identities in step 4.

    Request body

     {
   "data": "Item 1 raw textual data",
   "permissions": [
     {
       "allowAnonymous": false,
       "allowedPermissions": [
         {
           "identity": "asmith@example.com",
           "identityType": "User"
         },
         {
           "identity": "bjones@example.com",
           "identityType": "User"
         }
       ]
     }
   ]
 }

    Set the documentId query parameter to file://folder/item1.txt for the purpose of this tutorial.

  3. For the third HTTP request, use the following request body. Its permissions property indicates that only the user asmith@example.com can see this item in their query results. As user bjones@example.com is both allowed and denied in the permission model, this user is effectively denied access to the item in their query results.

    Request body

     {
   "data": "Item 2 raw textual data",
   "permissions": [
     {
       "allowAnonymous": false,
       "allowedPermissions": [
         {
           "identity": "asmith@example.com",
           "identityType": "User"
         },
         {
           "identity": "bjones@example.com",
           "identityType": "User"
         }
       ],
       "deniedPermissions": [
         {
           "identity": "bjones@example.com",
           "identityType": "User"
         }
       ]
     }
   ]
 }

    Set the documentId query parameter to file://folder/item2.txt for the purpose of this tutorial.

You may have to wait several minutes before these three items become available in your source.

Note

You’ll learn how to push batches of items along with metadata and complex permission models in the next tutorial.

Step 4: Add security identities to your security identity provider

The permission models of the second and third items you pushed in step 3 reference security identities (that is, asmith@example.com and bjones@example.com). These security identities haven’t yet been defined in the security identity provider you created in step 2. This means that once the Coveo indexing pipeline finishes processing these items, the security identities they refer to will be in error, and the allowed users won’t be able to see the items in their query results.

To fix this, you’ll now add the asmith@example.com and bjones@example.com security identities to the security identity provider using the PUT /providers//permissions HTTP request.

  1. For the first HTTP request, use the following request body to define the asmith@example.com user security identity.

    Request body

     {
   "identity": {
     "name": "asmith@example.com",
     "type": "USER"
   }
 }

  2. For the second HTTP request, use the following request body to define the bjones@example.com user security identity.

    Request body

     {
   "identity": {
     "name": "bjones@example.com",
     "type": "USER"
   }
 }
Note

You’ll learn how to define batches of security identities including aliases, groups, and granted identities in the next tutorial.

Step 5: Validate the indexing status of the items

As a reminder, the table below summarizes the information and effective permissions on the items you pushed in step 3.

documentId data permissions

file://folder/

""

Anonymous check

file://folder/item1.txt

"Item 1 raw textual data"

Anonymous x asmith@example.com check bjones@example.com check

file://folder/item2.txt

"Item 2 raw textual data"

Anonymous x asmith@example.com check bjones@example.com x

The Coveo Administration Console Content Browser is a powerful tool that lets you emulate the query results that security identities would see in a search interface. You’ll now use the Content Browser to validate the successful indexing of the three items, both in terms of their content and permissions.

  1. Access the Sources (platform-ca | platform-eu | platform-au) page.

  2. On the Push source row, click Open in Content Browser.

    Show source items in the Content Browser

    Note that with the View all content option enabled in the Content Browser, you can see all items in the results.

    The View all content Content Browser option | Coveo

    As a Coveo organization administrator, you have the Allowed access level on the View all content domain and the privilege to bypass item permission models.

  3. On the Security Identities (platform-ca | platform-eu | platform-au) page, click your Push API security identity provider, and then click Browse identities in the Action bar.

  4. Click bjones@example.com, and then click Search as in the Action bar.

    You’re now impersonating bjones@example.com and seeing the two items that this user would see in a search interface.

    Searching as bjones in the Content Browser | Coveo

You can repeat the last steps to validate that asmith@example.com can see all three items.

Step 6: Delete the items

To begin the next tutorial with a clean source, use the DELETE /sources/{sourceId}/documents HTTP request to delete the three items you added in this tutorial.

To do so, set the documentId value to file://folder/ and deleteChildren to true. This deletes the item whose documentId is the one you specified and all items whose documentId values are nested under the documentId of the parent. In this case, the file://folder item, along with all other items matching file://folder/* in the target source will be deleted.

Shortly after your successful HTTP request, the Sources (platform-ca | platform-eu | platform-au) page should show your Push source with No items in the Content column.

Step 7: Disable the security identities

By default, when you perform a Push API operation, the service automatically sets the optional orderingId parameter of this operation to the current number of milliseconds since the UNIX epoch.

This means that each individual Push API operation has its own timestamp value, which can be compared to the mandatory orderingId parameter provided in a DELETE /sources/{sourceId}/documents/olderthan or DELETE /providers/{providerId}/permissions/olderthan Push API HTTP request.

To begin the next tutorial with a clean security identity provider, delete the security identities you created using the DELETE /providers/{providerId}/permissions/olderthan Push API HTTP request. You will need to provide a value for the orderingId parameter. Use the 13-digit current number of milliseconds since the UNIX epoch. You can get it from https://currentmillis.com/.

Afterward, refresh your security identity provider.

What’s next?

Proceed to Push API tutorial 3: Using batch calls to manage complex secured content.