API7 Enterprise 3.2.14.4: Permission Boundary for Refined Permission Management

Zhihuang Lin

Zhihuang Lin

August 15, 2024

Products

API7 Enterprise v3.2.14.4 is officially released, featuring the introduction of the permission boundary to meet the need for more granular user permission management in enterprises.

What Is a Permission Boundary?

A permission boundary, as the name suggests, is like a wall of permissions that defines the maximum scope of permissions a user can have. It is used to restrict the actions that users or roles can perform in the system. Its primary purpose is to enhance system security and prevent the misuse of permissions. By setting this "wall", we can ensure that users can only operate within their scope of responsibilities and cannot access or modify data in the system beyond their authority.

Permission boundaries can reuse existing permission policies in the system or create new permission policies specifically. When a user is assigned a permission boundary, it limits their permissions but does not directly grant them any permissions.

Example

Suppose we create a permission policy that grants service operation and viewing permissions across all gateway groups and assign this policy as a permission boundary to user Tom.

{
  "statement": [
    // Viewing permissions across all gateway groups
    {
      "effect": "allow",
      "resources": [
        "arn:api7:gateway:gatewaygroup/<.*>"
      ],
      "actions": [
        "<.*>Get<.*>"
      ]
    },
    // Service operation permissions across all gateway groups
    {
      "effect": "allow",
      "resources": [
        "*"
      ],
      "actions": [
        "arn:api7:gateway:gatewaygroup/<.*>/publishedservice/<.*>"
      ]
    }
  ]
}

Under such circumstance, Tom's maximum permissions are restricted within this permission policy. Even though a permission boundary is set, it does not mean Tom already has these permissions. Next, we assign Tom a role with the following permission policy:

{
  "statement": [
    // Viewing permissions across all gateway groups
    {
      "effect": "allow",
      "resources": [
        "arn:api7:gateway:gatewaygroup/<.*>"
      ],
      "actions": [
        "<.*>Get<.*>"
      ]
    },
    // Service operation permissions across all gateway groups
    {
      "effect": "allow",
      "resources": [
        "arn:api7:gateway:gatewaygroup/<.*>/publishedservice/<.*>"
      ],
      "actions": [
        "<.*>"
      ]
    },
    // Operation permissions for custom plugins
    {
      "effect": "allow",
      "resources": [
        "arn:api7:gateway:gatewaysetting/*"
      ],
      "actions": [
        "gateway:<.*>CustomPlugin<.*>"
      ]
    }
  ]
}

Although Tom is granted service operation, viewing, and operation permissions for custom plugins across all gateway groups, he will find himself without the permissions to edit custom plugins. This is because we have set a permission boundary for Tom. Unless the permission boundary is adjusted to include permissions related to custom plugins, any additional permissions beyond the boundary are invalid.

How to Use the Permission Boundary Feature?

Create Permission Policies

Permission boundaries can directly reuse permission policies within the system. Before assigning a permission boundary to a user, you need to create a permission policy. Click "Permission Policies" in the system organization menu to enter the list page.

Permission Policies

Then, click "Add Permission Policy" in the upper right corner of the list to enter the creation form.

Add Policy

Fill in the basic information of the permission policy in the form and configure the corresponding policy statements to create the permission policy. Theoretically, the same permission policy can be associated with multiple roles and used as the permission boundary for multiple users, but this practice is not recommended.

Configure Policy

For more conceptual introductions to permission policies, refer to the article What's New in API7 Enterprise 3.4.14: IAM for Granular Access Control. For common policy configuration examples, refer to the document Permission Policy Examples. For the values that can be taken by resources and actions and the corresponding APIs, refer to the document Permission Policy Actions and Resources.

Assign Permission Boundaries

After creating permission policies, you can assign permission boundaries. Click "Users" in the organization menu to enter the user list page.

Users

We can directly assign permission boundaries to new users when inviting them. The invitation form includes a new field for permission boundaries, and the user will be assigned this permission boundary by default upon logging into the system.

Set Boundary

For existing users, you can click the editing icon of the permission boundary on the user details page to configure their permission boundary.

Edit Permission Boundary

When configuring permissions for a user, you can add the permission_boundaries condition to specific operation permissions. For example, in the actions iam:InviteUser (invite user) or iam:UpdateUserBoundary (update user permission boundary), you can further refine permission control by adding the permission_boundaries condition.

Under this condition, you can specify the ID of the permission policy that must be set for the user. Thus, when performing operations like inviting a new user or updating another user's permission boundary, the system will enforce the allocation of the appropriate permission boundary based on these preset rules.

Here is an example demonstrating how to achieve this:

{
  "statement": [
    {
      "effect": "allow",
      "resources": ["arn:api7:iam:user/<.*>"],
      "actions": [
        "iam:InviteUser",
        "iam:UpdateUserBoundary"
      ],
      "conditions": {
        "permission_boundaries": {
          "type": "AllOfStrings",
          "options": [
            "d3698967-1d28-4e37-b5e7-ef00a93304cc",
            "f863a233-f732-4af0-bb21-3fbe4013be69"
          ]
        }
      }
    }
  ]
}

Permission Boundary Mapping

In addition to directly configuring specific permission boundaries within the system, API7 Enterprise also supports Permission Boundary Mapping, which automatically assigns corresponding permission boundaries based on the user's identity and permissions in the IdP (Identity Provider). On the organization settings page, click "Add Login Option". Regardless of which provider is selected, a "Permission Boundary Mapping" switch is added at the bottom of the configuration form. Once enabled, you can configure permission boundary mapping.

Permission Boundary Mapping

  • Permission Policy: This is the permission policy resource defined in API7 Enterprise, used to control user access and operation scope. In permission boundary mapping, we can map configurations from the external IdP to these permission boundaries to assign corresponding permission boundaries to users upon login.

  • Mapped Permission Boundary Attribute: The identifier for user permission boundary information returned by the IdP, used to locate user permission boundary data in the IdP's response. For example, specifying an attribute name like "role" or "groups" will allow the system to extract the permission boundary value from the IdP's response based on this attribute name.

  • Operation: The method used to match the permission boundary value from the IdP's permission boundary attribute. Various methods are supported, such as exact match, fuzzy match, array match, etc. If the IdP returns a string array of permission boundary values, we can choose "Exact Match in Array" to find a match.

  • Mapped Permission Boundary Value: The specific value representing the user's permission boundary in the IdP.

Summary

Overall, permission boundaries are crucial tools for ensuring system security and preventing permission abuse. By clearly defining the scope of user permissions, we can protect key system resources from unauthorized access and ensure that each user can only operate within their authorized range. In complex system environments, effectively utilizing permission boundaries will provide robust protection for an enterprise's data security.

Tags:
RBACPermission ManagementAPI7 Enterprise