Roles and authorities
How permissions work, and how to manage roles, their authorities, and the roles of each user.
BPMS uses the permission model of BPMS 3.x, so every existing role keeps its access. A user's permissions come from the user's roles, and each role holds a list of authority codes: the codes of the BPMS 3.x menu, such as 6.2.1.4 (view roles).
| Operation | Call | Authority |
|---|---|---|
| List the roles | GET /api/v1/access/roles | 6.2.1.4 (View roles) |
| Read a role | GET /api/v1/access/roles/{roleId} | 6.2.1.4 |
| Create a role | POST /api/v1/access/roles | 6.2.1.1 (Create roles) and every code of the role |
| Update a role's name and description | PUT /api/v1/access/roles/{roleId} | 6.2.1.2 (Edit roles) |
| Grant or revoke an authority | PUT or DELETE /api/v1/access/roles/{roleId}/authorities/{code} | 6.2.1.2, and to grant, the code itself |
| Assign a role to a user, or unassign it | PUT or DELETE /api/v1/access/users/{userId}/roles/{roleId} | 6.2.2.2 (Edit users), and to assign, every code of the role |
How authorities are checked
- Each operation requires an authority code. The caller holds it when one of the caller's roles in the caller's tenant stores that code or a more specific one: a role with
5.3.8also holds5.3and5, as in BPMS 3.x. - A parent code never grants its children: a role with
5.3does not hold5.3.8. - Without the authority, the call answers
403with the codecore.authority-required, and the refusal is recorded in the audit log with the user, the tenant, the action, and the request id.
List the roles
curl -sS -H "Authorization: Bearer $TOKEN" "$BPMS_URL/api/v1/access/roles?page=0&size=20&sort=name"It requires the view-roles authority, 6.2.1.4, and lists only the roles of your tenant, without deleted ones. First call describes its parameters and answer.
Read a role
curl -sS -H "Authorization: Bearer $TOKEN" "$BPMS_URL/api/v1/access/roles/3"It answers 200 with id, uuid, name, and description. uuid is the BPMS 3.x identifier of the role, absent for a role BPMS 3.x stored without one, and description is absent when the role has none.
Create a role
curl -sS -X POST -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
"$BPMS_URL/api/v1/access/roles" -d '{"name": "Purchasing", "description": "Purchasing team", "authorities": ["2.1", "2.1.3"]}'name is required, at most 100 characters, and unique in your tenant in any case; description is optional, at most 2048 characters; authorities holds at least one BPMS 3.x authority code, and you can only include codes you hold. It answers 201 with the new role and its address in the Location header. The role starts with no users.
Update a role
curl -sS -X PUT -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
"$BPMS_URL/api/v1/access/roles/3" -d '{"name": "Purchasing and suppliers", "description": "Purchasing team"}'It replaces the name and the description, and answers 200 with the role. name is required; leaving description out clears it. The role keeps its uuid and its authorities, which change only by granting and revoking.
Grant an authority
curl -sS -X PUT -H "Authorization: Bearer $TOKEN" "$BPMS_URL/api/v1/access/roles/<roleId>/authorities/<code>"It adds the code to the role and answers 204, also when the role already holds it. It requires the edit-roles authority, 6.2.1.2, and the code being granted: a user can only grant authorities the user holds.
Revoke an authority
curl -sS -X DELETE -H "Authorization: Bearer $TOKEN" "$BPMS_URL/api/v1/access/roles/<roleId>/authorities/<code>"It removes exactly that code from the role and answers 204, also when the role did not hold it. Revoking 5.3 keeps 5.3.8. It requires the edit-roles authority, 6.2.1.2. A role always keeps at least one authority.
Every grant and revocation is recorded in the audit log in the same transaction as the change, so a change without its record cannot happen.
Assign a role to a user
curl -sS -X PUT -H "Authorization: Bearer $TOKEN" "$BPMS_URL/api/v1/access/users/<userId>/roles/<roleId>"It gives the role to the user and answers 204, also when the user already has it. It requires the edit-users authority, 6.2.2.2, and every code of the role, so nobody gains an authority by editing users.
Unassign a role
curl -sS -X DELETE -H "Authorization: Bearer $TOKEN" "$BPMS_URL/api/v1/access/users/<userId>/roles/<roleId>"It removes the role from the user and answers 204, also when the user did not have it. It requires 6.2.2.2. A user always keeps at least one role, without which the user cannot sign in.
Changes to a role and to a user's roles apply from the user's next request; the user's sessions stay open. Creating, updating, assigning, and unassigning are recorded in the audit log, as are their refusals for a missing authority.
Errors
| Status | code | When |
|---|---|---|
400 | core.validation-failed | A field is missing or invalid, a code is not a BPMS 3.x authority code, or a list parameter is invalid; errors lists each one. |
401 | core.authentication-required | The call has no valid token. |
403 | core.authority-required | The caller lacks the authority the operation requires, or a code of the role. |
404 | access.role-not-found | The role does not exist in your tenant or is deleted. |
404 | access.user-not-found | The user does not exist in your tenant or is deleted. |
409 | access.role-name-taken | Another role of the tenant has this name, in any case. |
409 | access.role-authority-required | The revocation would leave the role without authorities. |
409 | access.user-role-required | Unassigning would leave the user without roles. |
In the OpenAPI document, the operations are listRoles, getRole, createRole, updateRole, grantRoleAuthority, revokeRoleAuthority, assignUserRole, and unassignUserRole, under the access tag.