add_permissions.md

Permissions

This doc is for engineers who want to add permissions for features they want to protect using the Access Control System. The permission referred to in this context differs from repository permissions; the latter concerns permissions from code hosts relating to repositories.

Overview

The RBAC system is based on two concepts:

• Namespaces: these refer to resources that are protected by the RBAC system.
• Actions: these are operations that a user can perform in a given namespace.

The source of truth for the Access Control system is the schema.yaml file, which contains the list of namespaces and the actions available to each namespace.

How it works

When Sourcegraph starts, a background job is started that syncs the namespaces and actions into the permissions table in the database.

Permissions are a tuple of a namespace and an action available in that namespace. The background jobs removes actions and namespaces that are in the database but no longer referenced in the schema.yaml file, and adds permissions contained in the schema.yaml file but not in the database.

Once the permissions are synced, they can be used anywhere in Sourcegraph to protect unauthorized access to resources.

Adding Permissions

To add permissions for a new feature, follow these steps:

1. Add the namespace and action to schema.yaml. Namespace string must be unique.

2. Generate the access control constants with the command sg gen. This will generate access control constants for Typescript and Go.

3. Once these constants have been generated, you can protect any resource using the access control system.

   • In Go, you can do this by importing the CheckCurrentUserHasPermission method from the internal/rbac package. Example.

   • In Typescript, you can do this by accessing the authenticated user's permissions and verifying the permission you require is contained in the array. Example