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

EDIT ON GITHUB

Creating custom roles

Read time: 10 minutes
Last edited: Aug 08, 2022
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:

Prerequisites

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

  • An Admin or Owner 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 LaunchDarkly 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 a user is allowed to perform or 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 a user 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 users’ 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 Configuring SAML SSO.

Single sign-on

Single sign-on allows users 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 user if they sign in with the IdP and can pass a role. SCIM allows you to pass a role when creating and managing users as an admin.

To learn more about SCIM, read Enabling SCIM provisioning.

Recreating 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 nameCan view dataCan modify dataCan manage account membersCan manage billing
Reader
Writer
Admin
Owner
No access

Expand each of the sections below to learn how to recreate built-in roles using the advanced editor.

Reader

Expand reader custom role

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

  1. Navigate to Account settings.
  2. Click the Roles tab.
  3. Click Create role.
  4. Enter a name for the role and an optional description.
  5. Click Advanced editor.
  6. Copy the following policy and paste it into the Role policy window:
[
{
"effect": "allow",
"actions": ["viewProject"],
"resources": ["proj/*"]
}
]
  1. Click Save role.

Writer

Expand writer custom role

Because permissions are set to deny by default, you must explicitly allow actions for the Writer role.

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

  1. Navigate to Account settings.
  2. Click the Roles tab.
  3. Click Create role.
  4. Enter a name for the role and an optional description.
  5. Click Advanced editor.
  6. Copy the following policy and paste it into the Role policy window:
[
{
"effect": "allow",
"actions": ["*"],
"resources": ["proj/*"]
}
]
  1. Click Save role.

Administrator

Expand administrator custom role

Because permissions are set to deny by default, you must explicitly allow actions for the Admin role.

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

  1. Navigate to Account settings.
  2. Click the Roles tab.
  3. Click Create role:
The Roles tab under Account settings with the "Create role" button called out.
The Roles tab under Account settings with the "Create role" button called out.
  1. Enter a name for the role and an optional description.
  2. Click Advanced editor.
  3. Copy the following policy and paste it into the Role policy window:
[
{
"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": ["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/*:env/*:user/*"]
},
{
"effect": "allow",
"actions": ["*"],
"resources": ["code-reference-repository/*"]
},
{
"effect": "allow",
"actions": ["*"],
"resources": ["proj/*:env/*:destination/*"]
},
{
"effect": "allow",
"actions": ["*"],
"resources": ["acct"]
}
]
  1. Click "Simple editor." You are returned to the simple editor displaying the policy details. The details should look like the following:
The list of permissions for an Administrator role.
The list of permissions for an Administrator role.
  1. Click Save role.

No access

Expand No access custom role

LaunchDarkly sets role permissions to deny by default, except for the viewProject and createAccessToken actions. You must explicitly deny the viewProject action to recreate the No access role. You do not need to deny the createAccessToken action, because a member can't create an access token if they don't have view permissions.

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

  1. Navigate to Account settings.
  2. Click the Roles tab.
  3. Click Create role:
The Roles tab under Account settings with the "Create role" button called out.
The Roles tab under Account settings with the "Create role" button called out.
  1. Enter a name for the role and an optional description.
  2. Click Advanced editor.
  3. Copy the following policy and paste it into the Role policy window:
[
{
"effect": "deny",
"actions": ["viewProject"],
"resources": ["proj/*"]
}
]
  1. Click "Simple editor." You are returned to the simple editor displaying the policy details.
  2. Click Save role.

These policies can now be used as a starting point to create more custom roles, such as users who have write-access to only specific projects.

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

Mapping roles

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:

RoleDutiesPermissionsProdNon-prod
AdministratorManage 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 leadManage 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/QACreate 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 ownerTest 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
SupportView 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.

Writing 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: This 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.
  • Allow all actions by default, then strategically deny actions as needed: This 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 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": ["deleteUser"],
"resources": ["proj/public:env/*;sandbox,prod:user/*"]
}
]

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": ["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/*:env/*:user/*"]
},
{
"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/*"]
}
]

Using 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 Managing 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 Managing team members.

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

Using custom roles with your IdP

Using SCIM to provision users

If you use SCIM to provision users, you will create the roles in LaunchDarkly, but you must configure and manage your account members in the IdP. To learn more, read Enabling 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 must 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. To learn more about the customRole attribute, read Custom user attributes.

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)
  • Azure
  • 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 Configuring 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 Azure details

You can map LaunchDarkly role and customRole attributes to Azure using Azure claims. role and customRole can be mapped using any unused Azure source attribute. To learn how, read Mapping 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 Assigning 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 users through the Okta user interface (UI). To learn how, read Assigning custom roles in Okta.

Expand OneLogin details

You can assign custom roles that you created in LaunchDarkly to users through the OneLogin UI. To learn how, read Adding Users and Setting Roles in OneLogin.

To learn more, read Configuring 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.