Role Definitions

Overview

Role Definitions is an automated tool that generates optimized role assignments for your organization based on existing user permissions. It uses a deterministic algorithm to analyze patterns in how users access resources and creates a minimal set of distinct roles that can replace individual permission assignments.

Purpose

This feature helps organizations:

• Simplify access management by reducing the number of individual permission assignments

• Identify permission patterns across users and resources

• Create role-based access control (RBAC) from existing permission data

• Optimize role assignments to minimize the number of distinct roles needed

How It Works

Role Definitions analyzes uploaded permissions data using an algorithm that:

1. Analyzes user-resource-permission mappings from your CSV data

2. Identifies common permission patterns across users

3. Generates a minimal set of distinct roles that cover all permission requirements

4. Assigns appropriate roles to each user based on their permission needs

Step-by-Step Guide

Step 1: Prepare Your CSV File

Create a CSV file with the following structure. Each row represents a single user-resource-permission relationship, showing what permissions a user has on a specific resource.

user_id,resource_id,permissions_for_resource
u1,table_1,"read,write"
u2,table_2,"write,truncate,drop"
u3,table_1,"drop,delete"
u4,database_1,admin
u1,table_2,"write,truncate"

Understanding the data model:

• Each row defines which permissions a user has on a specific resource

• The same user can appear in multiple rows for different resources (e.g., u1 appears twice above)

• The same resource can appear in multiple rows for different users

• The algorithm analyzes these relationships to identify common permission patterns and generate optimal roles

CSV Format Requirements:

The file must follow standard CSV format (RFC 4180 compliant):

• Headers (required, case-sensitive): user_id, resource_id, permissions_for_resource

• All fields are required: Every row must have all three columns with non-empty values

• Empty rows: Automatically skipped during processing

Field Specifications:

• user_id: Unique identifier for each user (e.g., username, email, or ID)

  • Must be a non-empty string

  • Will be used to identify users in the generated role assignments

• resource_id: Identifier for the resource being accessed (e.g., table name, database name, file path)

  • Must be a non-empty string

  • Should use consistent naming across your organization

  • Can be as simple as table_1 or as complex as Azure ARM paths like /subscriptions/1111/resourceGroups/rg-app/providers/Microsoft.Web/sites/api-prod

• permissions_for_resource: Comma-separated list of permissions for this resource

  • Must be a non-empty string

  • Use quotes when permissions contain commas: "read,write,delete"

  • Single permissions can be unquoted: admin

  • Multiple permissions without internal commas can be unquoted: read,write

  • Permissions can be descriptive: Storage Blob Data Reader, SQL DB Contributor + Execute, or "Get Secret,Set Secret"

Example (Azure resources):

user_id,resource_id,permissions_for_resource
az_a1,/subscriptions/1111/resourceGroups/rg-analytics/providers/Microsoft.Storage/storageAccounts/saingest,Storage Blob Data Reader
az_a2,/subscriptions/1111/resourceGroups/rg-analytics/providers/Microsoft.Storage/storageAccounts/saingest,Storage Blob Data Reader + List
az_a1,/subscriptions/1111/resourceGroups/rg-analytics/providers/Microsoft.Storage/storageAccounts/saingest/blobServices/default/containers/raw,"Read,Write,List"
az_c1,/subscriptions/1111/resourceGroups/rg-sec/providers/Microsoft.KeyVault/vaults/kv-prod,"Get Secret,Set Secret"
az_c2,/subscriptions/1111/resourceGroups/rg-sec/providers/Microsoft.KeyVault/vaults/kv-prod,"Get Secret,Set Secret,Delete Secret"

Step 2: Navigate to Role Definitions

1. Open the Veza platform

2. Navigate to Access Intelligence in the left sidebar

3. Click on Role Definitions in the top navigation bar

   

   Role Definitions landing page showing upload interface

Step 3: Upload Your CSV File

1. On the "Uploaded Data" tab, you'll see an upload interface

2. Click the "Upload CSV File" button

3. Select your prepared CSV file

4. The system will parse and validate your file

After uploading, the CSV is parsed and validated for the correct format. Each row is converted into a user-permission mapping. The data is displayed in a preview table for verification.

Step 4: Review Uploaded Data

After a successful upload, you will see a preview table showing all uploaded entries, a search box to filter the data, and the total number of uploaded items.

Uploaded data preview showing CSV entries in table format

Review checklist:

• ✓ Verify all users are present

• ✓ Check that resource IDs are correct

• ✓ Confirm permissions are properly formatted

• ✓ Look for any duplicate or conflicting entries

