Authorization

Controlling and auditing who can do what to your software infrastructure is critical to the integrity of your business since in most cases, software controls all aspects of the business.

First level of defense: controlling direct access to live resources

Your core level of defense is the access control implemented on the live resources itself: Cloud account credentials, account separation, Cloud and Kubernetes IAM/RBAC, etc.

ConfigHub can never do more than what you permit via these access controls.

ConfigHub does not currently manage or access your secret infrastructure credentials. They are only indirectly used through Targets associated with Bridges provided by Workers that you run, so you can manage those credentials however you are accustomed to doing that.

Access control and Permissions within ConfigHub

ConfigHub allows you to establish another layer of authorization. In many cases, it can be less flexible or at least more cumbersome to provide the right balance between strict access control and efficient self-service using the live infrastructure access controls alone. ConfigHub enables you to delegate control based on your organization's needs.

ConfigHub includes a flexible but simple authorization model that is designed to meet the needs of all types of business operations. ConfigHub uses a medium level of granularity and customization so that granting common permissions is not excessively complicated.

Simplifications include:

• Operations are classified into categories. For instance, Update, Patch, and Delete operations are all classified as the Edit category.
• Permissions are cumulative. For example, the Use category also includes the operations contained within the View category, such as Get and List operations.
• Most permissions are inherited rather than being specified for every individual entity. (Discussed below in more detail.)
• Where permissions are specified for a specific entity, they are represented within that entity directly, as opposed to using a separate API, which simplifies viewing and changing the permissions.
• List operations and bulk operations are automatically filtered by what you are allowed to view.
• Create operations have an independent permission, and the creator is granted permission to Manage entities that they created, for entities supporting individual permissions, such as Spaces. This enables organization members to use ConfigHub relatively freely without impacting the work of other organization members while not gaining access to privileged infrastructure without an explicit grant of permissions. (Permissions levels are discussed in more detail below.)
• Use permissions (discussed below in more detail) facilitate delegation of authority by pre-establishing relationships without the use of robot or service accounts as a layer of indirection to access ConfigHub (in addition to using workers to access infrastructure).

Permissions inheritance

Most entities within ConfigHub (e.g., Filter and Tag) are not particularly sensitive security-wise or privacy-wise and therefore we have chosen not to provide individual fine-grained permission settings for them. Most permissions are controlled at the Organization level and the Space level. The exceptions are the entities mentioned above: Targets and Workers, since they are security-sensitive and can be shared across Spaces.

Spaces are intended to both simplify permission management and also to help users discover entities that "belong" together. For example, imagine you have a platform team who is responsible for setting up the infrastructure on behalf of several app teams. The platform team uses a platform space to keep configuration that should not be accessible and/or is not relevant to app teams.

If needed, permissions may be added to individual configuration Units and Triggers in the future, but it is recommended that you rely on Space-level permissions as much as possible by grouping entities within Spaces appropriately. Note that Triggers, which are used to maintain invariants and enforce policies on configuration data, are configured at the Space level as well. The main reason to add permissions to every entity type would be to enable broader use of the Create permission.

Organization Roles

By default, everyone added to an Organization can perform most actions to most entities within that Organization other than adding new Organization Members. Organization Members can be switched to roles with lower levels of privileges, however.

The roles currently supported are:

• admin: Superuser. Can perform any and all actions to all entities within ConfigHub, including adding and removing Organization Members and changing Organization metadata.
• manager: Can perform most actions to most entities within ConfigHub, except adding and removing Organization Members and changing Organization metadata.
• member: Legacy default Organization Member role currently equivalent to Manager.
• editor: Can change mutable fields other than Permissions and DeleteGates of all Spaces. Can delete Spaces not protected by DeleteGates. Includes user and creator permissions.
• user: Can copy Space entities and the Triggers within them. Includes viewer permissions.
• viewer: Can get and list all Spaces.
• creator: Can create Spaces.
• none: No default permissions at the Organization level.

Note that creator does not provide viewer, editor, or manager permissions at the Organization level. It means that the Organization Member can create and use their own Spaces, but not access other Spaces without explicitly being granted permission.

Permissions settings for Spaces, Workers, and Targets

These entities have a Permissions field, which is a map of operation category to Subjects, which right now is simply a set of users (represented as a map of UserIDs to facilitate lookups and patching).

