Creating & Managing Roles

Master AuthTuna's role-based access control system — from basic role creation to advanced permission management

The Power of Roles

Roles are the cornerstone of AuthTuna's authorization system. They group permissions together, making it easy to manage what users can do. Unlike individual permissions, roles can be assigned with different scopes, enabling fine-grained access control.

Permission Bundles

Roles collect related permissions into manageable groups, making authorization logic cleaner and more maintainable.

Scoped Assignment

Assign roles with specific scopes (like "project:123") to limit access to particular resources or contexts.

Hierarchical Grants

Higher-level roles can assign lower-level roles, creating natural authority hierarchies.

Creating Roles

Creating a role involves defining its properties and assigning appropriate permissions. AuthTuna supports both hierarchical roles (with levels) and flat organizational roles.

Role Properties

namestring (required)

descriptionstring (optional)

levelint (optional)

systembool (default: False)

Role Types

Hierarchical Roles

Have a level (1-100) for admin hierarchies

Organizational Roles

Flat roles for teams/orgs (level = 0)

System Role

It is a special role for performing automated processes

Creating a Role

from authtuna.integrations import auth_service 

role_manager = auth_service.roles

# Create a hierarchical admin role
admin_role = await role_manager.create(
    name="ContentModerator",
    description="Can moderate user-generated content",
    level=25
)

# Create an organizational role
team_lead_role = await role_manager.create(
    name="TeamLead",
    description="Leads a development team",
    # Organizational roles have no level they do not use the hierarchical system.
    # this is so that if you create a with level > 0 it will give permission to manage all these roles
    # to to prevent this this uses grant system 2 see down for more details
)

Assigning Permissions to Roles

Once created, roles need permissions to be useful. AuthTuna allows fine-grained permission assignment with audit trails and validation.

Permission Assignment

Permissions are assigned to roles, not directly to users. This creates a clean separation between authorization logic and user management.

# Assign permissions to our ContentModerator role
await role_manager.add_permission_to_role(
    role_name="ContentModerator",
    permission_name="content:moderate",
    adder_id=current_user.id  # For audit trail
)

await role_manager.add_permission_to_role(
    role_name="ContentModerator",
    permission_name="users:ban",
    adder_id=current_user.id
)

# Assign permissions to TeamLead role
await role_manager.add_permission_to_role(
    role_name="TeamLead",
    permission_name="team:manage_members",
    adder_id=current_user.id
)

✅ What Happens

• Permission is validated (must exist)
• Duplicate assignments are prevented
• Audit log entry is created
• Database relationship is established

❌ Common Mistakes

• Assigning non-existent permissions
• Forgetting audit trail (adder_id)
• Not handling duplicate assignments

Assigning Roles to Users

Role assignment is the final step that grants users their permissions. AuthTuna supports scoped assignments and includes comprehensive authorization checks.

Basic Role Assignment

# Assign ContentModerator role globally
await role_manager.assign_to_user(
    user_id="user_123",
    role_name="ContentModerator",
    assigner_id=current_user.id,
    scope="global"  # Applies everywhere
)

# Assign TeamLead role with specific scope
await role_manager.assign_to_user(
    user_id="user_456",
    role_name="TeamLead",
    assigner_id=current_user.id,
    scope="team:frontend"  # Only for frontend team
)

Understanding Scopes

Scopes limit where a role applies. Use hierarchical scopes like "org:shash/team:frontend"to create fine-grained permissions.

This allows anyone with role "TeamLead" with scope `org:shash/team:frontend`, or "TeamLead" with scope `org:shash` to perform the action.

Examples:
• "global" - Applies everywhere
• "org:company-a" - Specific organization
• "project:web-app" - Specific project
• "team:design" - Specific team

Authorization Pathways

AuthTuna uses three authorization pathways to determine if a user can assign roles. This multi-layered approach provides flexibility and security.

Permission Override

Direct permission like "roles:assign:Admin" bypasses other checks.

# User has "roles:assign:Moderator" permission
await role_manager.assign_to_user(
    user_id="target_user",
    role_name="Moderator",  # Allowed via permission
    assigner_id=current_user.id
)

Direct Role Grants

Roles can be configured to allow assignment of other specific roles.

# Configure that Admin can assign Moderator
await role_manager.grant_relationship(
    granter_role_name="Admin",
    grantable_name="Moderator",
    grantable_manager=role_manager,
    relationship_attr="can_assign_roles"
)

Level Hierarchy

Higher-level roles can assign lower-level roles automatically.

# SuperAdmin (level 100) can assign Admin (level 90)
# Admin (level 90) can assign Moderator (level 50)
# But Moderator (level 50) CANNOT assign Admin (level 90)

await role_manager.assign_to_user(
    user_id="target_user",
    role_name="Moderator",  # Allowed via hierarchy
    assigner_id=admin_user.id
)

Authorization Logic

The three pathways are checked in order with OR logic — if ANY pathway allows the assignment, it's permitted. This provides maximum flexibility while maintaining security.

Advanced Role Management

Querying Role Information

# Get all roles
all_roles = await role_manager.get_all_roles()

# Get users with a specific role
users_with_role = await role_manager.get_users_for_role(
    role_name="Admin",
    scope="global"
)

# Get roles a user can assign
assignable_roles = await role_manager.get_assignable_roles_for_user(
    target_user_id="user_123",
    assigning_user=current_user
)

Removing Roles

# Remove a role from a user
await role_manager.remove_from_user(
    user_id="user_123",
    role_name="ContentModerator",
    remover_id=current_user.id,
    scope="global"
)

Best Practices

✅ Do's

• Use descriptive role names and descriptions
• Leverage scopes for fine-grained control
• Set appropriate role levels for hierarchies
• Always include audit trails (adder_id)
• Use permission overrides for exceptions

🔧 Naming Conventions

• Use PascalCase for role names
• Group related permissions by prefix
• Use consistent scope patterns
• Document role purposes clearly

❌ Don'ts

• Don't assign permissions directly to users
• Don't use global scope when specific scope works
• Don't skip authorization checks
• Don't create roles without clear purposes
• Don't forget to handle role removal

🛡️ Security Tips

• Regularly audit role assignments
• Use principle of least privilege
• Monitor role assignment patterns
• That's all for now.

Key Takeaways

Roles Bundle Permissions: Create logical groupings of permissions for easier management
Scopes Enable Granularity: Use scoped role assignments for fine-grained access control
Three Authorization Pathways: Permission overrides, direct grants, and level hierarchies work together
Always Audit: Include user IDs in all role operations for proper audit trails
Plan Your Hierarchy: Design role levels and relationships carefully for maintainable systems