Chapter 29. 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 ~/USDSERVER_HOME/standalone/configuration/application-roles.properties and ~/application-users.properties . To add a user with the admin role, navigate to ~/USDSERVER_HOME/bin and run the following command: USD ./bin/jboss-cli.sh --commands="embed-server --std-out=echo,/subsystem=elytron/filesystem-realm=ApplicationRealm:add-identity(identity=<USERNAME>),/subsystem=elytron/filesystem-realm=ApplicationRealm:set-password(identity=<USERNAME>, clear={password='<PASSWORD>'}),/subsystem=elytron/filesystem-realm=ApplicationRealm:add-identity-attribute(identity=<USERNAME>, name=role, value=['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 your POST or PUT 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 as http://localhost:8080/business-central/rest/ . Note The 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} endpoint http://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" ] 29.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 the admin role. -H : Set the following header: Accept : application/json -X : Set to GET . URL : Enter the Security Management REST API base URL and endpoint, such as http://localhost:8080/business-central/rest/groups . 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 the admin role. -H : Set the following headers: Accept : application/json Content-Type : application/json -X : 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 . -d : Add a JSON request body or file ( @file.json ) with the identification data for the new group: 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. 29.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. 29.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 29.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 29.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." } 29.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" } ] 29.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 29.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 29.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 29.5. Request parameters Name Description Type Requirement userName Name of the user for whom you are changing the password String Required Example request command 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 29.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 29.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 29.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" } 29.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 29.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 29.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 29.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 29.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 29.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." } 29.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 29.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 is http://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 } } ] }

Commands:
./bin/jboss-cli.sh --commands="embed-server --std-out=echo,/subsystem=elytron/filesystem-realm=ApplicationRealm:add-identity(identity=<USERNAME>),/subsystem=elytron/filesystem-realm=ApplicationRealm:set-password(identity=<USERNAME>, clear={password='<PASSWORD>'}),/subsystem=elytron/filesystem-realm=ApplicationRealm:add-identity-attribute(identity=<USERNAME>, name=role, value=['admin'])"
newGroup
curl -u 'baAdmin:password@1' -H "Accept: application/json" -X GET "http://localhost:8080/business-central/rest/groups"
[ { "group1" }, { "group2" } ]
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 "["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
status: OK
message: Groups [newGroup] are assigned successfully to user wbadmin
[ { "group1" }, { "group2" } ]
{ "name": "groupName", "users": [ "userNames" ] }
status: OK
message: Group newGroup is created successfully.
status: OK
message: Group newGroup is deleted successfully.
process-admin, manager, admin
newUser, user1, user2
[ { "group1" }, { "group2" } ]
process-admin, manager, admin
{ "name": "newUser", "roles": [ "admin", "developer" ], "groups": [ "group1", "group2" ] }
status: OK
message: User newUser is created successfully.
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
status: OK
message: Password for newUser has been updated successfully.
status: OK
message: User newUser is deleted successfully.
newGroup
status: OK
message: Groups [newGroup] are assigned successfully to user wbadmin
admin
status: OK
message: Roles [admin] are assigned successfully to user wbadmin
{ "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 } }
{ "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 } }
{ "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 } }
{ "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 } }
status: OK
message: Group newGroup permissions are updated successfully.
{ "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 } }
status: OK
message: Role newRole permissions are updated successfully.
editDataObject: yes
plannerAvailable: yes
editGlobalPreferences: yes
editProfilePreferences: yes
accessDataTransfer: yes
jarDownload: yes
editGuidedDecisionTableColumns: yes
{ "pages": { "read": false, "exceptions": [ { "resourceName": "ProcessInstances", "permissions": { "read": false } }, { "resourceName": "ProcessDefinitions", "permissions": { "read": false } } ] } }
"pages": { "create": true, "read": false, "exceptions": [ { "name": "HomePerspective", "permissions": { "read": true } } ] }