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

    EDIT ON GITHUB

    Okta

    Read time: 7 minutes
    Last edited: Aug 08, 2022

    Overview

    This topic explains how Okta and LaunchDarkly work together to provide user management for your account members. Okta and LaunchDarkly communicate through the System for Cross-domain Identity Management (SCIM) API specification. SCIM is designed to make managing identities in cloud-based applications and services easier.

    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 followed Okta's documentation to Enable Single Sign-On with SAML
    • 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

    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.

    To get started, navigate to the Okta Administrator Dashboard to add an application and search for LaunchDarkly.

    If you have not configured SAML SSO for LaunchDarkly in Okta, you must do that first. To learn more, read How to configure SAML 2.0 for LaunchDarkly in Okta's documentation.

    To authorize Okta to manage your LaunchDarkly account members:

    1. Log in to Okta as an administrator.
    2. Navigate to Applications and click Browse App Integration Catalog.
    3. 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.
    The "Browse App Integration Catalog" screen in Okta, with search results populating.
    1. Click Add. The General Settings page for the LaunchDarkly app appears.
    2. (Optional) Give the app a custom name by modifying the Application Label.
    3. (Optional) Configure the Application Visibility checkboxes however you prefer.
    4. Click Done. The LaunchDarkly Application page appears.

    You just activated the LaunchDarkly app in Okta.

    Granting Okta permission to manage users in LaunchDarkly

    You can use SCIM to connect the LaunchDarkly app to Okta. This lets you provision, manage, and deprovision LaunchDarkly account members in Okta.

    To grant Okta permission to manage account members:

    1. Navigate to the LaunchDarkly app in Okta.

    2. Click the Provisioning tab. The Integration page appears.

    3. Click Configure API Integration:

      The "Integration" page in Okta, with the "Configure API integration" button called out.
      The "Integration" page in Okta, with the "Configure API integration" button called out.
    4. Check the Enable API Integration checkbox and click Save. An authorization window appears.

    5. Click Authenticate with LaunchDarkly. A new browser window appears describing what permissions Okta requires to integrate with LaunchDarkly. Review the permissions and verify that you are comfortable granting them.

    6. Click Authorize. You return to the Integration page.

    7. Click Save. The To App page appears.

    8. 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
    9. Click Save.

    Okta is now connected to LaunchDarkly.

    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:

    1. Navigate to the LaunchDarkly app in Okta.

    2. Click the Sign On tab. The Settings page appears.

    3. Click the Edit button in the top right corner of the Settings page.

    4. Scroll to the "Advanced Sign-on Settings" section and enter your Assertion consumer service URL.

    5. Enter your Entity ID.

    6. In the "Credential Details" section, set the Application username format to "Email":

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

    You have successfully connected Okta and LaunchDarkly.

    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 team. The roles you set up in Okta are passed to LaunchDarkly as user attributes.

    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:

    1. Navigate to the LaunchDarkly app in Okta.
    2. Navigate to the LaunchDarkly app's General Settings page.
    3. Navigate to the Assignments tab.
    4. In the Assign menu, choose "Assign to Groups":
    The "Assign" menu.
    The "Assign" menu.
    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.

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

      The "Assign LaunchDarkly to Groups" screen.
      The "Assign LaunchDarkly to Groups" screen.
    1. 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."

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

      The "Add Another Role" screen.
      The "Add Another Role" screen.
    2. 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.
    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:

    1. Navigate to the "Applications" page within Okta and open the LaunchDarkly app.
    2. 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.
    The "Push Groups" tab within the LaunchDarkly Okta application.
    1. Search for the name of the group you wish you to push, then click save.
    The "Push groups by name" screen in Okta.
    The "Push groups by name" screen in Okta.
    1. 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."
    An active group push in Okta.
    An active group push in Okta.

    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.

    The "Teams" tab showing teams synced with Okta.
    The "Teams" tab showing teams synced with Okta.

    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:

    1. Navigate to the "Applications" page within Okta and open the LaunchDarkly app.
    2. 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.
    The "Push Groups" tab within the LaunchDarkly Okta application.
    1. 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.
    Linking a group to an existing LaunchDarkly team in Okta.
    1. 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."
    An active group push.
    An active group push.

    After the push status in Okta is "Active," you can confirm the team has been marked as "Synced" in the LaunchDarkly UI, and that the team membership matches the group membership in Okta, on the LaunchDarkly Account settings page.

    Teams synced with SCIM.
    Teams synced with SCIM.

    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.
    Unlink and deactivate group push in Okta.

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

    Unlink pushed group in Okta.
    Unlink pushed group in Okta.

    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.