Creating custom roles

Overview

This guide explains best practices for managing custom roles and how to use a single-sign-on (SSO) provider for cross-domain identity management (SCIM) provisioning.

You can enforce permissions or restrictions regarding projects, environments, and other resources using custom roles. After you configure them, you can manage custom roles with your SSO administration rather than in the LaunchDarkly application.

This guide covers:

• Recreating built-in roles in LaunchDarkly
• Creating your own custom roles
• Mapping your current custom roles
• Using teams to manage permissions
• Using custom roles with specific IdPs

Prerequisites

To complete this guide, you must have the following prerequisites:

• An Owner or Admin role in your LaunchDarkly account, or a custom role with team management permissions.
• A basic understanding of custom roles within LaunchDarkly. To learn more, read Custom roles.
• Access to the SSO and SCIM configuration at your organization and the Identity Provider (IdP) you use. To learn more, read Single sign-on.

Concepts

You should understand these concepts before reading this guide:

Members

Account members are people who work at your organization or have access rights to your organization's LaunchDarkly environment for another reason, such as contractors or part-time employees.

To learn more about members, read Account members.

Teams

Teams are groups of your organization's members. A LaunchDarkly account administrator can give specific permissions to teams with custom roles that let them perform actions on different resources, such as projects or flags.

To learn more about teams, read Teams.

LaunchDarkly's built-in roles

Every LaunchDarkly account has four built-in roles: Reader, Writer, Admin, and Owner. Customers on an Enterprise plan also have a restricted No access role. Every account member must have at least either one of these built-in roles or a custom role. If you need to, you can also assign account members multiple custom roles to give them the exact set of permissions they need.

To learn more about built-in roles, read LaunchDarkly’s built-in roles.

Custom roles

Custom roles enable organizations to define granular permissions of actions that an account member is allowed to perform or is blocked from performing in LaunchDarkly.

Many organizations prefer to use custom roles instead of LaunchDarkly's built-in roles to access this additional flexibility when they configure SSO or SCIM.

To learn more, read Custom roles.

Policies

A policy in LaunchDarkly is a set of actions a role can or cannot take. Each policy is a list of statements allowing or denying an account member access to resources and actions within LaunchDarkly.

Policies can be direct or inverse. A direct policy allows or denies access to the resource defined. An inverse policy allows or denies actions for all resources except the one listed.

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

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

To learn more about policies, read Using policies.

Identity provider

An identity provider (IdP) is a service that creates, maintains, and manages members’ digital identities and permissions to use applications and services. It functions as a directory, sharing credentials with digital services and devices. IdPs communicate over Security Assertion Markup Language (SAML) or Open Authorization (OAuth).

To learn more about IdP configuration, read Configure SAML SSO.

Single sign-on

Single sign-on allows members to access multiple applications with a single set of login credentials. SSO can be deployed with an IdP to manage credentials and authentication to applications.

SCIM

SCIM is a standard for automating the exchange of information between identity domains, or IT systems.

The SSO workflow within LaunchDarkly creates a new member if they sign in with the IdP and the IdP can pass a role. SCIM allows you to pass a role when creating and managing members as an admin.

To learn more about SCIM, read Enable SCIM provisioning.

Recreate built-in roles

When you are ready to configure custom roles for your organization, start by recreating LaunchDarkly's built-in roles. Recreating built-in roles is useful because you can then build upon them to create similar, but personalized, custom roles. For example, you may want to create a role that gives a member Writer access to one project, but Reader access to all remaining projects.

This table displays the built-in roles and their associated permissions that you will recreate in this guide:

To create a role with the same permissions as a built-in role:

1. Click the gear icon in the left sidenav to view Organization settings.
2. Click Roles.
3. Click Create role. The New role page appears:

4. Enter a Name and Key for the role, and an optional Description.
5. In the "Edit Policy" panel, click View JSON.
6. Copy the policy for the role you want to recreate and paste it into the advanced editor:
   • Reader role: Copy the reader role policy from the Reader role policy template.
   • Writer role: Copy the Writer role policy from the Writer role policy template.
   • Admin role: Copy the Admin role policy from the Admin role policy template.
   • No access role: No action required. By default, custom roles cannot take any actions on any resources. An empty policy is equivalent to the No access role.

Repeat this procedure for each built-in role you want to recreate.

You can now use these policies as a starting point to create more custom roles, such as members who have write access only to specific projects.

Create custom roles

Now that you have LaunchDarkly's built-in roles recreated, you can use them as a foundation to build custom roles to suit your needs.

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

For some actions, access must be granted across all environments to function properly. These actions include:

• createFlag
• deleteFlag
• updateIncludeInSnippet
• updateName
• updateDescription
• updateTemporary
• updateTags
• updateMaintainer
• updateFlagVariations
• updateFlagCustomProperties

To learn more, read Using actions.

Expand each of the sections below to learn how to build example custom roles using the advanced editor.

Tag-specific permissions

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

Project-specific permissions with view access

[
  {
    "effect": "allow",
    "actions": ["*"],
    "resources": ["proj/new-checkout-flow:env/*"]
  },
  {
    "effect": "allow",
    "actions": ["viewProject"],
    "resources": ["proj/*"]
  }
]
COPY

Project-specific permissions without view access

[
  {
    "effect": "allow",
    "actions": ["*"],
    "resources": ["proj/new-checkout-flow"]
  }
]
COPY

For more custom role examples, read Example policies and templates.

Map LaunchDarkly roles to your organization

Now that you know how to create your own custom roles, you can begin thinking about your organization's specific needs. Scoping the different roles, teams, and permissions your organization uses will help you create a policy structure that’s scalable and easy to implement.

Some questions to consider include:

