Creating roles

Overview

This guide explains best practices for creating and managing 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 roles. After you configure them, you can manage roles with your SSO administration rather than in the LaunchDarkly application.

This guide covers:

• Understanding preset roles in LaunchDarkly
• Creating your own roles
• Mapping your current roles
• Using teams to manage permissions
• Using roles with specific IdPs

Prerequisites

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

• An Admin or Owner base role in your LaunchDarkly account, or another role with team management permissions.
• A basic understanding of roles within LaunchDarkly. To learn more, read 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 Members.

Teams

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

To learn more about teams, read Teams.

Roles

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

Every LaunchDarkly account has several preset roles. To learn more about preset roles, read Organization roles and Project roles.

Some organizations prefer to use roles that they create instead of LaunchDarkly’s preset roles. To learn more, read 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.

1
[
2
  {
3
    "effect": "allow",
4
    "actions": ["*"],
5
    "resources": ["proj/*:env/production:flag/*"]
6
  }
7
]

1
[
2
  {
3
    "effect": "allow",
4
    "actions": ["*"],
5
    "notResources": ["proj/*:env/production:flag/*"]
6
  }
7
]

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.

Review LaunchDarkly preset roles

When you are ready to configure roles for your organization, start by reviewing LaunchDarkly’s preset roles. This way, you can determine whether the provided roles meet your organization’s needs.

In some cases, the preset roles use role scope to specify resources. A role scope is a resource type by which a role is a parameterized. When you assign the role to a member or team, you specify the parameter, which is a called a role attribute.

For example, the preset project role “LaunchDarkly Developer” can perform all actions on projects specified in the developerProjectKeys parameter. This means you can assign the Developer role to a member and give them access to a one or more projects of your choosing using the preset role.

In many situations, the LaunchDarkly preset roles will provide all the custom access you need.

You can also use the preset roles as a starting point. For example, you can add additional policy statements to them.

Create your own roles

If you have reviewed LaunchDarkly’s preset roles and determined that your organization needs something different, you can also create your own roles.

When you create a new role, the role allows no access to any resources. You must explicitly grant access to a resource for a member with the role to view or edit that resource.

To learn how to create your own roles, read Creating roles and policies. For additional examples of roles you may find useful, read Example roles and policies.

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.

Map LaunchDarkly roles to your organization

Now that you are familiar with LaunchDarkly’s preset roles and know how to create your own 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?
• 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?

Account members can have more than one role. This is useful if one person performs multiple roles, or performs the same role for many different teams. For example, if an engineer works on several projects but should have no access to projects they are not working on, you could assign them LaunchDarkly “Developer” preset role and specify the projects they have access to. 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 that you create. Assigning multiple roles can make it easier to add and remove sets of permissions as an account member’s duties change.

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

If you don’t want to worry about conflicting permissions within multiple roles, you may want to create additional 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 roles up front to cover all of the possible role combinations.

Write your own roles

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

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

1
[
2
  {
3
    "effect": "allow",
4
    "actions": [
5
      "viewProject"
6
    ],
7
    "resources": ["proj/public"]
8
  },
9
  {
10
    "effect": "allow",
11
    "actions": [
12
      "deleteFlag",
13
      "updateTargets",
14
      "updateRules"
15
    ],
16
    "resources": ["proj/public:env/*;sandbox,prod:flag/*"]
17
  },
18
  {
19
    "effect": "allow",
20
    "actions": ["*"],
21
    "resources": ["proj/public:env/*;sandbox,prod:segment/*"]
22
  }
23
]

1
[
2
  {
3
    "effect": "allow",
4
    "actions": ["*"],
5
    "resources": ["proj/*"]
6
  },
7
  {
8
    "effect": "allow",
9
    "actions": ["*"],
10
    "resources": ["proj/*:env/*"]
11
  },
12
  {
13
    "effect": "allow",
14
    "actions": ["*"],
15
    "resources": ["proj/*:metric/*"]
16
  },
17
  {
18
    "effect": "allow",
19
    "actions": ["*"],
20
    "resources": ["member/*"]
21
  },
22
  {
23
    "effect": "allow",
24
    "actions": ["*"],
25
    "resources": ["member/*:token/*"]
26
  },
27
  {
28
    "effect": "allow",
29
    "actions": ["*"],
30
    "resources": ["pending-request/*"]
31
  },
32
  {
33
    "effect": "allow",
34
    "actions": ["*"],
35
    "resources": ["role/*"]
36
  },
37
  {
38
    "effect": "allow",
39
    "actions": ["*"],
40
    "resources": ["proj/*:env/*:flag/*"]
41
  },
42
  {
43
    "effect": "allow",
44
    "actions": ["*"],
45
    "resources": ["integration/*"]
46
  },
47
  {
48
    "effect": "allow",
49
    "actions": ["*"],
50
    "resources": ["proj/*:env/*:segment/*"]
51
  },
52
  {
53
    "effect": "allow",
54
    "actions": ["*"],
55
    "resources": ["webhook/*"]
56
  },
57
  {
58
    "effect": "allow",
59
    "actions": ["*"],
60
    "resources": ["proj/*:context-kind/*"]
61
  },
62
  {
63
    "effect": "allow",
64
    "actions": ["*"],
65
    "resources": ["code-reference-repository/*"]
66
  },
67
  {
68
    "effect": "allow",
69
    "actions": ["*"],
70
    "resources": ["proj/*:env/*:destination/*"]
71
  },
72
  {
73
    "effect": "allow",
74
    "actions": ["*"],
75
    "resources": ["acct"]
76
  },
77
  {
78
    "effect": "deny",
79
    "actions": [
80
      "updateOn",
81
      "updatePrerequisites",
82
      "updateRules",
83
      "updateTargets",
84
      "updateFallthrough",
85
      "updateOffVariation",
86
      "updateAttachedGoals",
87
      "copyFlagConfigFrom",
88
      "updateFlagDefaultVariations",
89
      "copyFlagConfigTo",
90
      "updateMaintainer"
91
    ],
92
    "resources": ["proj/team-1:env/*;production:flag/*"]
93
  }
94
]

Use LaunchDarkly teams to manage permissions

Teams help large organizations to manage their members and access in LaunchDarkly more easily. Instead of assigning roles to individual members, you can assign a 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 roles to a team, read Assigning roles to teams.

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 roles with your IdP

With your 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 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 Roles.

The fields and methods you must use to pass 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 roles for use within your organization. Using roles with an IdP gives you the security and flexibility you need to easily manage roles, permissions, and account members.