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

EDIT ON GITHUB

Managing custom roles with SSO and SCIM

Read time: 7 minutes
Last edited: Nov 04, 2021

Overview

This guide explains how to manage custom roles when you 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:

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

Prerequisites

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

  • A basic understanding of custom roles within LaunchDarkly. To learn more, read Custom roles.
  • An understanding of SSO and SCIM configuration at your organization and the Identity Provider (IdP) you use. To learn more, read Single sign-on.
  • An understanding of policies in LaunchDarkly. To learn more, read Using policies.
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:

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.

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 an External IdP.

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 User provisioning wtih SCIM.

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.

For example, this policy denies all actions within the production environment:

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

An inverse policy allows or denies actions for all resources except the one listed. For example, this policy allows all actions across all environments except production:

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

To learn more about policies, read Using policies.

Mapping roles

Before you configure SSO to use custom roles, scope out the different roles, teams, and permissions your organization uses. Defining your roles will help you create a policy structure that’s scalable and easy to implement.

Some questions to consider include:

  • How are teams at your organization structured?
  • Who do you want to target with custom roles?
  • Do you have separate QA, Dev, and production teams?
  • What level of access do you need for Engineering leads, QA, support, etc.?
  • What environments do you use within each project?
  • Do projects change frequently or do they last indefinitely?
  • Do you need seperate roles for permissions at the project level and at the 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 maintainance and future access control?

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

Built-in roles and permissions

When you configure custom roles for SSO, start by recreating LaunchDarkly's built-in roles. Recreating built-in roles as the base for SSO roles allows you to use these roles in a way that best fits your organization.

This table displays the built-in roles and their associated permissions that you need to recreate:

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

Recreating built-in roles

Using the advanced editor, create the following roles:

Administrator


To create a role with full administrator permissions across LaunchDarkly:

  1. Navigate to Account settings.
  2. Select 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 policy window:
1[
2 {
3 "effect": "allow",
4 "resources": ["proj/*"],
5 "actions": ["*"]
6 },
7 {
8 "effect": "allow",
9 "resources": ["member/*"],
10 "actions": ["*"]
11 },
12 {
13 "effect": "allow",
14 "resources": ["role/*"],
15 "actions": ["*"]
16 },
17 {
18 "effect": "allow",
19 "resources": ["webhook/*"],
20 "actions": ["*"]
21 },
22 {
23 "effect": "allow",
24 "resources": ["integration/*"],
25 "actions": ["*"]
26 },
27 {
28 "effect": "allow",
29 "resources": ["code-reference-repository/*"],
30 "actions": ["*"]
31 }
32]
  1. Click the "Simple editor" link to go back to the simple editor and view 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.

Repeat the process to create the "reader" and "writer" roles using the following policies.

Reader


To create a role with reader permissions across LaunchDarkly:

  1. Navigate to Account settings.
  2. Select 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 policy window.
1[
2 {
3 "effect": "allow",
4 "resources": ["proj/*"],
5 "actions": ["viewProject"]
6 }
7]
  1. Click Save role.

Writer


To create a role with writer permissions across LaunchDarkly:

  1. Navigate to Account settings.
  2. Select 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 policy window.
1[
2 {
3 "effect": "allow",
4 "resources": ["proj/*"],
5 "actions": ["*"]
6 }
7]
  1. 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 denies all access to all 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.

Example: Tag-specific permissions

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 with access resources with a dev tag:

1{
2 "resources": ["proj/*:env/*:flag/*;dev"],
3 "actions": ["*"],
4 "effect": "allow"
5},
6{
7 "resources": ["proj/*:env/*;dev"],
8 "actions": ["*"],
9 "effect": "allow"
10},
11{
12 "resources": ["proj/*;dev"],
13 "actions": ["*"],
14 "effect": "allow"
15},

Anyone with this custom role can edit resources with a dev tag.

Example: Project-specific permissions with view access

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:

1[
2 {
3 "resources": ["proj/New-checkout-flow:env/*"],
4 "actions": ["*"],
5 "effect": "allow"
6 },
7]

Anyone with this custom role can edit all resources within the New-checkout-flow project, and view all other projects.

Example: Project-specific permissions without view access

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:

1[
2 {
3 "notResources": [
4 "proj/New-checkout-flow"
5 ],
6 "actions": [
7 "*"
8 ],
9 "effect": "deny"
10 },
11 {
12 "resources": [
13 "proj/New-checkout-flow"
14 ],
15 "actions": [
16 "*"
17 ],
18 "effect": "allow"
19 }
20]

Anyone with this custom role can edit all resources within the New-checkout-flow project, but view no other projects.

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

Using custom roles with your IdP

With your custom roles built, you can now manage them using your IdP provider.

When you pass account member information into LaunchDarkly from your IdP provider, 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 attributes.

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

ADFS

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.

Azure

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.

GSuite

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

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

Okta

You can assign custom roles that you created in LaunchDarkly to users through the Okta UI. To learn how, read Assigning custom roles in Okta.

OneLogin

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.

Conclusion

In this guide you have learned about creating custom roles for use with SSO and SCIM. Custom roles and SSO give you the security and flexibility you need to 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 see how easy it is to manage the whole feature lifecycle from concept to launch to control.

Want to try it out? Start a trial.