manage-roles

# Manage Roles Skill Manage Harness RBAC (Role-Based Access Control) via MCP v2 tools. ## MCP v2 Tools Used | Tool | Resource Type | Operations | |------|--------------|------------| | `harness_list` | `role` | List all roles | | `harness_get` | `role` | Get role details | | `harness_create` | `role` | Create custom role | | `harness_update` | `role` | Update custom role | | `harness_delete` | `role` | Delete custom role | | `harness_list` | `role_assignment` | List role assignments | | `harness_get` | `role_assignment` | Get assignment details | | `harness_list` | `permission` | List available permissions | | `harness_get` | `permission` | Get permission details | | `harness_list` | `resource_group` | List resource groups | | `harness_get` | `resource_group` | Get resource group details | | `harness_describe` | `role` | List supported operations and filters for roles | | `harness_schema` | `role` | Get the JSON Schema for `create`/`update` role bodies | | `harness_search` | -- | Search across role-related resources | For built-in roles (account/org/project/module), resource groups, common permissions, and role assignment structure, consult references/builtin-roles.md. ## Instructions ### Step 1: Understand Requirements Determine: - **Who** needs access (user email, group ID, or service account ID) - **What** level of access (admin, developer, viewer, executor, custom) - **Where** (account, org, project scope) - **Which resources** (all or specific resource group) ### Step 2: List Existing Roles ``` harness_list( resource_type="role", org_id="<org>", # optional project_id="<project>", # optional search_term="<keyword>" # optional ) ``` ### Step 3: Check Current Assignments ``` harness_list( resource_type="role_assignment", org_id="<org>", project_id="<project>" ) ``` ### Step 4: List Available Permissions (for custom roles) ``` harness_list(resource_type="permission") ``` ### Step 5: Create Custom Role (if needed) ``` harness_create( resource_type="role", org_id="<org>", project_id="<project>", body={ "identifier": "custom_deployer", "name": "Custom Deployer", "description": "Can execute pipelines and view services", "permissions": [ "core_pipeline_execute", "core_pipeline_view", "core_service_view", "core_environment_view" ] } ) ``` Identifier must match pattern: `^[a-zA-Z_][0-9a-zA-Z_]{0,127}$` ### Step 6: View Resource Groups ``` harness_list(resource_type="resource_group", org_id="<org>", project_id="<project>") ``` ## Examples ### List all roles in a project ``` /manage-roles Show me all roles available in the payments project ``` ### Check who has admin access ``` /manage-roles List all role assignments with admin privileges in the default org ``` ### Create a custom read-only deployer role ``` /manage-roles Create a custom role called "release-manager" that can execute pipelines, view services and environments, but cannot edit anything ``` ### Audit access for a user ``` /manage-roles What roles does jane.smith@company.com have across all projects? ``` ### Review resource groups ``` /manage-roles Show me all resource groups and what they include ``` ## Best Practices - **Prefer groups over individual users** -- assign roles to USER_GROUP for easier management - **Follow least privilege** -- start with viewer roles and add permissions as needed - **Scope narrowly** -- use project-level roles over account-level when possible - **Use built-in roles first** -- create custom roles only when built-in roles do not fit - **Naming convention:** `{role}_{principal}` for identifiers (e.g., `deployer_ops_team`) ## Error Handling | Error | Cause | Solution | |-------|-------|----------| | Role not found | Invalid role identifier | Built-in roles start with `_` -- verify exact identifier | | Resource group not found | Invalid resource group | Check `harness_list(resource_type="resource_group")` | | Principal not found | User/group/SA does not exist | Verify the principal exists before assigning | | Duplicate identifier | Role with same ID exists | Use a unique identifier or update the existing role | | Permission denied | Caller lacks RBAC management permissions | Need `core_role_view` / `core_role_edit` permissions | ## Performance Notes - List existing roles and resource groups before creating new ones to avoid duplication. - Verify role permissions match the principle of least privilege. - Confirm user/group identifiers are correct before assigning roles — incorrect assignments may grant unintended access. ## Troubleshooting ### User Cannot Access Resources 1. List role assignments for the user to confirm a role is assigned 2. Check the role has the required permissions (`harness_get` on the role) 3. Verify the resource group scope includes the target resources 4. Check that the assignment is not `disabled: true` ### Custom Role Not Working 1. Verify all required permissions are included (e.g., `_view` permission is needed alongside `_edit`) 2. Check the role is assigned at the correct scope (account/org/project) 3. Confirm the resource group matches the resources the user needs ### Permission Denied When Managing Roles 1. The caller needs `core_role_edit` to create/update roles 2. The caller needs `core_roleassignment_edit` to manage assignments 3. Account-level operations require account admin or equivalent