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 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"
]

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

  1. Identify the relevant API endpoint to which you want to send a request, such as [GET] /groups to retrieve groups in Business Central.

  2. 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. 
    curl -u 'baAdmin:password@1' -H "Accept: application/json" -X GET "http://localhost:8080/business-central/rest/groups"

  3. Execute the request and review the KIE Server response.

    Example server response (JSON): 

    [
  	{
		"group1"
	},
	{
		"group2"
	}
]

  4. 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: 
    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

  5. 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

NameDescriptionTypeRequirement

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

NameDescriptionTypeRequirement

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

NameDescriptionTypeRequirement

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

NameDescriptionTypeRequirement

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

NameDescriptionTypeRequirement

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

NameDescriptionTypeRequirement

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

NameDescriptionTypeRequirement

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

NameDescriptionTypeRequirement

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

NameDescriptionTypeRequirement

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

NameDescriptionTypeRequirement

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

NameDescriptionTypeRequirement

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

NameDescriptionTypeRequirement

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

NameDescriptionTypeRequirement

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 valuePriority

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
		}
	}
]
}