Zitadel User Role Management Guide#
Overview#
portierX uses Zitadel as its Identity and Access Management (IAM) system with a predefined Role-Based Access Control (RBAC) model. As an organization administrator, you can assign specific roles to users within your organization to control their access to different features and functionalities within the portierX platform.Available Roles#
Your portierX organization has access to five predefined roles, each designed for specific responsibilities within your Physical Identity and Access Management (PIAM) system:1. organization_admin#
Purpose: Full administrative control over the organization (54 total permissions)
Complete user and role management across the organization
Full CRUD operations on all system entities (individuals, credentials, access points)
System configuration including settings, integrations, and audit policies
Exclusive access to user management and system settings pages
Can delete entities and perform all administrative functions
Cannot Do: N/A - Has complete system access
Best For: IT administrators, facility managers, security directors
2. access_manager#
Purpose: Operational management of access systems and credentials (24 total permissions)
Manage individuals, access credentials, and assignments
Configure access points and manage physical access systems
Set up and configure integrations with external systems
Issue and revoke credentials, manage assignments with due dates
Export audit logs and view comprehensive system reports
Cannot Do: Delete individuals or access points, manage users/settings, full audit log access
Best For: Facility managers, security officers, access control specialists
3. credential_manager#
Purpose: Limited credential and individual management (13 total permissions)
Basic individual record management (create, update, view)
Issue, revoke, and assign access credentials
Manage assignments including setting due dates
View credential status and basic audit logs
Cannot Do: Delete/deactivate individuals, manage access points, configure integrations, export audit logs
Best For: Security staff, administrative assistants, credential administrators
4. security_monitor#
Purpose: Read-only monitoring and oversight (4 total permissions)
View-only access to individuals, credentials, assignments, and access points
Monitor audit logs and security events (filtered view)
Access security dashboards for compliance and oversight
Review access patterns and system activity
Cannot Do: Any create, update, or delete operations; no system configuration; limited audit log access
Best For: Security analysts, compliance officers, monitoring staff
5. individual#
Purpose: Self-service access for personal data (4 total permissions)
View own assigned credentials and access history
Access personal dashboard with own activity logs
View basic individual and assignment information (own data only)
Limited system access for personal use
Cannot Do: Any management operations, view other users' data, access administrative features
Best For: Regular employees, contractors, temporary staff
Prerequisites#
To manage user roles, you must have:1.
Organization Admin Role: You need the organization_admin role to assign roles to other users
2.
Active Organization: Users must be part of your organization in Zitadel
3.
Valid User Account: Users must have existing Zitadel accounts in your domain
Accessing User Management#
Method 1: Through portierX Interface#
1.
Login to your portierX application
2.
Navigate to Settings → User (User Management)
3.
The embedded Zitadel console will load within the portierX interface
4.
Navigate to Tab Authorization
5.
You'll see the user authorization interface with change authorization user role capabilities
Method 2: Direct Zitadel Console Access#
1.
Access your Zitadel console directly at: https://auth.portierx.com/ui/console/users
2.
Login with your organization admin credentials
3.
Navigate to the Users section to edit your users
4.
Navigate to the Authorization section to change user authorization user role
Step-by-Step Role Assignment Process#
Finding Users#
1.
Search Users: Use the search functionality to find specific users by: 2.
Filter Users: Apply filters to narrow down the user list:By user status (Active, Inactive, etc.)
By organization membership
Assigning Roles#
1.
Select User: Click on the user you want to modify
2.
Access Role Management: Look for "Grants" or "Project Grants" section
3.
Click "Add Grant" or similar button
Select your portierX project from the list
Choose from the available roles: 4.
Confirm Assignment: Save the changes
Removing Roles#
1.
Select User: Navigate to the user's profile
2.
View Current Grants: Check existing project grants
3.
Find the portierX project grant
Click "Remove" or "Revoke"
Managing Multiple Roles#
Users can have multiple roles assigned simultaneously. For example:A user might have both credential_manager and security_monitor roles
This gives them permissions from both role definitions (17 total permissions in this case)
security_monitor + credential_manager: Security staff with operational capabilities
access_manager + credential_manager: Comprehensive facility management
Avoid Over-Privileging: Be cautious with multiple role assignments - users should only have roles necessary for their job functions
Common Role Assignment Scenarios#
Scenario 1: New Employee Onboarding#
Standard access for new employees with minimal permissions
Can view only their own credentials and access history
Self-service access to personal dashboard and activity logs
Cannot see other users' data or perform any management operations
Recommended default role for all regular staff
Scenario 2: Security Team Member#
Roles: security_monitor + credential_managerCan monitor security events and manage credentials
Has read-only access to audit logs plus credential management capabilities
Can issue/revoke credentials but cannot delete individuals or configure access points
Appropriate for security staff who need both visibility and operational capabilities
Scenario 3: Facility Manager#
Roles: access_manager + credential_managerComprehensive operational control over access systems
Can manage individuals, credentials, assignments, and access points
Has integration configuration capabilities and audit log export
Cannot delete individuals/access points or access user management
Ideal for day-to-day facility and access management operations
Scenario 4: IT Administrator#
Complete system administration with all 54 permissions
Exclusive access to user management and system settings
Can perform all CRUD operations including deletions
Full audit log access and retention policy management
Required role for managing user accounts and system configuration
Best Practices#
Security Guidelines#
1.
Principle of Least Privilege: Assign only the minimum roles necessary for job functionsStart with individual role for all new users
Add operational roles (credential_manager, access_manager) only when needed
Reserve organization_admin for essential administrative staff only
2.
Role Combination Caution: Be careful when assigning multiple rolesaccess_manager + credential_manager = 37 total permissions (high privilege)
Consider if single roles meet the user's actual needs
Document justification for multiple role assignments
3.
Regular Review: Periodically review and audit user role assignmentsMonitor users with multiple roles or high-privilege roles
Remove roles when job functions change
Track organization_admin assignments closely
4.
Role Separation: Distribute administrative responsibilitiesAvoid having only one organization_admin user
Consider separating operational (access_manager) and administrative functions
Use security_monitor for oversight without operational access
Organizational Workflow#
1.
Documentation: Maintain a record of who has which roles and why
2.
Approval Process: Implement an approval workflow for role changes
3.
Training: Ensure users understand their role permissions and responsibilities
4.
Monitoring: Regularly monitor user activities, especially for privileged roles
Role Assignment Matrix#
| Job Function | Recommended Roles | Permission Count | Notes |
|---|
| CEO/Executive | organization_admin | 54 | Full access for oversight |
| IT Manager | organization_admin | 54 | Technical system management |
| Facility Manager | access_manager + credential_manager | 37 | Comprehensive operational control |
| Security Officer | security_monitor + credential_manager | 17 | Security oversight + limited ops |
| HR Manager | credential_manager | 13 | Employee credential management |
| Regular Employee | individual | 4 | Standard user access |
| Contractor | individual | 4 | Limited temporary access |
| Auditor | security_monitor | 4 | Read-only audit access |
Troubleshooting#
Common Issues#
"Cannot Assign Role" Error#
Cause: You might not have organization admin privileges
Solution:Verify you have the organization_admin role
Check that you're in the correct organization context
Contact your system administrator if needed
"User Not Found" Error#
Cause: User might not exist in your organization
Solution:Verify the user exists in Zitadel
Check if they belong to your organization
User might need to be invited to your organization first
"Role Not Available" Error#
Cause: Trying to assign a role that doesn't exist in your project
Solution:Verify you're selecting from the five predefined roles
Check that the project grant includes the desired role
Contact technical support if roles are missing
Permission Denied After Role Assignment#
Cause: Role assignment might not have taken effect or user needs to re-authenticate
Solution:Wait a few minutes for changes to propagate
Ask user to logout and login again
Verify the role was correctly assigned in Zitadel console
"Feature Not Visible" After Role Assignment#
Cause: User's role may not have sufficient permissions for specific UI components
Solution:Check role permissions: individual and security_monitor have very limited access
Verify user needs access to that specific feature (e.g., only organization_admin can manage users)
Consider if multiple roles are needed for the user's job function
Review the role capability matrix to ensure correct role assignment
"Cannot Export Audit Logs" Error#
Cause: Only organization_admin and access_manager can export audit logs
Solution:Verify user has access_manager or organization_admin role
credential_manager and security_monitor can view logs but cannot export
Consider adding access_manager role if export capability is needed
Getting Help#
1.
Check Role Permissions: Review what each role can actually do in the systemindividual: 4 permissions (very limited, personal data only)
security_monitor: 4 permissions (read-only access)
credential_manager: 13 permissions (basic operational tasks)
access_manager: 24 permissions (full operational control)
organization_admin: 54 permissions (complete system access)
2.
Verify Project Configuration: Ensure all roles are properly configured in your Zitadel project
3.
Check Audit Logs: Review recent changes in the security monitor
4.
Contact Support: If issues persist, contact your portierX technical support team
Summary#
Managing user roles in portierX through Zitadel is straightforward once you understand the five predefined roles and their purposes. As an organization admin, you have the power to control access to your PIAM system effectively by assigning the right roles to the right people.Follow the principle of least privilege
Regularly review role assignments
Document your role management decisions
Monitor user activities for security
Modified at 2025-09-12 08:38:57
