Custom user roles

Custom user roles are a key component of managing security through the Fine-grained Access Control. In order to allow or deny access using fine-grained access control, you need to grant custom roles to users according to your needs.

Custom roles are similar to the GraphDB system user roles. However, unlike those, custom roles have no inherent rights or restrictions associated with them, and are instead just markers that can be freely granted to any number of users. You can also grant each user any number of custom roles. Thus, custom roles provide the facility for grouping users together for the sake of defining fine-grained access control rules.

Custom roles are identified by the prefix CUSTOM_ in their name. For example, CUSTOM_ROLE_ADMIN and CUSTOM_ADMIN are custom roles, while ROLE_ADMIN (one of the system roles) and ADMIN_ROLE (neither a system role, nor a custom one) are not custom roles.

The names of custom roles are not case sensitive — CUSTOM_ROLE_ADMIN, custom_role_admin and Custom_Role_ADMIN all refer to the same custom role — but they will be normalized to uppercase when returned by API calls and shown in the user interface.

Managing custom roles through Workbench

Granting or revoking custom roles can be done easily through the Workbench UI:

  1. Navigate to to Setup ‣ Users and Access.

  2. Start creating a new user or editing an existing one.

To grant a custom role, simply input the name of the custom role without the CUSTOM_ prefix in the Custom Roles field.

To revoke a custom role, click the x icon of the custom role you want to revoke.

_images/custom-user-roles-create.png

Note

The CUSTOM_ prefix is omitted in the User management view in Workbench for convenience.

Note

The Workbench UI allows you to grant custom roles only to basic Users. Admin and Repository manager users are automatically granted access to all statements and thus assigning custom roles to them has no practical use. However, if you add custom roles to those users through the REST API, they will also be displayed in Workbench.

Custom role management REST API

Custom roles can also be managed through the custom role management REST API, which provides additional capabilities.

Users in a role can be represented as a simple JSON array in the API:

[
  "user1",
  "user2"
]

Conversely, custom roles are described by a simple JSON object where the key is the role name and the value is the user array:

{
  "custom_role1": [
    "user1",
    "user2"
  ],
  "custom_role2": [
    "user1"
  ],
  "custom_role3": [
    "user2",
    "user3"
  ]
}

The API supports the following operations:

List all custom roles and their users

Returns a JSON custom roles object that contains all custom roles and the users associated with each role.

GET /rest/security/custom-roles

Possible response type:

Set all custom roles and their users

Replaces all existing custom roles/users associations with the provided ones. Accepts a JSON custom roles object.

PUT /rest/security/custom-roles

Possible response type:

  • HTTP Status 200 (Created) — The custom roles were successfully updated

  • HTTP Status 400 (Bad Request) — The request is invalid (e.g. one of the provided users does not exist, or one of the provided roles is not a custom role)

List the users of a particular custom role

Returns a JSON array of usernames as strings that contains all users associated with the provided custom role.

GET /rest/security/custom-roles/<customRole>

Possible response type:

  • HTTP Status 200 (OK) — The request was successful, and the response will contain an array of usernames as strings

  • HTTP Status 400 (Bad Request) — The request is invalid (e.g. the provided role is not a custom role)

Set custom role users

Replaces all users in <customRole> with the provided ones. Accepts a JSON array of usernames as strings.

PUT /rest/security/custom-roles/<customRole>

Possible response type:

  • HTTP Status 200 (OK) — The custom role was successfully updated

  • HTTP Status 400 (Bad Request) — The request is invalid (e.g. one of the provided users does not exist, or the provided role is not a custom role)

Grant custom role to user

Adds the provided users to <customRole>. Accepts a JSON array of usernames as strings.

POST /rest/security/custom-roles/<customRole>

Possible response type:

  • HTTP Status 200 (OK) — The custom role was granted to each of the provided users who was not already granted that role

  • HTTP Status 400 (Bad Request) — The request is invalid (e.g. one of the provided users does not exist, or the provided role is not a custom role)

Revoke custom role from user

Removes the provided users from <customRole>. Accepts a JSON array of usernames as strings.

DELETE /rest/security/custom-roles/<customRole>

Possible response type:

  • HTTP Status 204 (No Content) — The custom role was revoked if it was previously granted or no action was taken if the role was not already granted

  • HTTP Status 400 (Bad Request) — The request is invalid (e.g. one of the provided users does not exist, or the provided role is not a custom role)

List all roles associated with a user

Returns a JSON array of roles as strings with the custom roles granted to the provided user.

GET /rest/security/users/<username>/custom-roles

Possible response type:

  • HTTP Status 200 (OK) — The request was successful, and the response will contain a list of custom roles