[Solution Validation] Configuring fine-grained permissions for job tokens

What did we learn

Results

Participants would prefer to use job tokens but are limited by lack of API support and fine grained controls. Across survey participants and moderated interviews, participants placed more importance and preference to defining job token permissions in the API or UI.

The UX of adding permissions in existing project allowlist is acceptable provided there's a default set of permissions to enable adoption without breaking changes to their current jobs and pipelines. Users are also concerned about how to scale this across their organization and its impact on developer efficiency.

Results deck and Dovetail recordings

We issued a survey with 11 participants and presented our solution approaches to 4 participants in a moderated interview setting. Participants were asked about comparing permission definition on job tokens outbound through YAML vs inbound through API/UI:

Outbound definition YAML feedback

  • YAML definition raised concern with developers being able to override permission settings and how it lacks the ability to manage consistent guardrails across projects
  • For 1 out of 4 participants who preferred the YAML option:
    • Developer efficiency is top of mind and the location of job token permission and developers lack of access to this area presents a risk to developer efficiency

Inbound definition through API/UI feedback

  • For the 3 out of 4 participants with preference to the API/UI, we found that:
    • UX of adding permissions to the existing project allowlist is acceptable provided there's default permissions that will not break their pipelines
    • Users express a need to manage job token permissions at scale to minimize the overhead and complexity with managing permissions per projects
    • Prefer an ability to migrate with ease or an instance level control
  • All participants expressed the need to audit permissions both to serve the needs of auditors and developers / pipeline editors

We also validated the following problems:

  • Users need more API support to meet their use cases of pipeline automation and standardization, release management, service to service and cross-project authentication
    • Common use case includes pipeline standardization, automating commit process, release management and endpoint gaps include access to MR comments and tags
  • Security risk with broad API access and lack of fine-grained control to resources, Verbatims from customers include:
    • “Lack of fine-grained token permissions. Having to use API for the entire scope of all projects is far too risky.”

Background

What's this issue all about?

Customers have requested to make pipeline permissions more controllable and flexible. This will improve the security of job tokens by reducing access to API instead of relying on overprivileged permission defaults of the user. The scope of this issue is to review and validate user experience proposals and test with customers on a viable path.

What questions are you trying to answer?

Pipeline permission definition, visibility, and auditability

  1. Where should pipeline permissions be defined for job tokens?
  2. Is it important to be able to view permissions on what that job token can do on a given project for troubleshooting or auditing? How should this be presented to a non-admin?

Pipeline permission security

  1. Today - running a pipeline with a job token is aligned to user membership and its role. Is scoping down the permissions on project an acceptable security model to organizations? When cross-project communication is a factor, relying on user permissions and fine-grained permissions from the calling project acceptable? (Proposal 1)
  2. An alternative model - Is defining who (groups/projects) and what (permissions) can access the resources on X project an acceptable security model? This replicates machine access and the job token permissions are no longer tied to the user. Default permissions may be provided to simplify setup. (Proposal 2)

Permission selection

  1. How should the resource and permission options (write/read/none) be presented to the user? For example, is it important for the consistency of permission option, so access is predictable? Is the coarse level of the resource sufficient (write including CRUD)?

Cross-project access

  1. What is the desired experience to restrict cross-project access?

Opt-in

  1. What is the acceptable experience to opt-in for fine-grained permissions for jobs?

Solutions

🔎 Approach 1: Permissions defined in the yaml to scope down access

Scoped: Single job or all jobs in a pipeline.

Definition via: YAML.

Security:

  • Trust boundary continues to be on the user membership and abides by existing allowlist on projects.
  • Reducing permissions based on the user who ran the pipeline. The permissions will never elevate above the user.

Workflow

job_one:
  permissions:
    <resource_name>: <none, read, write>
    <resource_name>: <none, read, write>

example_job:
  permissions:
    releases: write
    containers: write
permissions:
  <resource_name>: <none, read, write>
  <resource_name>: <none, read, write>

job_one:
  script:
    - echo ...
🔎 Approach 2: Job token permission profile

Scope: All jobs in the project.

Definition via: API / UI.

Security :

  • Trust boundary is on the project itself. The permission profile determines who and what resources can be accessed.
  • For requests on the project itself, there may be default permissions applied to make it easier for setup.
  • For cross-project communication, the profile includes what groups/projects and associated permissions can access its resource.
  • Not dependent on user permissions.

Workflow (example)

  1. Under Settings > CI/CD / Job Token Permission Profile OR Build > Pipeline Security (new page)
  2. Ability to create a permission profile.
    • Job Token Permission Profile
      1. Pick inbound group/project that can access project resources
      2. Permissions allowed on resources from group/project defined above.
    • Includes self or the existing project in what permissions the token can perform. May come with default permissions for easy setup.
  3. Ability to view permission profiles
    • View the available group+project and associated permissions that can access the project resources.
  4. Can be defined in UI or API.
  5. Security
    • Developers+ can view permission profile
    • Maintainers+ can edit permissions.
  6. Future
    1. Scope down by specific jobs for defense in depth measures.
Opt-in
  • Opt-in: If the user configures a solution above, the job automatically evaluates if the group/project has granted it access (allow list) and if the resource permission is allowed. If so, the payload returns the data.

Migration

  • Detect existing usage based on API calls. Create audit log of usage and preselect these permissions.
Permission Selection
  • read: View resources.
  • write: Create/update/delete resources.
  • None: No access to resources.

Considerations

Consideration Description
Handling permission security in non-protected/protected branches Changing the permissions of the pipeline as jobs run based on protection.
Scaling the configuration Defining permissions for hundreds or thousands of projects.
Existing pipelines Handling configuration of fine-grained permissions of existing pipelines versus new pipelines.
Determination of permissions project vs pipeline vs job Assuming customers will need configuration in all three levels, how will permissions be determined?
Implicit use For existing + new implicit use case of job tokens, what is the default permissions?

Research method

What research methodology do you intend to use?

Moderated customer interviews

What persona, persona segment, or customer type experiences the problem most acutely?

What business decisions will be made based on this information?

  • Confidence in moving forward with solution and design path for configuring job token permissions

What, if any, relevant prior research already exists?

Who will be leading the research?

@ipelaez1 with support from @jrandazzo

What timescales do you have in mind for the research?

Interviews in %17.5

Checklist

Edited by Ilonah Pelaez