Push API tutorial 2: Manage secured content
Push API tutorial 2: Manage secured content
- Prerequisites
- Step 1: Secure your Push source
- Step 2: Create a security identity provider
- Step 3: Add items to your source
- Step 4: Add security identities to your security identity provider
- Step 5: Validate the indexing status of the items
- Step 6: Delete the items
- Step 7: Disable the security identities
- What’s next?
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.
-
Access the Sources (platform-ca | platform-eu | platform-au) page in the Coveo Administration Console.
-
Click your Push source, and then click Edit in the Action bar.
-
On the Edit a Push source page, select the Content security tab.
-
Select Same users and groups as in your current permission system.
-
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
|
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.
-
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 tofile://folder/
. This URI doesn’t exist, but that doesn’t matter as you’re only pushing dummy items for this tutorial. -
For the second HTTP request, use the following request body. Its
permissions
property indicates that only the usersasmith@example.com
andbjones@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 tofile://folder/item1.txt
for the purpose of this tutorial. -
For the third HTTP request, use the following request body. Its
permissions
property indicates that only the userasmith@example.com
can see this item in their query results. As userbjones@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 tofile://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.
-
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" } }
-
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 |
file://folder/item1.txt |
"Item 1 raw textual data" |
Anonymous asmith@example.com bjones@example.com |
file://folder/item2.txt |
"Item 2 raw textual data" |
Anonymous asmith@example.com bjones@example.com |
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.
-
Access the Sources (platform-ca | platform-eu | platform-au) page.
-
On the Push source row, click Open in Content Browser.
Note that with the View all content option enabled in the Content Browser, you can see all items in the results.
As a Coveo organization administrator, you have the
Allowed
access level on theView all content
domain and the privilege to bypass item permission models. -
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.
-
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.
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.