Roles and Permissions

• 1: Required Roles and Permissions
• 2: Working with Roles

1 - Required Roles and Permissions

The Protegrity Agent uses role-based access control (RBAC) to govern access to its features. The Protegrity Policy Cloud gateway enforces all permissions through JSON Web Token (JWT) authentication. The Agent API does not perform permission checks internally.

Roles

The following table lists the permissions assigned to the roles.

For more information about creating the role, refer to Working with Roles.

Permissions

Protegrity Agent API Permissions

These permissions control access to the core Agent endpoints. All endpoints are authenticated using the jwt_token method.

Workbench Permissions

These permissions control access to Workbench features such as policy management and package distribution.

Insight Permissions

These permissions control access to the Insight dashboard.

Administrative Permissions

These permissions control token creation and user management.

2 - Working with Roles

This section describes about creating roles and users for the Protegrity Agent on a Protegrity Policy Cloud cluster. Roles define the features that a user can access. Users inherit permissions from their assigned roles.

For more information about permissions, refer to Required Roles and Permissions.

Prerequisites

• A running PPC cluster with the Protegrity Agent deployed.
• kubectl is configured and is accessible for the target PPC cluster.
• An admin account on the PPC cluster with required permissions to create roles and users.

Retrieving the Gateway Host

To store the PPC gateway address in a shell variable, run the following command .

export GW_HOST="$(kubectl get gateway pty-main -n api-gateway -o jsonpath='{.status.addresses[0].value}')"

The GW_HOST variable is used in every subsequent command.

Generate a JWT Token

Ensure to authenticate as the PPC admin user to obtain a JSON Web Token (JWT). All role and user creation commands require this token.

TOKEN=$(curl -k -s "https://$GW_HOST/api/v1/auth/login/token" \
  -X POST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d "loginname=admin" \
  -d "password=Admin123!" \
  -D - -o /dev/null 2>&1 \
  | grep -i 'pty_access_jwt_token:' \
  | sed 's/pty_access_jwt_token: //' \
  | tr -d '\r') && echo "${TOKEN:0:10}"

A successful response prints the first 10 characters of the token. If the output is empty, verify the admin credentials and gateway address.

Creating Agent Roles

Create one or more roles that bundle the permissions that are required by the users.

This section provides two recommended role skeletons:

• Administrator with complete access permissions
• Viewer with read-only permissions

Complete-Access Role (agent_admin)

This role grants read-write access to all Agent, Workbench, and Insight features.

curl -sk -X POST "https://$GW_HOST/pty/v1/auth/roles" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "agent_admin",
    "description": "Administrator role",
    "permissions": [
      "proagent_conversations_permission",
      "proagent_doc_permission",
      "proagent_health_permission",
      "proagent_liveness_permission",
      "proagent_log_permission",
      "proagent_readiness_permission",
      "proagent_responses_permission",
      "proagent_ui_permission",
      "proagent_version_permission",

      "workbench_certificate_export",
      "workbench_package_export_dynamic",
      "workbench_package_export_encrypted",
      "workbench_policy_manage",
      "workbench_policy_view",

      "insight_admin",
      "insight_viewer",

      "can_create_token"
    ]
  }'

This user inherits all permissions from the agent_admin role.

For more information about the available permissions for agent_admin, refer to Roles.

Read-Only Role (agent_reader)

This role restricts access to read-only operations. The user can view conversations and policies but cannot modify or export them.

curl -sk -X POST "https://$GW_HOST/pty/v1/auth/roles" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "agent_reader",
    "description": "Read-only role",
    "permissions": [
      "proagent_conversations_permission",
      "proagent_doc_permission",
      "proagent_health_permission",
      "proagent_liveness_permission",
      "proagent_log_permission",
      "proagent_readiness_permission",
      "proagent_responses_permission",
      "proagent_ui_permission",
      "proagent_version_permission",

      "workbench_policy_view",

      "insight_viewer",

      "can_create_token"
    ]
  }'

This role excludes workbench_policy_manage, all package export permissions, and insight_admin. The user can view policies and the Insight dashboard but cannot make changes.

For more information about the available permissions for agent_reader, refer to Permissions.

Building a Custom Role

To create a role with any subset of the available permissions, select the required permission from Protegrity Agent Permissions Reference . The JSON payload follows the same structure shown above. Replace the name, description, and permissions array with your values.

curl -sk -X POST "https://$GW_HOST/pty/v1/auth/roles" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<name of custom the role>",
    "description": "<description custom the role>",
    "permissions": [
      <permission 1>,
      <permission 2>,
      <permission 3>
    ]
  }'

Validate Role Creation

To list all roles and confirm your new roles exist, run the following command .

curl -sk -X GET "https://$GW_HOST/pty/v1/auth/roles" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN"

The response includes every role on the PPC cluster. Ensure that agent_admin and agent_reader roles appear in the list.

Create Agent Users

Create user accounts and assign them to the required roles.

Admin User

This user inherits all permissions from the agent_admin role. To create an agent_admin, run the following command.

curl -sk -X POST "https://$GW_HOST/pty/v1/auth/users" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "agent_admin",
    "email": "agent_admin@example.com",
    "firstName": "Agent",
    "lastName": "Admin",
    "enabled": true,
    "password": "Admin123!",
    "roles": [
      "agent_admin"
    ]
  }'

Read-Only User

This user inherits the read-only permissions from the agent_reader role. To create an agent_reader, run the following command.

curl -sk -X POST "https://$GW_HOST/pty/v1/auth/users" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "agent_reader",
    "email": "agent_reader@example.com",
    "firstName": "Agent",
    "lastName": "Reader",
    "enabled": true,
    "password": "Admin123!",
    "roles": [
      "agent_reader"
    ]
  }'
```=

#### User Skeleton Structure

Every user creation request follows the same JSON structure.

```json
{
  "username": "<unique-username>",
  "email": "<email-address>",
  "firstName": "<first-name>",
  "lastName": "<last-name>",
  "enabled": true,
  "password": "<password>",
  "roles": [
    "<role-name-1>",
    "<role-name-2>"
  ]
}

A user can hold multiple roles. The effective permission set is the union of all permissions from every assigned role. For example, assigning both agent_reader and a custom role that includes workbench_policy_manage grants the user both read and write access to policies.

Note: Change the default passwords before deploying to a production environment.

Verify the User Configuration

After creating the users, log in with the new credentials to confirm the accounts are accessible.

curl -k -s "https://$GW_HOST/api/v1/auth/login/token" \
  -X POST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d "loginname=agent_admin" \
  -d "password=Admin123!" \
  -D - -o /dev/null 2>&1 \
  | grep -i 'pty_access_jwt_token:'

A successful response returns a pty_access_jwt_token header. An empty response indicates incorrect credentials or a missing role.