Design Custom Role System

This tutorial will introduce you to how to design and implement a custom role system for your organization. Custom roles allow you to grant users fine-grained access permissions, thereby enhancing security and improving data integrity.

Key Factors

1. Clear Requirements and Goals

First, clearly define the specific requirements and goals for designing your custom role system. For example, do you want to improve application security? Simplify access control management? Or meet more complex access control requirements? Clear requirements can help you better define roles and permissions and choose the right implementation.

2. Reasonable Role Division

Divide roles logically based on application functionality and user responsibilities, ensuring appropriate granularity. This way can avoid overly fine-grained roles that complicate management or overly coarse-grained roles that lack sufficient permission control.

3. Clear Permission Definition

Each role should have a clear definition of permissions. Permission definitions should be clear and easy to understand and align with the responsibilities of the role. Avoid granting too many or irrelevant permissions to the same role.

Reusing permission policies in different roles can be a double-edged sword. It offers benefits for simplicity and management but also introduces potential security risks if not done carefully. If a reused policy is compromised, it can impact all roles that inherit it, potentially granting unauthorized access to multiple resources. This magnifies the potential damage of a security breach. Overly broad policies can make it difficult to implement the principle of least privilege, granting users more access than they strictly need.

4. Clear Hierarchy and Scalability

A user-friendly custom role system should be highly scalable and future-proof. This empowers the separation of duties for assigning users to appropriate roles. Departmental needs can be met with tailored roles and permission policies, reducing reliance on a single "Super Admin" for everyday permission management. Alternatively, group leaders can assign roles and permissions within their teams, ensuring granular control and minimizing impact on other groups.

Use Cases

In general, API7 Enterprise recommends a measured approach to role management within teams. Leverage team lead roles for most scenarios, and consider creating even smaller leadership roles only when a clear need exists and a thorough security review is conducted.

Team-Specific Access Control

Imagine you need an RBAC system that excels at managing shared roles with stable responsibilities across teams (e.g., "Test Engineer," "Development Engineer"). However, it can be challenging when:

• Team Composition Changes Frequently: New members join, or team members switch roles for adjustments.
• Team-Specific Duties Exist: Each team might have unique workflows or responsibilities requiring granular access control.
• Limited User Visibility: Users may not be familiar with colleagues from other teams.

Solution

1. Super Admins and users with the Role Manager custom role (granted the following permissions) are responsible for maintaining all roles in API7 Enterprise:

{
  "statement": [ // Multiple statements within a policy function with an OR relationship.
    {
      "resources": [
        "arn:api7:iam:user/<.*>"
      ],
      "actions": [
        "<.*>"
      ],
      "effect": "allow"
    },
    {
      "resources": [
        "arn:api7:iam:role/<.*>"  // All roles except super admin
      ],
      "actions": [
        "<.*>"
      ],
      "effect": "allow"
    },
    {
      "resources": [
        "arn:api7:iam:permissionpolicy/<.*>" // All permission policies excep super-admin-permission-policy
      ],
      "actions": [
        "<.*>"
      ],
      "effect": "allow"
    }
  ]
}

2. Create a custom role Team Lead with the following permissions. Users assigned this role will be responsible for managing roles within their specific teams.

 {
    "statement": [
        {
            "resources": [
                "arn:api7:iam:users/23w9q4t-ba7e-f310-a1d45b-78jklz1234", // User id of all team members
                "arn:api7:iam:users/n5p1u6y-0df3-4a5b-c90fe1-32kasd789b",
                "arn:api7:iam:users/23w9q4t-ba7e-f310-a1d45b-78jklz1234",
                "arn:api7:iam:users/gt8h2x3-1fe4-5678-d21b0a-98zxc1b546",
                "arn:api7:iam:users/y7u8i9o-pasd-fghj-123456-7klmnop12"
            ],
            "actions": [ // Include all actions required for team management, invite user not included.
                "iam:GetUser",
                "iam:UpdateUserRole",
                "iam:ResetPassword",
                "iam:DeleteUser"
            ],
            "effect": "allow" 
        }
    ]
 }

Team-Specific Role Design

A modularized RBAC system with the team-specific role and permission creation allows each team to manage their own access needs, reducing reliance on Super Admin or Role Manager.

Solution

1. Create a custom role Team Lead with the following two permission policies. Users assigned this role will be responsible for designing and managing roles within their specific teams.

Permission policy 1 for assigning roles to team members:

 {
    "statement": [
        {
            "resources": [
                "arn:api7:iam:users/23w9q4t-ba7e-f310-a1d45b-78jklz1234", // User id of all team members
                "arn:api7:iam:users/n5p1u6y-0df3-4a5b-c90fe1-32kasd789b",
                "arn:api7:iam:users/23w9q4t-ba7e-f310-a1d45b-78jklz1234",
                "arn:api7:iam:users/gt8h2x3-1fe4-5678-d21b0a-98zxc1b546",
                "arn:api7:iam:users/y7u8i9o-pasd-fghj-123456-7klmnop12"
            ],
            "actions": [ // Include all actions required for team management, invite user not included
                "iam:GetUser",
                "iam:UpdateUserRole",
                "iam:ResetPassword",
                "iam:DeleteUser"
            ],
            "effect": "allow" 
        }
    ]
 }

Permission policy 2 for creating custom roles and permission policies for the team:

{
    "statement": [
        {
            "resources": [
                "arn:api7:iam:role/<.*>>",
            ],
            "actions": [ // Include all actions required for role management
                "<.*>"
            ],
            "conditions": {
                "role_label": {
                    "type": "MatchLabel",
                    "options": {
                        "key": "team",
                        "operation": "exact_match",
                        "value": "champion"
                    }
                }
            },
            "effect": "allow" 
        },
        {
            "resources": [
                "arn:api7:iam:permissionpolicy/<.*>>"
            ],
            "actions": [ // Include all actions required for permission policy management
                "<.*>"
            ],
            "conditions": {
                "permissionpolicy_label": {
                    "type": "MatchLabel",
                    "options": {
                        "key": "team",
                        "operation": "exact_match",
                        "value": "champion"
                    }
                }
            },
            "effect": "allow" 
        }
    ]
}

2. As a Team Lead, always include your team's designated label within the resources you create. This ensures proper access control for your roles and permission policies.

3. You can also have shared roles designed by Super Admin or Role Manager, and assign them to your team members.

4. API7 Enterprise allows further delegation within teams. As a Team Lead, you can even create a custom role attached to the same permission policy. This approach can significantly reduce the burden on Team Leaders for managing roles.

While delegation offers efficiency benefits, it is crucial to maintain a balance with security. Excessive layers of role management can lead to complexity and difficulty in managing overall access control.

Additional Resources

• Key Concepts
  • Roles and Permission Policies
• Getting Started
  • Update User Roles
  • Create Custom Role
• Reference
  • Permission Policy Actions and Resources
  • Permission Policy Examples