Okta

Read time: 9 minutes

Last edited: Dec 18, 2023

Overview

This topic explains how Okta and LaunchDarkly work together to provide both authentication and provisioning for your account members.

A LaunchDarkly app is available in Okta. You can connect LaunchDarkly and Okta through the Okta UI, give Okta permissions to modify account members in LaunchDarkly, and even integrate LaunchDarkly custom roles with Okta. Optionally, you can also sync groups in Okta with LaunchDarkly teams to automate team member provisioning.

Prerequisites

To use Okta with LaunchDarkly, you must meet the following prerequisites:

You must have Administrator privileges in LaunchDarkly
You must have Administrator privileges in Okta
You must have your Assertion consumer service URL and Entity ID from LaunchDarkly's SAML configuration page
You must have access to the email addresses of the account members you wish to configure

Configuring Okta SAML SSO for LaunchDarkly

To authorize Okta to manage your LaunchDarkly account members:

Log in to Okta as an administrator.
Navigate to Applications and click Browse App Integration Catalog.
In the search bar, type "LaunchDarkly." The LaunchDarkly app appears in the search results:

The "Browse App Integration Catalog" screen in Okta, with search results populating.

Click Add. The General Settings page for the LaunchDarkly app appears.
(Optional) Give the app a custom name by modifying the Application Label.
(Optional) Configure the Application Visibility checkboxes however you prefer.
Click Done. The LaunchDarkly Application page appears.

You just activated the LaunchDarkly app in Okta.

After you have activated the app and confirmed you meet the prerequisites above, follow Okta's documentation to Enable Single Sign-On with SAML.

Using Okta to manage LaunchDarkly members with SCIM

SCIM-based user provisioning is an Enterprise feature

SCIM facilitates real-time user provisioning, which means your IdP can create, update, and deactivate LaunchDarkly members before the first time a user authenticates in LaunchDarkly. User provisioning with SCIM is available to customers on an Enterprise plan. To learn more, read about our pricing. To upgrade your plan, contact Sales.

If you have more than one SCIM connection

If you get an error during configuration that you cannot add an additional SCIM connection, go to the Security tab in LaunchDarkly's Account settings and click Disconnect SCIM. This allows you to connect Okta's SCIM-based protocols to LaunchDarkly.

You can use SCIM to connect the LaunchDarkly app to Okta. This lets you provision, manage, and deprovision LaunchDarkly account members in Okta. If you have not configured SAML SSO for LaunchDarkly in Okta, you must do that first. To learn how, read Configuring Okta SAML SSO for LaunchDarkly.

To grant Okta permission to manage account members:

Navigate to the LaunchDarkly app in Okta.
Click the Provisioning tab. The Integration page appears.
Click Configure API Integration:

The "Integration" page in Okta, with the "Configure API integration" button called out.
Check the Enable API Integration checkbox.
Check the Import Groups checkbox.
Click Save. An authorization window appears.
Click Authenticate with LaunchDarkly. A new browser window appears describing what permissions Okta requires to integrate with LaunchDarkly.
Click Authorize. You return to the Integration page.
Click Save. The To App page appears.
In the Provisioning to App section, click Edit. Fields on the screen become configurable. Set the following fields to Enable:
- Create Users
- Update User Attributes
- Deactivate Users
The "Provisioning to App" page in Okta, with the "Create Users," "Update User Attributes," and "Deactivate Users" options enabled.
Click Save.

Okta is now connected to LaunchDarkly.

To learn more, read Okta's Configuring Okta to Manage LaunchDarkly Users with SCIM guide.

Setting email addresses as the username

Next, you must configure Okta to recognize email addresses as the usernames for individual account members.

How LaunchDarkly and Okta use email addresses

LaunchDarkly stores emails in lowercase, and does not differentiate between usernames and email addresses. You may use one email address with one LaunchDarkly account at a time. Okta uses email addresses as SCIM usernames. If you change a username or email address in Okta or LaunchDarkly after configuration, the corresponding value also changes. Only use lowercase letters to configure email addresses. Email addresses including uppercase letters cause an error.

To configure Okta to recognize email addresses as usernames:

Navigate to the LaunchDarkly app in Okta.
Click the Sign On tab. The Settings page appears.
Click the Edit button in the top right corner of the Settings page.
Scroll to the "Advanced Sign-on Settings" section and enter your Assertion consumer service URL.
Enter your Entity ID.
In the "Credential Details" section, set the Application username format to "Email":

The "Credentials Details" screen, with username format set to "Email."
Click Save.

You have successfully connected Okta and LaunchDarkly.

Deactivating and deleting members

If you have enabled SCIM and you deactivate a user in Okta, then Okta will deactivate the member and remove them from your LaunchDarkly account.

If you have configured Okta SAML SSO but have not enabled SCIM, then deactivating a user in Okta will not automatically remove them from your LaunchDarkly account. In that case, you will need to remove the member from LaunchDarkly manually.

Assigning custom roles in Okta

You can assign custom roles that you created in LaunchDarkly to account members through the Okta UI.

