Technical Articles
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.
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.
Is it possible that the Service detects the client automatically?