• How are units at your organization structured?
• Do you use LaunchDarkly's teams feature?
• Who do you want to target with custom roles?
• Do you have separate QA, Dev, and Production units?
• What level of access do you need for Engineering leads, QA, support, etc.?
• Do you have a tech lead for each project?
• Do your members need access to multiple projects?
• Should members be able to view projects that aren't their own, or that they aren't working on?
• What environments do you use within each project?
• Do projects change frequently or do they last indefinitely?
• Do you need separate roles for permissions at the flag level, project level, and environment level?
• Do you have an internal approval process for enabling flags in Production?
• Do external organizations ever toggle flags?
• Who will be responsible for maintenance and future access control?
• Do you need policies for service tokens?
• Who should be able to rotate keys?

Here is an example of a role map for an organization:

Account members can have more than one custom role. This is useful if one person performs multiple roles. For example, if an engineer is also a tech lead on only certain projects, you may want to assign them both a "Tech lead" role and a "Developer/QA" role. Assigning multiple roles can make it easier to add and remove sets of permissions as an account member's duties change.

If two custom roles have conflicting permission levels, the more permissive level of access is applied. For example, if a member has one custom role that allows access to a resource, and another custom role that denies access to that resource, the member is granted access.

If you don't want to worry about conflicting permissions within multiple custom roles, you may want to create additional custom roles, such as a "Tech lead + QA" role, that includes access needed for both. This eliminates the complexity of managing multiple roles per member, but requires that you create more custom roles up front to cover all of the possible role combinations.

Write your own custom roles

There are a few ways to approach writing your own custom roles:

• Allow no access by default, then strategically allow actions as needed
• Allow all actions by default, then strategically deny actions as needed

Expand No access by default

Allowing no access by default is the most secure. LaunchDarkly custom roles are no access by default, so your LaunchDarkly administrators must modify your custom role policies to allow individual actions. 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.

Here is an example of a custom role that explicitly allows actions only on certain resources:

View-only by default

[
  {
    "effect": "allow",
    "actions": [
      "deleteFlag",
      "updateTargets",
      "updateRules"
    ],
    "resources": ["proj/public:env/*;sandbox,prod:flag/*"]
  },
  {
    "effect": "allow",
    "actions": ["*"],
    "resources": ["proj/public:env/*;sandbox,prod:segment/*"]
  }
]
COPY

Older custom roles may have read-only access to all resources by default

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

[
  {
    "effect": "allow",
    "actions": ["*"],
    "resources": ["proj/*"]
  },
  {
    "effect": "allow",
    "actions": ["*"],
    "resources": ["proj/*:env/*"]
  },
  {
    "effect": "allow",
    "actions": ["*"],
    "resources": ["proj/*:metric/*"]
  },
  {
    "effect": "allow",
    "actions": ["*"],
    "resources": ["member/*"]
  },
  {
    "effect": "allow",
    "actions": ["*"],
    "resources": ["member/*:token/*"]
  },
  {
    "effect": "allow",
    "actions": ["*"],
    "resources": ["pending-request/*"]
  },
  {
    "effect": "allow",
    "actions": ["*"],
    "resources": ["role/*"]
  },
  {
    "effect": "allow",
    "actions": ["*"],
    "resources": ["proj/*:env/*:flag/*"]
  },
  {
    "effect": "allow",
    "actions": ["*"],
    "resources": ["integration/*"]
  },
  {
    "effect": "allow",
    "actions": ["*"],
    "resources": ["proj/*:env/*:segment/*"]
  },
  {
    "effect": "allow",
    "actions": ["*"],
    "resources": ["webhook/*"]
  },
  {
    "effect": "allow",
    "actions": ["*"],
    "resources": ["proj/*:context-kind/*"]
  },
  {
    "effect": "allow",
    "actions": ["*"],
    "resources": ["code-reference-repository/*"]
  },
  {
    "effect": "allow",
    "actions": ["*"],
    "resources": ["proj/*:env/*:destination/*"]
  },
  {
    "effect": "allow",
    "actions": ["*"],
    "resources": ["acct"]
  },
  {
    "effect": "deny",
    "actions": [
      "updateOn",
      "updatePrerequisites",
      "updateRules",
      "updateTargets",
      "updateFallthrough",
      "updateOffVariation",
      "updateAttachedGoals",
      "copyFlagConfigFrom",
      "updateFlagDefaultVariations",
      "copyFlagConfigTo",
      "updateMaintainer"
    ],
    "resources": ["proj/team-1:env/*;production:flag/*"]
  }
]
COPY

Use LaunchDarkly teams to manage permissions

Teams help large organizations to more easily manage their members and access in LaunchDarkly. Instead of assigning custom roles to individual members, you can assign a custom role to a team, then add members to the team. If you update or add permissions to the team, all the team members inherit those permissions automatically. To learn how to add custom roles to a team, read Manage team permissions.

Removing members from the team revokes any permissions the team granted to them. To learn how to add or remove members from a team, read Manage team members.

To learn more about best practices when using teams, read Building teams in LaunchDarkly.

Use custom roles with your IdP

With your custom roles designed and built, you can now manage them using SSO and your IdP.

When you pass account member information into LaunchDarkly from your IdP, you can include the key of the member's custom role in a customRole attribute, along with their other profile information such as name and email address, if you want to update those fields. To learn more about the customRole attribute, read Custom roles.

The fields and methods you must use to pass custom role information to LaunchDarkly differ depending on your IdP. We provide configuration guidance for the following IdPs:

• Active Directory Federation Services (ADFS)
• Entra ID
• Google Apps
• Okta
• OneLogin

To learn more, read Configure SAML SSO.

Conclusion

In this guide you have learned about creating custom roles for use within your organization. Using custom roles with an IdP gives you the security and flexibility you need to easily manage roles, permissions, and account members.