• HOME
  • INTEGRATIONS
  • SDKS
  • GUIDES
  • API DOCS
No results for ""
EXPAND ALL
launchdarkly.com

EDIT ON GITHUB

Custom role concepts

Read time: 2 minutes
Last edited: Oct 22, 2020

Overview

This topic is an overview of concepts that are important to creating custom roles. You can create powerful custom roles by using LaunchDarkly's built-in advanced editor.

To write your own custom role, you'll need to understand four key concepts:

  • Resources
  • Actions
  • Policies
  • Tags
The advanced editor is powerful

You can cause large permissions changes to sensitive or confidential resources if you use the advanced editor without understanding permissions and resource types in LaunchDarkly. It is critically important that you read all the documentation in the "Custom roles" section thoroughly before you use the advanced editor to create or modify any custom roles.

Resources

When you write a custom role, you specify resources that the role can or cannot access.

Almost everything in LaunchDarkly is a resource, including:

  • Projects
  • Feature flags
  • Environments
  • Metrics
  • Custom roles

This graphic shows how resources relate to each other:

Resource organization diagram
Resource organization diagram

Understanding permissions for accessing resources

The default permission level of any team member in LaunchDarkly is the built-in reader role. This is the role that is assigned to new team members by default, and is the most limited set of permissions a LaunchDarkly user can have.

To give a team member the ability to modify resources in LaunchDarkly, you must assign them a different role: Writer, Owner / Admin, or a custom role.

To learn more about specific resources, read Using resources.

Actions

Each resource has a set of actions associated with it. By granting a custom role resource-specific actions, you allow or forbid users with that custom role to do things to that resource. For example, you can allow a custom role the ability to delete a project.

To learn more about specific actions, read Using actions.

Understanding the minimum required actions for a role

The default state of a new custom role is to deny every possible action. In most cases, you must explicitly allow each action you wish the role recipient to be able to do.

The one exception is how custom roles use the viewProject action. The ability to view and change resources is configured at the project resource level with the viewProject action.

You do not need to allow a custom role holder to see projects in your LaunchDarkly account. You can deny them viewing access to any project, but by default all roles can view all projects as soon as they are created.

To learn more about configuring the viewProject action, read Creating private projects with custom roles.

Viewing permissions are not the same as permissions that let a user modify the things they can see. Being able to view a project does not mean a role recipient can take action on that project. A role recipient cannot take any actions on the project unless you explicitly permit them.

Policies

Policies combine resources and actions into a set of statements that define what users can or cannot do in LaunchDarkly.

You use LaunchDarkly's advanced editor to build custom roles by writing combinations of resources and actions the role is allowed to or forbidden from taking on them.

Policies are represented as JSON arrays. They require you to use project and environment keys, not names.

Each element in the array is a statement represented as a JSON object with three attributes:

  • resources / notResources
  • effect
  • actions / notActions

The example below shows a policy that allows the role recipient to perform all actions on a flag called exampleFlag:

1[
2 {
3 "effect": "allow",
4 "resources": ["proj/*:env/*:flag/exampleFlag"],
5 "actions": ["*"]
6 }
7]

To learn more about specific policies, read Using policies.

Tags

Tags are simple strings that you can attach to any resource in LaunchDarkly. Tags do not allow or deny role recipients to do anything, but they are useful for grouping resources into a set that you can name in a resource specifier.

For example, you can create a dev tag for your environments and use it in a policy to specify custom rules that only apply to development environments.

The following resources support tags:

  • projects
  • environments
  • segments
  • flags

Other resources like metrics, webhooks, and integrations do not support tags.

To learn more about specific tags, read Using tags.