• Home
  • Integrations
  • SDKs
  • Guides
  • API docs
No results for ""
EXPAND ALL

EDIT ON GITHUB

Creating custom roles and policies

Read time: 5 minutes
Last edited: Jan 21, 2022

Overview

This topic explains how to create and implement custom roles and policies in LaunchDarkly.

This topic only describes creating custom roles with the basic policy editor

If you need to use custom roles to address a scenario not covered in the documentation, you can write your own policies with the advanced editor. For examples, read Example policies and templates.

Creating a custom role

Before you can give an account member custom permissions in LaunchDarkly, you must create a custom role to assign to them.

To create a custom role:

  1. Navigate to Account settings.
  2. Click into the Roles tab.
  3. Click Create role. The "Create custom role" screen appears.
  4. Enter a human-readable Name for the role.
  5. Enter a Key for the role.
  6. (Optional) Enter a Description to explain what the role does.
  7. (Optional) Uncheck the "By default, members can view all LaunchDarkly content" box for this role to start with no access.
  8. Create a policy in the "Policy" fields.
  9. Click Save Role:
The "Create custom role" screen.
The "Create custom role" screen.
The base role setting is for Early Access Program customers only

Setting a custom role's base role to no access is limited to a subset of customers in LaunchDarkly's Early Access Program (EAP). If you want access to this feature, email product@launchdarkly.com.

If you keep the "By default, members can view all LaunchDarkly content" box checked, the custom role starts with reader permissions. You can use the role's policy to remove view permissions or allow the ability to modify resources.

If you uncheck the box, the custom role starts with no access permissions. You can use the role's policy to allow view permissions for specific projects or teams, or allow the ability to modify resources. However, if you give access to modify a resource without giving access to view the project the resource is in, the member still won't be able to see the resource.

For example, suppose you create a custom role with this box unchecked but grant access to modify a flag. Members with the role will not have view access to the project in LaunchDarkly, so will not be able to edit the flag from the LaunchDarkly Dashboard. However, they will be able to make changes to the flag using the API.

The base role option checkbox in the "Create custom role" screen.
The base role option checkbox in the "Create custom role" screen.

Creating policies for custom roles

Policies are sets of actions a custom role is allowed or not allowed to take. You can create policies from the Roles tab.

Write policies by hand in the advanced editor

Advanced users can write custom policies of their own with the Advanced editor.

To learn more about writing your own policies, read Using policies.

To create a policy:

  1. Complete the steps in Creating a custom role.
  2. In the "Create a role" screen, click into the Resources field.
  3. Specify a resource this policy affects.
The resource finder can help

Many common LaunchDarkly items are resources, including flags, metrics, and more. If your LaunchDarkly project is large, it may be difficult to find the exact resource you need.

Click Resource finder to choose projects, feature flags, environments, metrics, and roles to add to your policy.

To learn more, read Finding resource IDs.

  1. Choose an Effect from the dropdown.
  2. Choose one or more Actions for the policy to enforce:
The Actions dropdown with options selected.
The Actions dropdown with options selected.
  1. Click Update. The results of your policy display:
A custom policy.
A custom policy.

Finding resource IDs

You can find resource IDs with the resource finder, which you can access with the “resource finder” link in either the simple or advanced editor, or by using the keyboard shortcut + . (Mac) or ctl + . (Windows). All of your environments, members, feature flags, metrics, and roles will be available.

Here is a screenshot of the "Find a resource ID" screen:

The "Find a resource ID" screen.
The "Find a resource ID" screen.

Giving an account member a custom role

After you have created a custom role and policies for it, you must give that role to all members to whom you wish it to apply.

To give a member a custom role:

  1. Navigate to Account settings.
  2. Click into the Members tab and find the account member you wish to give a custom role.
  3. Click that account member's name. The member's Permissions page opens:
The member's Permissions page.
The member's Permissions page.
  1. Click Edit member roles. A modal appears.
  2. Choose Custom. A dropdown menu containing your organization's custom roles appears.
A member's Edit role menu.
A member's Edit role menu.
  1. Choose all the custom roles you wish to give the member.
  2. Click Save roles. You are returned to the permissions page:
The member's Permissions page with updated custom roles.
The member's Permissions page with updated custom roles.
Use Teams to assign roles to multiple members

Use the Teams feature to group a set of members and assign them all the same custom roles. To learn more, read Teams.

You can also assign custom roles through your IdP with SSO or SCIM. For an in-depth guide on how to use custom roles with IdPs, read Managing custom roles with SSO and SCIM.

Viewing an account member's roles

To view the roles for an individual account member, read Viewing an individual member's roles.

Removing an account member's custom role

If an account member changes function or needs their permissions modified, you can remove a custom role from them at any time.

To remove a custom role from a member:

  1. Navigate to Account Settings.
  2. Click into the Members tab and find the account member you wish to remove a custom role from.
  3. Click that account member's name. The member's Permissions page opens.
  4. Click Edit member roles. The Edit role window appears:
A member's Edit role menu.
A member's Edit role menu.
  1. Click the X icon on all the custom roles you wish to remove from the member. You may also choose a built-in role for this member.
  2. Click Save roles.

Viewing custom role details

You can see details about a specific custom role. More information is available on the "Role policy details" screen.

Use the "Role policy details" screen to view detailed information about a custom role, including which projects and feature flags the role has permission to modify. You can also see each action the custom role can perform and what that action does.

Here is a screenshot of the "Role policy details" screen:

The "Role policy details" screen.
The "Role policy details" screen.

To view details for custom roles from the Roles tab:

  1. Navigate to Account settings and click into the Roles tab.
  2. Find the role with details you wish to view and click Details or Edit. The "Role policy details" screen appears:
A role's entry in the Roles tab with the Details button called out.
A role's entry in the Roles tab with the Details button called out.

To view details for custom roles in other parts of the LaunchDarkly user interface (UI), click a custom role's name to open the "Role policy details" screen:

A member's Permissions tab with custom role names called out.
A member's Permissions tab with custom role names called out.

Editing existing custom roles

Edit an existing policy at any time by clicking the pencil icon or add a new policy to a custom role by clicking Add statement.

To edit a custom role:

  1. Navigate to Account settings.
  2. Click into the Roles tab and find the role you wish to edit.
  3. Click Edit role. The "Edit custom role policy" screen appears:
The "Edit custom role policy" screen.
The "Edit custom role policy" screen.
  1. Change whatever features of the role you wish.
  2. Click Save changes.

Deleting custom roles

Delete a custom role from the Account Settings page.

To delete a custom role:

  1. Navigate to Account settings.
  2. Click into the Roles tab and find the role you wish to edit.
  3. Click Edit role. The "Edit custom role" screen appears.
  4. Click Delete role:
The "Delete role" button.
The "Delete role" button.