Client Segregation in Document Information Extraction: A Brief Guide

If your organization uses multiple clients with the Document Information Extraction service, end users can usually switch freely between these clients on the Document Information Extraction UI. In some cases, however, you may want to restrict users’ access to defined clients only. The newly introduced client segregation function allows you to safeguard these clients against unauthorized access.

To use client segregation, you must embed the client id or ids in the user’s access token. When you’ve done this, the user can access only those clients specified in the token. This blogpost explains how to use any user attribute from an SAML identity provider (IdP) as a client id and make it available in the user’s token.

Once you’ve completed all the configuration steps described below, the authentication and authorization flow looks like the following:

In the example presented here, we’ll use the department attribute from the IdP as the source of dox_client_id in the user token. However, you can choose the attribute that best fits your particular use case.

Prerequisites

• You have administrator rights for the relevant subaccount on SAP Business Technology Platform (SAP BTP).
• A service instance has been created for Document Information Extraction in the tenant’s subaccount on SAP BTP. (See https://developers.sap.com/tutorials/cp-aibus-dox-service-instance.html.)
• A subscription to Document Information Extraction UI has been added in the tenant’s subaccount on SAP BTP. (See https://developers.sap.com/tutorials/cp-aibus-dox-ui-sub.html.)
• Mutual trust has been established between XSUAA and the tenant’s IdP. (See https://help.sap.com/docs/BTP/65de2977205c403bbc107264b8eccf4b/2ce3938c66d94479848bff3090999027.html.)

Role Configuration in SAP BTP Cockpit

In a first step, we’ll add the dox_client_id attribute to the user’s token.

In the SAP BTP cockpit, navigate to the Subscriptions tab of the tenant subaccount and choose the Actions button for the Document Information Extraction UI subscription.

Next, choose Manage Roles. On the Roles tab, choose Add a role (plus button above the table).

Enter a name for the new role. Now, select the role template Document_Information_Extraction_Attr_Dox_Client_Id. You also have the option of adding a description here. When you’ve completed your entries, choose Next.

To configure the attributes, select Identity Provider as source and enter department as value. These settings map the dox_client_id attribute to the department user attribute from the IdP. Choose Next.

Don’t make any changes to the remaining steps and complete the wizard by choosing Finish.

Next, create a new role collection with the name Document_Information_Extraction_Attr_Dox_Client_Id that contains this new role. To do so, navigate to Role Collections, choose the plus button at the top of the screen, and make the necessary entries.

Now, navigate to Users and assign your new role collection to all the users that need to access the Documentation Information Extraction UI.

The users’ tokens now include the dox_client_id:

"xs.user.attributes": {
    "dox_client_id": ["d1", "d2", "d3"]
}

Enable Client Segregation via DOX API

In a final step, you enable client segregation for the Document Information Extraction instance. To do this, call up the Swagger UI. To activate client segregation, make a POST request to the /configuration?scope=instance endpoint with the following payload:

{
    "value": {
      "clientSegregation": "true"
    }
}

You’ve enabled client segregation. The users you selected in SAP BTP cockpit now have access only to the clients included in their tokens.

By following the above steps for configuring roles in the SAP BTP Cockpit and enabling client segregation in the Swagger UI, you can easily restrict users’ access only to the clients that are specified in their access tokens.

Got any feedback or thoughts about client segregation in Document Information Extraction? Then feel free to share them in a comment below. If you’d like to ask (or answer) a question about the service or UI, you can make a post here. And if you want to dig deeper into other aspects of Document Information Extraction, then check out the blogposts here.