Custom role concepts
Read time: 6 minutes
Last edited: Dec 02, 2024
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
When you write a custom role, you specify resources that the role can or cannot access, as part of the scope for each policy statement.
LaunchDarkly has many kinds of resources, such as:
- Projects
- Environments
- Feature flags
- Metrics
- Experiments
- Context kinds
- Segments
For a full list of LaunchDarkly 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 the Policy builder.
There are a few ways to approach writing your own custom roles:
- Allow no access by default, then strategically allow actions as needed. This method is the most secure. However, this can create additional work for your administrators, as they must explicitly add permissions to custom roles each time LaunchDarkly releases a new feature.
- Allow all actions by default, then strategically deny actions as needed. We do not consider this a best security practice, because it means that all members, regardless of role, are automatically granted access to new features. Administrators will need to explicitly deny access to new features in custom role policies as needed.
For additional discussion on how to decide between these approaches, read the Creating custom roles guide.
Minimum required actions for a role
As a default state, a blank custom role denies access to all resources. You must explicitly grant access to a resource for a member to view or edit it.
By default, new custom roles cannot take any actions on any resources. However, custom roles created prior to October 2024 had the option to use the built-in Reader role as their starting point, rather than starting with no access.
To check whether this applies to any of your existing custom roles, edit the custom role and look for the warning statement "This role currently has base permissions set to Reader. Members can view all LaunchDarkly content." Uncheck the box to update the role so that it starts with no access and only allows actions based on the statements in its policy.
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 Policy builder to build custom roles by selecting combinations of resources and actions the role is allowed to or forbidden from taking on them.
When a team or account member has two or more custom roles with conflicting permission levels, the more permissive level of access is applied. For example, if a team has one custom role that allows access to a resource, and a member of that team has another custom role that restricts access to a resource, the member is allowed access.
You can create most roles using the graphical Policy builder. If needed, you can also define a role directly in JSON, using the advanced editor.
The advanced editor can cause large permissions changes to sensitive or confidential resources. If you use the advanced editor incorrectly, it is possible to disable your LaunchDarkly project, lock yourself out of your account, or cause other irrevocable changes.
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.
To learn more, read Using the advanced editor.
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:
effectactions/notActionsresources/notResources
The example below shows a policy that allows the role recipient to perform all actions on a flag called exampleFlag:
To learn more about specific policies, read Using policies.
Tags
Tags are simple strings that you can attach to certain resources in LaunchDarkly, including projects, environments, segments, flags, and metrics. Tags 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 roles that only apply to development environments.
To learn more about tags and custom roles, read Using tags.
You can also use the REST API: Tags
Property-based selectors
All resources, such as projects, environments, and flags, have various properties. Some resource properties are available to use in a resource specifier. You can select for resources whose properties match a particular value. For example, you can create policies that apply to all environments that are marked as critical.
To view example custom roles that use property-based selectors, read Example policies and templates.