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

    EDIT ON GITHUB

    Creating custom roles and policies

    Read time: 4 minutes
    Last edited: Aug 09, 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" panel 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 to any resources.
    8. Create a policy in the "Policy" fields.
    9. Click Save role:
    The "Create custom role" panel.
    The "Create custom role" panel.

    You can also use the REST API: Create custom role

    Understanding starting roles

    LaunchDarkly uses the built-in Reader role as the starting point for new custom roles when you create them. 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.

    You can also create custom roles with no access to any LaunchDarkly resources by unchecking the checkbox. To learn how, read Configuring roles with no access.

    The starting role checkbox in the "Create custom role" panel.
    The starting role checkbox in the "Create custom role" panel.

    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 custom role" panel, click into the Choose resources for this policy statement 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. Under Allow or deny actions on the resource, choose an effect from the menu.
    2. Under Choose actions to allow or deny, choose one or more actions for the policy to enforce:
    The "Actions" menu with options selected.
    The "Actions" menu 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" dialog:

    The "Find a resource ID" dialog.
    The "Find a resource ID" dialog.

    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 dialog appears.
    2. Choose Custom. A 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.

    You can also use the REST API: Modify an account member

    Use Teams to assign roles to multiple members

    You can 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 Creating custom roles.

    Viewing an account member's roles

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

    You can also use the REST API: Get account member

    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 view details about a specific custom role. More information is available on the "Role policy details" panel.

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

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

    The "Role policy details" panel.
    The "Role policy details" panel.

    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" panel 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" panel:

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

    You can also use the REST API: Get custom role

    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" panel appears:
    The "Edit custom role policy" panel.
    The "Edit custom role policy" panel.
    1. Change whatever features of the role you wish.
    2. Click Save changes.

    You can also use the REST API: Update custom role

    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" panel appears.
    4. Click Delete role:
    The "Delete role" button.
    The "Delete role" button.

    You can also use the REST API: Delete custom role