Step 5: Generate Role Assignments

1. Click the "Generate Role Assignments" button

2. The system will process your data (this may take a few moments)

3. You'll be automatically switched to the "Generated Role Assignments" tab

What happens during generation:

• The algorithm analyzes permission patterns across all users

• Common permission sets are identified and grouped using frequent subset analysis

• Optimal roles are created to minimize redundancy

• Each user is assigned appropriate roles based on their permissions

Step 6: Review Generated Roles

The Generated Role Assignments tab shows:

• Role Assignments: Which roles each user has been assigned

• Distinct Roles: The unique roles created and their permissions

• Statistics:

  • Number of options explored during optimization

  • Number of distinct input permissions

  • Number of distinct output permissions

Understanding the results:

• Each distinct role has a generated name (e.g., "role_1", "role_2")

• Roles contain specific permission sets for resources

• Users may be assigned multiple roles to cover all their permissions

Generated role assignments grouped by user

You can expand individual users to see detailed role assignments:

Expanded user view showing role details and permissions

You can also switch to view results grouped by role to see which users are assigned to each role:

Generated role assignments grouped by role

Step 7: Export Results

1. Click the "Export" button on the Generated Role Assignments tab

2. The results will be downloaded as a CSV file named generated-role-assignments.csv

Export file format:

The exported CSV contains three columns:

• User ID: The unique identifier for each user

• Assigned Roles: Comma-separated list of role names assigned to the user (e.g., role_1,role_2,role_3)

• Assigned Role Definitions: JSON object mapping each role name to its permissions

  • Format: {"role_1": ["permission1", "permission2"], "role_2": ["permission3"]}

  • Contains the complete permission definitions for all roles assigned to that user

Example export:

User ID,Assigned Roles,Assigned Role Definitions
u1,"role_1,role_2","{""role_1"":[""read"",""write""],""role_2"":[""admin""]}"
u2,role_1,"{""role_1"":[""read"",""write""]}"

Each row represents one user with all their assigned roles and the complete permission definitions for those roles.

Role definitions use a deterministic role mining algorithm based on frequent subset analysis. The algorithm:

• Analyzes permission patterns to find common permission sets across users

• Uses a greedy approach to minimize the number of distinct roles

• Produces consistent results with the same input data

• Optimizes for minimal role count while maintaining complete permission coverage

Common Use Cases

1. Database Access Management

Convert individual table/database permissions into database roles:

• Input: Users with various read/write/admin permissions on tables

• Output: Roles like "DatabaseAdmin", "TableReader", "TableWriter"

2. Application Access Control

Transform application-specific permissions into application roles:

• Input: Users with different feature access in an application

• Output: Roles like "BasicUser", "PowerUser", "Administrator"

3. File System Permissions

Consolidate file and folder permissions into file system roles:

• Input: Users with various read/write/delete permissions on folders

• Output: Roles like "ReadOnlyUser", "Contributor", "Owner"

Best Practices

1. Clean your data first: Remove test users and obsolete permissions before uploading

2. Use consistent naming: Ensure resource IDs and permission names are standardized

3. Start with a subset: Test with a small group of users first

4. Review carefully: Verify generated roles make sense for your organization

5. Document changes: Keep track of which roles replace which individual permissions

Troubleshooting

Common Issues

CSV Upload Fails:

If you see an error during CSV upload, check the error message:

• "Invalid CSV format. Please ensure the file has the correct headers."

  • Verify all three required headers are present: user_id, resource_id, permissions_for_resource

  • Headers are case-sensitive and must match exactly

  • Ensure the file is saved as CSV format (not Excel)

• "Invalid CSV format. Please ensure all rows have the required fields."

  • Check that every row has values in all three columns

  • Ensure no cells are empty (all fields must be non-empty strings)

No Roles Generated:

• Ensure you have uploaded data before clicking generate

• Check that permissions are properly formatted

• Verify there are actual permission patterns to mine

Too Many Roles Generated:

• This may indicate highly unique permission sets

• Consider grouping similar resources together

• Review if all permissions are necessary

Limitations

• Maximum CSV file size depends on system configuration

• Processing time increases with the number of unique permission combinations

• The algorithm optimizes for minimal roles, which may not always align with organizational structure

Security Considerations

• Uploaded data is processed in memory and not permanently stored

• Generated roles should be reviewed before implementation

• Export files may contain sensitive permission information

Next Steps

After generating role definitions:

1. Review and refine the generated roles

2. Map roles to your organization's structure

3. Implement roles in your access control system

4. Monitor and adjust as needed

5. Consider automating role assignment for new users