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

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 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": "deny",
    "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 Configuring 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 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:

To create a role with the same permissions as a built-in 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 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.

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

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

Project-specific permissions without view access

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

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:

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
• Allow all actions by default, then strategically deny actions as needed

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

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

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

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