Provisioning authorizations

Ons® Autorisatie offers the option for third party integrations to provision authorizations. This makes it possible to create integrations that allow user authorizations in Ons® to be set from HR software for example.

Guidelines

To ensure the system’s security and allow for easy supervision by the care organisations, a couple of guidelines were followed during the development of the authorization APIs. For anyone developing an integration that makes use of these APIs, it’s important to be aware of these:

• The configuration of roles (that is: the assignment of tasks to a role) will always be done through the user interface of Ons® Autorisatie. This way the care organisation is always in control of what actions a user with a certain role can perform in our software. There is no API endpoint to create or configure roles.
• Ons® Autorisatie offers a provisioning API to assign roles. This API assigns a complete set of roles to the users and overwrites all old roles for your specific integration in the process. The supplier will need to independently store which roles are assigned to which users, for example in HR software. There is no API endpoint to query which roles are assigned to a user. This is done to prevent the development of authorization structures based on the configuration of Ons® Autorisatie. This is undesirable because it creates side effects of (un)assigning a role to a user that are not evident when that action is performed.
• The care organisation decides which roles are made available to integrations through a whitelist in the user interface of Ons Autorisatie. This allows the care organisation to, for example, keep the management of an administrative role with broad authorizations under their own control. There is an API endpoint to query which roles are available to you
• Third party integrations only have access to role assigments that they themselves have created (ownership of these assignments is tracked). Roles that have been manually, or otherwise, assigned can not be modified by the integration. This allows care organisations to use several tools at the same time and keep the option to manually make exceptions when required.
• The scope of a role assignment can be set per role assignment. These can reference the My Teams and My Locations lists or the Role Scope maintained by the care provider.
• The My Teams and My Locations lists of a user can be set through separate endpoints for MyTeams and MyLocations. These endpoints are, like the role assignments endpoint, write-only. This has the same ownership mechanism applied where a specific integration can only overwrite their own set.

Process

1. Create users or fetch users using API endpoints from the User model
2. Determine which roles are available to the integration using the API endpoint for getting all roles (that are available through Ons® API)
3. Use the API endpoint for duties to assign roles to a user.
4. Use the endpoints for MyTeams and MyLocation to set a scope for a user_uuid.

The roles that are set in step 3 will replace any existing assigments that were made by this integration. Roles, My Teams and My Locations that were assigned/added by the integration will be labeled with the integration’s name in the Ons® Autorisatie user interface to clearly show how that element came to be.

Auditing

All changes in the provisioning API are logged for future reference.

Ownership

Third party integrations will only be able to replace role assignments, My Teams, My Locations and LegacyAuthScopingOptions they made themselves.

• The owner of a role assignment is identified by the connector_name and the source from the provisioning user model.
• The owner of a My Teams, My Locations and LegacyAuthScopingOptions entry is only determined by connector_name.

The connector_name is taken from the first part of the integration’s certificate’s common name ({connector_name}-{customer_code}-{identifier}). source is a string provided by the integration.