The general categories are:

• Manage: Can change Permissions, DeleteGates, and DestroyGates (in Units). Includes Edit permissions.
• Edit: Can change other non-readonly, non-immutable fields and delete the entity if DeleteGates is empty. Includes Use and Create permissions.
• Use: Can copy the entity, reference it in other entities, and reference it in non-CRUDL operations. Includes View permissions.
• View: Can read the entity, such as using Get or List APIs, and invoke readonly functions (on Units and Revisions). The view permission allows an actor to see all data for an entity without changing anything. Most organizations should be liberal with granting read permissions because it allows teams to discover and learn on their own.
• Create: Can create new entities. (Not directly usable. See CreateChildren, below.)

One case where permissions are not cumulative is to distinguish permissions on an entity from permissions to access children of that entity. This is most important for Spaces.

• ManageChildren: Can change Permissions, DeleteGates, and DestroyGates (in Units) of child entities. Includes EditChildren permissions.
• EditChildren: Can change other non-readonly, non-immutable fields and delete child entities if DeleteGates is empty. Includes UseChildren and CreateChildren permissions.
• UseChildren: Can copy child entities, reference them in other entities, and reference them in non-CRUDL operations. Includes ViewChildren permissions.
• ViewChildren: Can read child entities, such as using Get or List APIs, and invoke readonly functions (on Units and Revisions).
• CreateChildren: Can create new child entities. Since this does not grant ViewChildren, EditChildren, or ManageChildren permissions, it is recommended to be used only for parents of entities, such as Spaces, which have their own Permissions fields.

There are some Space permissions specific to Unit operations.

• ApproveChildren: Can invoke the Approve API on the Unit(s). Note that recording an approval does not imply that the approval policy will be satisfied.
• TargetEditChildren: Can invoke actions, such as Apply and Destroy, that modify the Targets attached to the Unit(s). Includes View permission for those Units.
• TargetViewChildren: Can invoke actions, such as Refresh and Import, that read from the Targets attached to the Unit(s) and update the Units accordingly. Includes Edit permission for those Units.

ManageChildren includes all of those permissions.

Authorization delegation via Use permissions

ConfigHub's permissions model enables authorization delegation as follows:

1. An Organization member given CreateChildren permission in some Space(s) can create Workers and corresponding Targets.
2. An Organization member given CreateChildren permission, likely in another Space, can create Units.
3. An Organization member given Use permission (potentially via UseChildren) to the Targets and Edit permission (via EditChildren) to the Units can update the Units' TargetIDs to attach the desired Targets to the desired Units. This creates a durable association between them.
4. An Organization member given TargetEditChildren and/or TargetViewChildren permission on the Space containing the Units can invoke Apply, Destroy, Refresh, and/or Import actions on the Units with attached Targets.

Once associations between the Targets and Units have been established, they represent authorization by themselves that can be utilized by Organization members without permission to establish those assocations.

For example, Jane is one of a few people who manages the Bridge Workers and she is reponsible for setting up Targets for teams who need to deploy to certain accounts -- step (1) above. After she create a Target, she grants Use permission to the operations team who needs to deploy to this particular part of the infrastructure. This team can now associate Units with the Target but they cannot otherwise change the Target.

Let's say John is on that team. If John has Use permission on Target T and Edit permission on Unit U, then he can attach Target T to Unit U by setting the TargetID field on the Unit -- step (3) above. Once this association have been created, it represents an authorization for Unit U to be applied to Target T.

So if Jessie has TargetEditChildren permission on the Space containing Unit U, then an Apply will succeed regardless of what permissions Jessie has on Target T -- step (4) above. Similarly, if a CI bot user has TargetEditChildren permission on the Space containing Unit U, it can also perform applies regardless of other permissions.

The choice of this model stems from the nature of a business. A business is a system of business processes that transcend the humans involved with the business. The systems keep running as people join and leave a company. People are responsible for setting up new systems and change or retire existing systems. Once this is done, the systems do the work and people can quit or transfer to other positions while the system keeps running.

Responsibility for the system is based on the org chart. A system should not be owned by a person. It should be owned by a team or group that maps to an organizational unit in the org chart. This allows people to come and go without causing ownership problems.