Custom role concepts

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 the following key concepts:

• Resources
• Actions
• Roles
• Policies
• Tags

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:

Understanding permissions for accessing resources

The default permission level of any account member in LaunchDarkly is the built-in Reader role. This is the role that is assigned to new account members by default.

To give an account member the ability to modify resources in LaunchDarkly, you must assign them a different role: Writer, Admin, Owner, or a custom role with the appropriate actions.

To prevent an account member from accessing any part of the LaunchDarkly platform, you can assign them the No access role. This role is for members who shouldn't be able to view or modify anything until you give them access to specific areas of LaunchDarkly.

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 members 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.

Roles

When you create a role, you specify the role policy using either the Resource finder or the Advanced editor.

There are two ways to approach writing your own custom roles:

• Allow view-only access by default, then strategically add and deny additional actions as needed. A custom role that has no role policy specified, and the By default, members can view all LaunchDarkly content box checked, allows view access to all resources. You must explicitly grant access to a resource for a member to edit it.
• Deny all actions by default, then strategically allow actions as needed. A custom role that has no role policy specified, and the By default, members can view all LaunchDarkly content box unchecked, denies all access to all resources. You must explicitly grant access to a resource for a member to view or edit it.

For additional discussion on how to decide between these approaches, read the Creating custom roles guide.

Understanding the minimum required actions for a role

As a default state, a blank custom role allows only view access to all resources. You must explicitly grant access to a resource for a member to edit it.

The two exceptions are:

• The viewProject action: The ability to view and change resources is configured at the project resource level with the viewProject action.
• The createAccessToken action: The ability to create personal access tokens is configured at the members resource level with the createAccessToken action. The ability to create service access tokens is configured at the top resource level with the createAccessToken action.

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 member modify the resources they can view. For example, 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 members 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:

• effect
• actions / notActions
• resources / notResources

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

[
  {
    "effect": "allow",
    "actions": ["*"],
    "resources": ["proj/*:env/*:flag/exampleFlag"]
  }
]
COPY

To learn more about specific policies, read Using policies.

Tags

Tags are simple strings that you can attach to most resources 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.

Tag names can include only letters, numbers, periods ., underscores _, and dashes -.

The following resources support tags:

• projects
• environments
• segments
• flags
• metrics

Other resources like webhooks and integrations do not support tags.

To learn more about specific tags, read Using tags.