Create a Custom Role

API7 Enterprise starts with a locked-down Super Admin role and policy granting full access for initial setup. The default admin account is permanently tied to this role for emergency recovery.

With custom roles, you can create a granular permission system tailored to your specific needs. This tutorial will guide you through the process of defining custom roles in API7 Enterprise, empowering you to manage access control with greater precision.

This tutorial showcases a custom role with view-only access to production gateway group and full access (view & edit) to test gateway group. You will complete the following steps:

1. Create two permission policies, one to define the view-only permission to production gateway group, and another to define the full access to test gateway group.
2. Create a custom role Development Team Member attached to the above two permission policies.

Prerequisites

1. Install API7 Enterprise.
2. Have two gateway groups for test and production environments with at least one gateway instance in each group.
3. Have a published service in both two gateway groups for validation use.
4. (Optional) Learn permission policy examples.

Create Permission Policies

Create Production Permission Policy

1. Select Organization from the top navigation bar, and then select Permission Policies.
2. Click Add Permission Policy.
3. From the dialog box, do the following:

• In the Name field, enter production-gateway-group-view-only.

• In the Policy Editor field, enter the JSON:

    ```json
    {
        "statement": [
            {
                "resources": [
                    "arn:api7:gateway:gatewaygroup/{gateway group id}" // Use gateway group id to match resources
                ],
                "actions": [ // List view permissions to all types of resources in the gateway group. 
                    "gateway:GetGatewayGroup",
                    "gateway:GetGatewayInstance",
                    "gateway:GetConsumer",
                    "gateway:GetSSLCertificate",
                    "gateway:GetGlobalPluginRule",
                    "gateway:GetPluginMetadata",
                    "gateway:GetServiceRegistry",
                    "gateway:GetPublishedService"
                ],
                "effect": "allow" 
            },
            {
                "resources": [
                    "arn:api7:gateway:gatewaygroup/{gateway group id}/publishedservice/<.*>"  // View all published services on this gateway group
                ],
                "actions": [
                    "gateway:GetPublishedService"
                ],
                "effect": "allow"
            }
        ]
    }
    ```
  
    You can also use wildcard grammar as alternative:
  
    ```json
    {
        "statement": [
            {
                "resources": [
                    "arn:api7:gateway:gatewaygroup/{gateway group id}" // Use gateway group id to match resources
                ],
                "actions": [ // Match all actions start with "Get"
                    "<.*>Get<.*>"
                ],
                "effect": "allow" 
            },
            {
                "resources": [
                    "arn:api7:gateway:gatewaygroup/{gateway group id}/publishedservice/<.*>"  // View all published services on this gateway group
                ],
                "actions": [
                    "gateway:GetPublishedService"
                ],
                "effect": "allow"
            }
        ]
    }
    ```

• Click Add.

Create Test Permission Policy

1. Select Organization from the top navigation bar, and then select Permission Policies.
2. Click Add Permission Policy.
3. From the dialog box, do the following:

• In the Name field, enter test-gateway-group-full-access.

• In the Policy Editor field, enter the JSON:

    ```json
    {
        "statement": [
            {
                "resources": [
                    "arn:api7:gateway:gatewaygroup/{gateway group id}" // Use gateway group id to match resources
                ],
                "actions": [ // Include all actions
                    "<.*>"
                ],
                "effect": "allow" 
            },
            {
                "resources": [
                    "arn:api7:gateway:gatewaygroup/{gateway group id}/publishedservice/<.*>"  // Full access to all published services on this gateway group
                ],
                "actions": [
                    "<.*>"
                ],
                "effect": "allow"
            }           
        ]
    }
    ```

• Click Add.

Create Custom Role

1. Select Organization from the top navigation bar, and then select Roles.
2. Click Add Custom Role.
3. From the dialog box, do the following:

• In the Name field, enter Development Team Member.
• (Optional) In the Description field, enter View-only access to production gateway group and full access (view & edit) to test gateway group.
• Click Add.

4. In the role detail page, click Attach Policy.
5. Select production-gateway-group-view-only and test-gateway-group-full-access.
6. Click Submit.

Validate Custom Role

1. Follow the tutorial Update User Roles and assign the Development Team Member to another user, for example Tom.
2. Ask Tom to log in and validate his permissions.

Additional Resources

• Key Concepts
  • Roles and Permission Policies
• Getting Started
  • Update User Roles
• Best Practice
  • Design Custom Role System
• Reference
  • Permission Policy Actions and Resources
  • Permission Policy Examples