If you use Okta to manage account members, you cannot change back to LaunchDarkly.

SCIM setup takes precedence over LaunchDarkly's configuration options. If you begin to manage account members and their role assignment in Okta, you must continue managing them in Okta for additional changes to take effect.

Use Okta's Group Assignment feature to set up custom roles for a LaunchDarkly account member or group of members. The roles you set up in Okta are passed to LaunchDarkly as member roles.

Account members with multiple roles have permissions combining them

If an Okta user has multiple Okta groups representing different roles, the corresponding LaunchDarkly account member is assigned permissions for all of their roles. For example, if a user is in both a Marketing role and a more permissive Engineering role, they can use the permissions granted by the Engineering role.

To assign custom roles to Okta groups:

Navigate to the LaunchDarkly app in Okta.
Navigate to the LaunchDarkly app's General Settings page.
Navigate to the Assignments tab.
In the Assign menu, choose "Assign to Groups":

Assigning custom roles to one user

You can also specify custom roles for individual Okta users by performing this procedure after choosing Assign to Users in step 3.

Find the groups you want to assign custom roles to and click Assign:

The "Assign LaunchDarkly to Groups" screen.
Enter the key for the custom role you wish to assign to this group. This connects one role to the selected group.

You cannot assign roles and custom roles at the same time

You can assign either a role or a custom role in this step, but not both. If you enter values in both the Role and customRole fields, LaunchDarkly will ignore the Role field. If you want to assign a custom role, leave the Role field set to the default value of "Reader."

Add more custom roles by entering additional keys in the customRole field separated by commas, with no spaces:

The "Add Another Role" screen.
Click Save and Go Back.

Adding custom roles to new users

If you have custom roles already configured in Okta, you can set up custom roles in Attribute Mapping when you first set up a user in Okta:

The Okta LaunchDarkly "Attributes" mapping screen with custom roles available.

Removing existing roles

SAML ignores empty fields if used in Roles or customRoles. To clear all existing roles, enter an empty string "" into the field.

Using Okta to manage LaunchDarkly teams with SCIM

You can use Okta to create new teams in LaunchDarkly, or link an Okta group to an existing team, to maintain team memberships within Okta.

Prerequisites:

You must configure SCIM provisioning in the LaunchDarkly Okta app.
You must have turned on team sync with SCIM.
Any group members that you want to push to a team in LaunchDarkly must already be provisioned and assigned to the LaunchDarkly application in Okta. After you sync an Okta group with a LaunchDarkly team, you will no longer be able to make team membership changes in the LaunchDarkly UI.

You cannot use the same Okta group for assignments and for Group Push

Okta does not support using the same Okta group for assignments and for Group Push. You must create a separate group that is configured to push teams to maintain consistent group membership between Okta and LaunchDarkly. This is a known limitation of Okta's Group Push feature. To learn more, read About Group Push.

Pushing an Okta group to create a new team

To push an Okta group to create a new team in LaunchDarkly:

Navigate to the "Applications" page within Okta and open the LaunchDarkly app.
On the "Push Groups" tab, click Push Groups. Select whether to search for a group by name or by rule.

The "Push Groups" tab within the LaunchDarkly Okta application.

Search for the name of the group you wish you to push, then click save.

The "Push groups by name" screen in Okta.

The group now appears in the LaunchDarkly app's group list. It may take a moment for the "Push Status" column to change from "Pushing" to "Active."

After the push status in Okta is "Active," you can confirm the new team was created and synced with Okta on the Teams tab in LaunchDarkly.

Linking an Okta group to an existing team

LaunchDarkly also supports Group Linking with Okta, which adds the ability to push a group name that already exists within the LaunchDarkly application and link it to that team.

To link an Okta group to an existing LaunchDarkly team:

Navigate to the "Applications" page within Okta and open the LaunchDarkly app.
On the "Push Groups" tab, click Push Groups. Select whether to search for a group by name or by rule.

Find the group you wish to link by searching for its name. Okta will attempt to find a matching team based on the group name.

If Okta doesn't automatically select a group based on the team name, click the "Create Group" menu and select "Link Group," then search for the team you wish to link.

Linking a group to an existing LaunchDarkly team in Okta.

The group now appears in the LaunchDarkly application's group list. It may take a moment for the "Push Status" column to change from "Pushing" to "Active."

After the push status in Okta is "Active," you can confirm the team has been marked as "Synced" in the LaunchDarkly UI.

Unlinking pushed groups in Okta

After you have synced a team with an Okta group, you cannot unsync it. The only way to remove the team is to unlink the pushed group in Okta.

Unlink and deactivate group push in Okta.

To unlink the push group, click the group's push status, choose the "Unlink pushed group" option, then choose "Delete the group in the target app."

Deactivating group push or unlinking a group while leaving the group in LaunchDarkly results in an orphaned team. You will not be able to manage or maintain an orphaned team within the LaunchDarkly UI.

To remove the team, first re-link the team, choose the "Unlink pushed group" option, then choose the "Delete the group in the target app" option.