Skip to main content Link Menu Expand (external link) Copy Copied
Ons API

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.

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 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 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 to query which roles are currently assigned to a user.

  • The care organisation decides which roles are made available to 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 suppliers 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 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.

    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 (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 a separate endpoint. This endpoint is, like the role assignments endpoint, write-only. This has the same ownership mechanism applied where a specific integration can only overwrite their own set.

About My Teams, My Locations and Default User Scope

We’re currently running a pilot to migrate the Default User Scope to two new lists: My Teams and My Locations. Internally, these use the same store and are interchangeable: Anything stored in one, is also visible in the other, except for the All Clients, All Employees and Myself entries, which are only visible in the Default User Scope and not supported in My Teams and My Locations.

Integration parties should already switch to API’s using My Teams / My Locations, regardless of the customer environment being switched. This will ensure compatibility once the customer environment is switched, and makes this switch independent of the integration party switching.

In other words: Anything set in My Teams and My Locations using this provisioning API will show up in customer environments in the Default User Scope if that customer hasn’t switched yet.

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}/duties
    • 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}/my_teams and ../my_locations
    • accepts: MyTeams or MyLocations.
    • returns: HTTP 201 Created.
    • Sets the My Teams or My Locations list of the user
    • Idempotent. Subsequent calls omitting groups will remove these from the user scope (if these are set by the same connector)
    • Unlike duties, there cannot be a distinction made on source
    • Invalid location and team ID’s will be silently ignored.
  • PUT /t/authorization/provisioning/user/{user_uuid}/scope_settings
    • accepts: ScopeSettings
    • returns: HTTP 201 Created.
    • Sets the Myself, AllClients and AllEmployees in the Advanced Scoping diaglog of the user
    • Idempotent. Subsequent calls omitting groups will remove these from the user scope (if these are set by the same connector)
    • Unlike duties, there cannot be a distinction made on source

Models

Role

  • uuid: String
  • name: String

User

  • userUuid: String. Optional
  • source: String. Optional
  • duties: list of Duty

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
  • myPlanning: Boolean. Optional. Default false
  • myRoster: Boolean. Optional. Default false
  • clientEmployeeRelationTypeIds: list of Integer (from nexus.ClientEmployeeRelationTypeAPI)
  • myTeams: Boolean. Optional. Default false
  • myLocations: Boolean. Optional. Default false
  • roleScope: Boolean. Optional. Default false

MyTeams

  • teamIds: list of Integer

MyLocations

  • locationIds: list of Integer

ScopeSettings

  • legacyAuthScopingOptions: LegacyAuthScopingOptions model

LegacyAuthScopingOptions

  • 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}/duties to set the roles for the user with user_uuid.
  4. Use PUT /t/authorization/provisioning/users/{user_uuid}/my_teams and ../my_locations to set these lists 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, 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.