Chapter 8. Security Management REST API for Business Central groups, roles, and users
Red Hat Process Automation Manager provides a Security Management REST API that you can use to manage the groups, roles, and users in Red Hat Process Automation Manager without using the Business Central user interface. This API support enables you to facilitate and automate management of Business Central groups, roles, users, and granted permissions.
With the Security Management REST API, you can perform the following actions:
- Retrieve information about all groups, roles, users, and their granted permissions
- Create, update, or delete groups and users
- Update granted permissions for groups, roles, and users
- Retrieve information about groups and roles assigned to the users
Security Management REST API requests require the following components:
- Authentication
The Security Management REST API requires HTTP Basic authentication or token-based authentication for the user role
admin
. To view configured user roles for your Red Hat Process Automation Manager distribution, navigate to~/$SERVER_HOME/standalone/configuration/application-roles.properties
and~/application-users.properties
.To add a user with the
admin
role, navigate to~/$SERVER_HOME/bin
and run the following command:$ ./add-user.sh -a --user <USERNAME> --password <PASSWORD> --role admin
For more information about user roles and Red Hat Process Automation Manager installation options, see Planning a Red Hat Process Automation Manager installation.
- HTTP headers
The Security Management REST API requires the following HTTP headers for API requests:
Accept
: Data format accepted by your requesting client:-
application/json
(JSON)
-
Content-Type
: Data format of yourPOST
orPUT
API request data:-
application/json
(JSON)
-
- HTTP methods
The Security Management REST API supports the following HTTP methods for API requests:
-
GET
: Retrieves specified information from a specified resource endpoint -
POST
: Creates or updates a resource -
PUT
: Updates a resource -
DELETE
: Deletes a resource
-
- Base URL
The base URL for Security Management REST API requests is
http://SERVER:PORT/business-central/rest/
, such ashttp://localhost:8080/business-central/rest/
.NoteThe REST API base URL for the Security Management, Knowledge Store, and Process Automation Manager controller built into Business Central are the same because all are considered part of Business Central REST services.
- Endpoints
Security Management REST API endpoints, such as
/users/{userName}
for a specified user, are the URIs that you append to the Security Management REST API base URL to access the corresponding resource or type of resource in Red Hat Process Automation Manager.Example request URL for
/users/{userName}
endpointhttp://localhost:8080/business-central/rest/users/newUser
- Request data
HTTP
POST
requests in the Security Management REST API may require a JSON request body with data to accompany the request.Example POST request URL and JSON request body data
http://localhost:8080/business-central/rest/users/newUser/groups
[ "newGroup" ]
8.1. Sending requests with the Security Management REST API using a REST client or curl utility
The Security Management REST API enables you to manage the groups, roles, and users in Red Hat Process Automation Manager without using the Business Central user interface. You can send Security Management REST API requests using any REST client or curl utility.
Prerequisites
- Business Central is installed and running.
-
You have
admin
user role access to Business Central.
Procedure
-
Identify the relevant API endpoint to which you want to send a request, such as
[GET] /groups
to retrieve groups in Business Central. In a REST client or curl utility, enter the following components for a
GET
request to/groups
. Adjust any request details according to your use case.For REST client:
-
Authentication: Enter the user name and password of the Business Central user with the
admin
role. HTTP Headers: Set the following header:
-
Accept
:application/json
-
-
HTTP method: Set to
GET
. -
URL: Enter the Security Management REST API base URL and endpoint, such as
http://localhost:8080/business-central/rest/groups
.
For curl utility:
-
-u
: Enter the user name and password of the Business Central user with theadmin
role. -H
: Set the following header:-
Accept
:application/json
-
-
-X
: Set toGET
. -
URL: Enter the Security Management REST API base URL and endpoint, such as
http://localhost:8080/business-central/rest/groups
.
curl -u 'baAdmin:password@1' -H "Accept: application/json" -X GET "http://localhost:8080/business-central/rest/groups"
-
Authentication: Enter the user name and password of the Business Central user with the
Execute the request and review the KIE Server response.
Example server response (JSON):
[ { "group1" }, { "group2" } ]
In your REST client or curl utility, send another API request with the following components for a
POST
request to/users/{userName}/groups
to update the groups assigned to a user. Adjust any request details according to your use case.For REST client:
-
Authentication: Enter the user name and password of the Business Central user with the
admin
role. HTTP Headers: Set the following header:
-
Accept
:application/json
-
Content-Type
:application/json
-
-
HTTP method: Set to
POST
. -
URL: Enter the Security Management REST API base URL and endpoint, such as
http://localhost:8080/business-central/rest/users/newUser/groups
. - Request body: Add a JSON request body with the identification data for the new group:
[ "newGroup" ]
For curl utility:
-
-u
: Enter the user name and password of the Business Central user with theadmin
role. -H
: Set the following headers:-
Accept
:application/json
-
Content-Type
:application/json
-
-
-X
: Set toPOST
. -
URL: Enter the Security Management REST API base URL and endpoint, such as
http://localhost:8080/business-central/rest/users/newUser/groups
. -
-d
: Add a JSON request body or file (@file.json
) with the identification data for the new group:
curl -u 'baAdmin:password@1' -H "Accept: application/json" -H "Content-Type: application/json" -X POST "http://localhost:8080/business-central/rest/users/newUser/groups" -d "["newGroup"]"
curl -u 'baAdmin:password@1' -H "Accept: application/json" -H "Content-Type: application/json" -X POST "http://localhost:8080/business-central/rest/users/newUser/groups" -d @user-groups.json
-
Authentication: Enter the user name and password of the Business Central user with the
Execute the request and review the KIE Server response.
Example server response (JSON):
{ "status": "OK", "message": "Groups [newGroup] are assigned successfully to user wbadmin" }
If you encounter request errors, review the returned error code messages and adjust your request accordingly.
8.2. Supported Security Management REST API endpoints
The Security Management REST API provides endpoints for managing groups, roles, users, and permissions in Business Central. It includes the security and permission management tasks that an administrator can also perform using the Security Management page in Business Central.
8.2.1. Groups
The Security Management REST API supports the following endpoints for managing groups in Business Central. The Security Management REST API base URL is http://SERVER:PORT/business-central/rest/
. All requests require HTTP Basic authentication or token-based authentication for the admin
user role.
- [GET] /groups
Returns all groups in Business Central.
Example server response (JSON)
[ { "group1" }, { "group2" } ]
- [POST] /groups
Creates a group in Business Central. A group must have at least one user assigned.
Table 8.1. Request parameters Name Description Type Requirement body
Name of the group and users assigned to the new group
Request body
Required
Example request body (JSON)
{ "name": "groupName", "users": [ "userNames" ] }
Example server response (JSON)
{ "status": "OK", "message": "Group newGroup is created successfully." }
- [DELETE] /groups/{groupName}
Deletes a specified group from Business Central.
Table 8.2. Request parameters Name Description Type Requirement groupName
Name of the group to be deleted
String
Required
Example server response (JSON)
{ "status": "OK", "message": "Group newGroup is deleted successfully." }
8.2.2. Roles
The Security Management REST API supports the following endpoints for managing roles in Business Central. The Security Management REST API base URL is http://SERVER:PORT/business-central/rest/
. All requests require HTTP Basic authentication or token-based authentication for the admin
user role.
- [GET] /roles
Returns all roles in Business Central.
Example server response (JSON)
[ { "name": "process-admin" }, { "name": "manager" }, { "name": "admin" } ]
8.2.3. Users
The Security Management REST API supports the following endpoints for managing users in Business Central. The Security Management REST API base URL is http://SERVER:PORT/business-central/rest/
. All requests require HTTP Basic authentication or token-based authentication for the admin
user role.
- [GET] /users
Returns all users in Business Central.
Example server response (JSON)
[ "newUser", "user1", "user2", ]
- [GET] /users/{userName}/groups
Returns all groups assigned to a specified user.
Table 8.3. Request parameters Name Description Type Requirement userName
Name of the user for whom you are retrieving assigned groups
String
Required
Example server response (JSON)
[ { "group1" }, { "group2" } ]
- [GET] /users/{userName}/roles
Returns all roles assigned to a specified user.
Table 8.4. Request parameters Name Description Type Requirement userName
Name of the user for whom you are retrieving assigned roles
String
Required
Example server response (JSON)
[ { "name": "process-admin" }, { "name": "manager" }, { "name": "admin" } ]
- [POST] /users
Creates a specified user with specified roles and groups.
Example request body (JSON)
{ "name": "newUser", "roles": [ "admin", "developer" ], "groups": [ "group1", "group2" ] }
Example server response (JSON)
{ "status": "OK", "message": "User newUser is created successfully." }
- [Post] /users/{userName}/changePassword
Changes the password of a specified user.
Table 8.5. Request parameters Name Description Type Requirement userName
Name of the user for whom you are changing the password
String
Required
Example request command
curl -u 'baAdmin:password@1' -H "Accept: application/json" -H "Content-Type: application/json" -X POST "http://localhost:8080/business-central/rest/users/newUser/changePassword" -d newpassword
Example server response (JSON)
{ "status": "OK", "message": "Password for newUser has been updated successfully." }
- [DELETE] /users/{userName}
Deletes a specified user from Business Central.
Table 8.6. Request parameters Name Description Type Requirement userName
Name of the user to be deleted
String
Required
Example server response (JSON)
{ "status": "OK", "message": "User newUser is deleted successfully." }
- [POST] /users/{userName}/groups
Overrides the existing groups assigned to a specified user with new groups.
Table 8.7. Request parameters Name Description Type Requirement userName
Name of the user for whom you are updating groups
String
Required
Example request body (JSON)
[ "newGroup" ]
Example server response (JSON)
{ "status": "OK", "message": "Groups [newGroup] are assigned successfully to user wbadmin" }
- [POST] /users/{userName}/roles
Overrides the existing roles assigned to a specified user with new roles.
Table 8.8. Request parameters Name Description Type Requirement userName
Name of the user for whom you are updating roles
String
Required
Example request body (JSON)
[ "admin" ]
Example server response (JSON)
{ "status": "OK", "message": "Roles [admin] are assigned successfully to user wbadmin" }
8.2.4. Permissions
The Security Management REST API supports the following endpoints for managing permissions granted to the groups, roles, and users in Business Central. The Security Management REST API base URL is http://SERVER:PORT/business-central/rest/
. All requests require HTTP Basic authentication or token-based authentication for the admin
user role.
- [GET] /groups/{groupName}/permissions
Returns all permissions granted to a specified group.
Table 8.9. Request parameters Name Description Type Requirement groupName
Name of the group for whom you are retrieving permissions
String
Required
Example server response (JSON)
{ "homePage": "HomePerspective", "priority": -10, "project": { "read": { "access": false, "exceptions": [] }, }, "spaces": { "read": { "access": true, "exceptions": [ "MySpace" ] }, }, "editor": { "read": { "access": false, "exceptions": [ "GuidedDecisionTreeEditorPresenter" ] }, "create": null, "update": null, "delete": null, "build": null }, "pages": { "read": { "access": true, "exceptions": [] }, "build": null }, "workbench": { "editDataObject": false, "plannerAvailable": false, "editGlobalPreferences": false, "editProfilePreferences": false, "accessDataTransfer": false, "jarDownload": true, "editGuidedDecisionTableColumns": true } }
- [GET] /roles/{roleName}/permissions
Returns all permissions granted to a specified role.
Table 8.10. Request parameters Name Description Type Requirement roleName
Name of the role for whom you are retrieving permissions
String
Required
Example server response (JSON)
{ "homePage": "HomePerspective", "priority": -10, "project": { "read": { "access": false, "exceptions": [] }, }, "spaces": { "read": { "access": true, "exceptions": [ "MySpace" ] }, }, "editor": { "read": { "access": false, "exceptions": [ "GuidedDecisionTreeEditorPresenter" ] }, "create": null, "update": null, "delete": null, "build": null }, "pages": { "read": { "access": true, "exceptions": [] }, "build": null }, "workbench": { "editDataObject": false, "plannerAvailable": false, "editGlobalPreferences": false, "editProfilePreferences": false, "accessDataTransfer": false, "jarDownload": true, "editGuidedDecisionTableColumns": true } }
- [GET] /users/{userName}/permissions
Returns all permissions granted to a specified user.
Table 8.11. Request parameters Name Description Type Requirement userName
Name of the user for whom you are retrieving permissions
String
Required
Example server response (JSON)
{ "homePage": null, "priority": null, "project": { "read": { "access": false, "exceptions": [] }, }, "spaces": { "read": { "access": true, "exceptions": [ "MySpace" ] }, }, "editor": { "read": { "access": false, "exceptions": [ "GuidedDecisionTreeEditorPresenter" ] }, "create": null, "update": null, "delete": null, "build": null }, "pages": { "read": { "access": true, "exceptions": [] }, "build": null }, "workbench": { "editDataObject": false, "plannerAvailable": false, "editGlobalPreferences": false, "editProfilePreferences": false, "accessDataTransfer": false, "jarDownload": true, "editGuidedDecisionTableColumns": true } }
- [Post] /groups/{groupName}/permissions
Updates the permissions of a specified group.
Table 8.12. Request parameters Name Description Type Requirement groupName
Name of the group for whom you are updating permissions
String
Required
Example request body (JSON)
{ "homepage": "HomePerspective", "priority": 10, "pages": { "create": true, "read": false, "delete": false, "update": false, "exceptions": [ { "name": "HomePerspective", "permissions": { "read": true } } ] }, "project": { "create": true, "read": true, "delete": false, "update": false, "Build": false }, "spaces": { "create": true, "read": true, "delete": false, "update": false }, "editor": { "read": true }, "workbench": { "editDataObject": true, "plannerAvailable": true, "editGlobalPreferences": true, "editProfilePreferences": true, "accessDataTransfer": true, "jarDownload": true, "editGuidedDecisionTableColumns": true } }
Example server response (JSON)
{ "status": "OK", "message": "Group newGroup permissions are updated successfully." }
- [Post] /roles/{roleName}/permissions
Updates the permissions of a specified role.
Table 8.13. Request parameters Name Description Type Requirement roleName
Name of the role for whom you are updating permissions
String
Required
Example request body (JSON)
{ "homepage": "HomePerspective", "priority": 10, "pages": { "create": true, "read": false, "delete": false, "update": false, "exceptions": [{ "name": "HomePerspective", "permissions": { "read": true } }] }, "project": { "create": true, "read": true, "delete": false, "update": false, "Build": false }, "spaces": { "create": true, "read": true, "delete": false, "update": false }, "editor": { "read": true }, "workbench": { "editDataObject": true, "plannerAvailable": true, "editGlobalPreferences": true, "editProfilePreferences": true, "accessDataTransfer": true, "jarDownload": true, "editGuidedDecisionTableColumns": true } }
Example server response (JSON)
{ "status": "OK", "message": "Role newRole permissions are updated successfully." }
8.2.4.1. Supported permissions in Business Central
The following are available permissions in Red Hat Process Automation Manager. Administrators use these permissions to allow specific actions to a group, role, or user in Business Central.
- Priority
Priority is an integer that defines the precedence of users who are assigned multiple roles or groups. The default value of priority for a new group is
-100
. In Business Central, you can set an integer value as a priority, which is resolved using the following rules:Table 8.14. Priority value table Integer value Priority Less than -5
VERY LOW
Between -5 and 0
LOW
Equal to 0
NORMAL
Between 0 and 5
HIGH
Greater than 5
VERY HIGH
- Home Page
- Home Page indicates the default landing page for users.
- Workbench
Workbench consists of the following defined permissions:
{ "editDataObject": true, "plannerAvailable": true, "editGlobalPreferences": true, "editProfilePreferences": true, "accessDataTransfer": true, "jarDownload": true, "editGuidedDecisionTableColumns": true }
- Pages, Editor, Spaces, and Projects
The following are possible values for the permissions based on the resource type:
-
PAGES: read,create,update,delete
-
EDITOR: read
-
SPACES: read,create,update,delete
-
PROJECT: read,create,update,delete,build
You can use following code to add exceptions to Pages, Editor, Spaces, and Projects permissions:
{ "pages": { "read": false, "exceptions": [ { "resourceName": "ProcessInstances", "permissions": { "read": false } }, { "resourceName": "ProcessDefinitions", "permissions": { "read": false } } ] } }
The
name
attribute is an identifier of a resource that you add as an exception. Use the following REST API endpoints to get the list of possible identifiers. The REST API base URL ishttp://SERVER:PORT/business-central/rest/
.-
[GET] /perspectives
: Returns perspective names of all pages in Business Central -
[GET] /editors
: Returns all editors in Business Central -
[GET] /spaces
: Returns all spaces in Business Central -
[GET] /spaces/{spaceName}/projects
: Returns projects in a specified space
Example server response for pages (JSON)
"pages": { "create": true, "read": false, "exceptions": [ { "name": "HomePerspective", "permissions": { "read": true } } ] }
-