Link Search Menu Expand Document

Using Ons Autorisatie in your integrations

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.

To ensure the system’s security and allow for easy supervision by the care organizations, 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 rights for 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 to create/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 in the process. The third party developing an integration will need to independently store which roles are assigned to which users, for example in HR software.
    There is no API to query which roles are currently assigned to a user.

  • The care organisation decides which roles are made available to third party integrations through a whitelist. 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 available that allows third party integrations to query which roles are available to them.

  • It is explicitly not possible 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 Autorisaties. 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.
    For insights into the configuration, there are reports available in the Ons Autorisatie user interface.

  • Third party integrations only have access to role assigments that they themselves have created. 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 (preferred) or be set to use the default scope. The User provisioning model offers two fields to differentiate between those assignment types. Use duties for scoping per role assignment, and defaultScopedDuties for assignments using the default scope.

  • The default scope of a user can be set through a separate endpoint. This endpoint is, like the role assignments endpoint, write-only.

API description

Endpoints

  • GET /t/authorization/provisioning/roles
    • Returns: list of Role.
    • Used to obtain a list of roles that are accessible to this integration.
  • PUT /t/authorization/provisioning/user/{user_uuid}
    • accepts: User.
    • returns: HTTP 201 Created.
    • Sets role assignments (duties) for a user.
    • Idempotent. Subsequent calls omitting duties will remove these for the same source. See source field.
    • Returns a 400-range error when using role uuid’s which don’t exist, or aren’t whitelisted.
    • Invalid location and team ID’s will be silently ignored.
  • PUT /t/authorization/provisioning/user/{user_uuid}/scopes
    • accepts: DefaultScope.
    • returns: HTTP 201 Created.
    • Sets default scope for a user.
    • Idempotent. Subsequent calls omitting groups will remove these from the user scope (even if they are set in the UI or by other tools)
    • Invalid location and team ID’s will be silently ignored.

Models

Role

  • uuid: String
  • name: String

User

  • userUuid: String. Optional
  • source: String. Optional
  • duties: list of Duty
  • defaultScopedDuties: list of Duty (Scope fields are ignored)

Duty

  • roleUuid: String
  • locationIds: list of Integer
  • teamIds: list of Integer
  • myself: Boolean. Optional. Default false
  • allEmployees: Boolean. Optional. Default false
  • allClients: Boolean. Optional. Default false

DefaultScope

  • locationIds: list of Integer
  • teamIds: list of Integer
  • myself: Boolean. Optional. Default false
  • allEmployees: Boolean. Optional. Default false
  • allClients: Boolean. Optional. Default false

Process

  1. Create users or fetch users using other APIs.
  2. Determine which roles are available to the integration using GET /t/authorization/provisioning/roles.
  3. Use PUT /t/authorization/provisioning/users/{user_uuid} to set the roles for the user with user_uuid.
  4. Use PUT /t/authorization/provisioning/users/{user_uuid}/scopes to set the default scope for the user with user_uuid.

The roles that are set in step 3 will replace any existing assigments that were made by this integration. Roles that were assigned by the integration will be labeled with the integration’s name in the Ons Autorisatie user interface to clearly show how the assignment came to be.

Note that the ownership rules for duties do not apply for the default scope set by the call in step 4. This requires developers to be vigilant and complete when calling this API!. Only one connector at a time should be given access to this API.

Auditing

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

Ownership of a role assignment

Third party integrations will only be able to replace role assignments they made themselves. The owner of a role assignment is identified by the connector_name and the source from the provisioning user model. The connector_name is taken from the first part of the integration’s certificate’s common name ({connector_name}-{customer_code}-{identifier}).