No results for ""
EXPAND ALL
  • Home
  • API docs

Creating custom roles

Read time: 15 minutes
Last edited: Oct 02, 2024
Custom roles is an Enterprise feature

Custom roles is available to customers on an Enterprise plan. To learn more, read about our pricing. To upgrade your plan, contact Sales.

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.
Using SSO with custom roles is an Enterprise feature

Using SSO with custom roles is available to customers on an Enterprise plan. To learn more, read about our pricing. To upgrade your plan, contact Sales.

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.

Expand direct policy example

This policy denies all actions within the production environment:

[
{
"effect": "deny",
"actions": ["*"],
"resources": ["proj/*:env/production:flag/*"]
}
]
Expand inverse policy example

This policy allows all actions across all environments except production:

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

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:

Role name

Can view data

Can modify data

Can manage account members

Can manage billing

Reader

Writer

Admin

Owner

No access

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.
  4. Enter a name for the role and an optional description.
  5. Click Advanced editor.
  6. Copy the policy for the role you want to recreate and paste it into the Role policy window:
    • Reader role: Copy the reader role policy from from the Reader role policy template.
    • Writer role: because edit permissions are set to deny by default, you must explicitly allow actions for the Writer role. Copy the reader role policy from from the Writer role policy template.
    • Admin role: because edit permissions are set to deny by default, you must explicitly allow actions for the Admin role. Copy the reader role policy from from the Admin role policy template.
    • No access role: Copy the reader role policy from from the No access role policy template.

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 to only 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 only view access to all resources. You must explicitly grant access to a resource for a member to 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

Expand tag-specific permissions custom role

One way to organize access to resources is by tagging individual resources, and then creating custom roles with access based on tags. For example, you can create a dev tag for your environments and use it in a policy to allow access only to development environments. Tags can be added to projects, environments, segments, flags, and metrics.

Here is the code sample to build a custom role that can access resources with a dev tag:

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

Anyone with this custom role can edit resources with a dev tag. This role is useful for a developer or quality assurance (QA) role if you tag your non-production environments with dev.

Project-specific permissions with view access

Expand project-specific permissions with view access custom role

In this example, you will create a "New checkout flow" custom role that has edit permissions in the new-checkout-flow project only, and can view all other projects.

Here is the code sample:

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

Anyone with this custom role can edit all resources within the New-checkout-flow project, and view all other projects. This role is useful for developers or project managers working only on specific projects, but who need visibility into other projects at your organization.

Project-specific permissions without view access

Expand project-specific permissions without view access custom role

In this example, you will create a "New checkout flow" custom role that has edit permissions in the new-checkout-flow project only, but cannot view any other projects.

Here is the code sample:

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

Anyone with this custom role can edit all resources within the new-checkout-flow project, but view no other projects. This role is useful for developers working only on specific projects who don't need visibility into other projects at your organization.

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:

Role

Duties

Permissions

Prod

Non-prod

Administrator

Manage account members and their permissions, assign members to teams, manage billing. Not directly involved with feature releases.

  • Create and manage roles
  • Assign roles to members
  • Manage team permissions

Tech lead

Manage feature releases, monitor and approve flag changes, delegate flag change reviews.

  • Create and edit flags
  • Toggle flags on and off
  • Approve flag changes
  • Assign reviewers
  • Archive flags

Developer/QA

Create and edit flags, manage flags in code, archive flags, toggle flags on and off in test environments only, request reviews. Access only to the specific projects they are working on.

  • Create and edit flags
  • Toggle flags on and off
  • Assign reviewers
  • Archive flags

 

Product owner

Test and manage feature flags in test environments, approve flags going live on Production. Access only to the specific projects they are working on.

  • Toggle flags on and off
  • Approve flag changes
  • Assign reviewers

Support

View only

  • View only

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 two ways to approach writing your own custom roles:

  • View-only access by default, then strategically allow actions as needed
  • Allow all actions by default, then strategically deny actions as needed
Expand View-only access by default

The view-only access by default method is the most secure. LaunchDarkly custom roles are view-only 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:

[
{
"effect": "allow",
"actions": [
"deleteFlag",
"updateTargets",
"updateRules"
],
"resources": ["proj/public:env/*;sandbox,prod:flag/*"]
},
{
"effect": "allow",
"actions": ["*"],
"resources": ["proj/public:env/*;sandbox,prod:segment/*"]
},
{
"effect": "allow",
"actions": ["deleteContextInstances"],
"resources": ["proj/public:env/*;sandbox,prod:context/*"]
}
]
Expand Allow all actions by default

The allow all actions by default method automatically allows members access to new features as they are released. However, we do not consider this a best security practice, because 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.

Here is an example of a custom role that allows all actions, then explicitly denies actions on certain resources in the last statement:

[
{
"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/*"]
}
]

Use LaunchDarkly teams to manage permissions

Teams is an Enterprise feature

Teams is available to customers on an Enterprise plan. To learn more, read about our pricing. To upgrade your plan, contact Sales.

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

Using SCIM to provision members

If you use SCIM to provision members, you will create the roles in LaunchDarkly, but you must configure and manage your account members in the IdP. To learn more, read Enable SCIM provisioning.

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
Expand ADFS details

You can map LaunchDarkly custom role attributes to ADFS using a Claim issuance Policy. To learn how, read Configure custom roles.

After your policy is set up, you can assign members to custom role groups using the Member of tab within the ADFS user properties window.

Expand Entra details

You can map LaunchDarkly role and customRole attributes to Entra using Entra claims. role and customRole can be mapped using any unused Entra source attribute. To learn how, read Map custom roles to Entra user attributes.

After your role and customRole attributes are mapped, include the key of the role for each account member in the mapped fields.

Expand Google Apps details

Before you create the LaunchDarkly app in GSuite, you must create LaunchDarkly-specific fields for roles and custom roles. To learn how, read Assign roles and custom roles with Google Apps.

After your role and customRole attributes are mapped, include the key of the role for each account member in the mapped fields.

Expand Okta details

You can assign custom roles that you created in LaunchDarkly to members through the Okta user interface (UI). To learn how, read Assign custom roles in Okta.

Expand OneLogin details

You can assign custom roles that you created in LaunchDarkly to members through the OneLogin UI. To learn how, read Add users and set roles in 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.

Want to know more? Start a trial.

Your 14-day trial begins as soon as you sign up. Learn to use LaunchDarkly with the app's built-in quick start guide. You'll discover how easy it is to manage the whole feature lifecycle from concept to launch to control.

Want to try it out? Start a trial.