Ons APIUsing Ons Autorisatie in your integrations
Care organisations that work with Ons use Ons Autorisatie to set up rights and roles for their employees. As discussed in Provisioning Authorizations, it is impossible by design to query which Roles are assigned to an Ons user. In order to assist you in making authorization decisions for an Ons user within your application, we offer the option to request a Right that is specific to your integration.
See also the support portal for documentation specific to Ons Autorisatie.
Why integrate with Ons Autorisatie?
If your integrated application supports Ons Users in one of their tasks in the care process, it’s likely that the scope of clients for that User should be the same in Ons and in your application. Given the complexity and flexibility of our authorization system, it will be very hard to rebuild the same configuration in your application.
When using Ons Autorisatie, the authorization management for the external application will be fully integrated in Ons. This has several benefits:
- By integrating with Ons Autorisatie, the care organisation can manage all authorizations in one place. This also eliminates possible duplications.
- If an employee needs to escalate their authorizations, no extra steps are required within the external application. An example: requiring emergency access to a patient’s room.
- Any change in authorizations within the care organisation is automatically propagated to the external application. Authorizations in the external application are always up-to-date with authorization changes and escalations in Ons.
When to integrate with Ons Autorisatie - and when not to
When access to (part of) an external integration’s functionality should be limited in some way, it might be a good idea to create a right for this. Do note that roles are always assigned to an employee, so it’s not possible to authorize based on another entity (such as a location).
In order to be able to integrate with Ons Autorisatie, the employees and clients in the external application should be linked in some way to those administered in Ons.
Process
Before creating a new right, first consider whether integrating with Ons Autorisatie is possible and beneficial to the application. See also the above paragraphs detailing why and when to integrate the authorization.
Rights are always scoped to a connector in the API dashboard. Only versions of that connector can use a right defined on the connector.
As a first step, define a right on the page of the relevant connector. This will require several fields, each with strict rules regarding their content. See Right Syntax Requirements for a detailed description. The request of Rights is subject to human approval at multiple levels and, after approval, depends on a fixed roll-out schedule. For this reason, this process is:
- Slow: Expect ±2 weeks for approval and then ±1 month for roll-out on production
- Final: After acceptance, no further changes to the Right and its descriptions are allowed
If you want to add a right to a specific version, go to that version’s page and, in the technical design, open the “rights” tab. Here you can enable the required rights. The right can now be used for the connector version! See Using Authorization APIs for help calling and interpreting the authorization APIs.
Using Rights in Versions
Once your requested right is approved, it can be added to the technical design of new versions. There, it becomes part of the regular review process and can not be removed after approval. It is important that the right used by a version is locked into the technical design, because we show the permissions of integrations to customers using them. This also means that versions predating the acceptance of your right will not be able to use the right.
Impact on roll-out process
Once you add a Right to a version, you tie this version up with the roll-out schedule of this right across the stages. You can only request approval for the next stage if all rights you are using are available on the current stage, because otherwise you will not have been able to test your implementation on the current stage.
Example usecase
A care provider uses application A to handle a certain part of their work processes. In application A, employees can view sensitive client data. Both these employees and clients are actively synced between Nedap Ons and application A.
The developer of application A would like to restrict access of employees to only those clients they are authorized to view. To do this, they request a right. When the right is approved and available on staging and production, they ask the care provider to add the right to the roles describing client-employee relations.
When an employee now logs in to application A and looks through the list of clients, the application will query the scopes endpoint to retrieve a list of all clients the employee may see in the context of the created right. When an employee navigates to a specific client page, application A will query the clearance endpoint to ask Ons Autorisatie whether that employee has access to that client in the context of the right.