Configuring SAML SSO
Read time: 7 minutes
Last edited: Mar 04, 2024
Overview
This topic explains how to configure your LaunchDarkly account for SSO.
If you're a LaunchDarkly administrator or account owner, you can configure LaunchDarkly to use your IdP when account members authenticate.
Configure your IdP
To set up a LaunchDarkly connection, follow the instructions for your chosen IdP.
We provide support for the following IdP connectors:
You can only use one identity provider per LaunchDarkly account.
You can use other identity providers with LaunchDarkly, but we do not provide support or configuration guidance for other providers. To learn more, read Supported external identity providers.
Configure LaunchDarkly SAML
To configure SAML within LaunchDarkly:
- Log in to LaunchDarkly as an administrator or account owner.
- Navigate to the "SSO management" section of the Security tab on the Account settings page:
- Click Configure SAML. The SAML configuration panel appears, pre-populated with information you need to set up LaunchDarkly as a SAML application with your identity provider:
To complete SAML configuration, follow the instructions specific to your IdP. The list of IdPs we support is in the Overview.
Specific configuration details vary between IdPs, but the basic process is the same regardless of which IdP you use.
To configure LaunchDarkly with an external IdP:
- Create the SAML application in your IdP. To do this, follow the instructions in the documentation for your IdP.
- Copy the SAML configuration metadata from the IdP into LaunchDarkly's SAML configuration panel.
- Click Save.
Encrypting SAML assertions
If you choose to encrypt SAML assertions, LaunchDarkly uses a private/public key pair for encryption and provides the public key as an X.509 certificate. You can copy this, upload it into your IdP, and configure your IdP to encrypt SAML assertions.
To encrypt SAML assertions sent by your IdP:
- Navigate to the "SSO management" section of the Security tab on the Account settings page.
- Click Configure SAML. The SAML configuration panel appears.
- Click Advanced settings.
- Check the Enable encrypted SAML assertions checkbox.
- LaunchDarkly uses a public/private key pair for encryption and provides the public key as an X.509 certificate. Click the copy icon to copy the certificate contents. You'll need to upload this into your IdP and configure your IdP to encrypt SAML assertions.
- When the existing certificate is close to expiring, LaunchDarkly provides a new one. Select the newer certificate and copy its contents.
- Click Save.
Here is an example of the Advanced settings section of the SAML configuration panel:
Managing expired SAML certificates
If your SAML certificate expires, you may not be able to log in to your LaunchDarkly account through SSO. If this happens, contact Support.
We will disable SSO for your account, allowing you to log in with your original email and password. If you have only ever logged in through SSO, you can use the "Forgot your password?" link to log in. To learn how, read Resetting your password.
You can then update your SAML certificate and re-enable SSO.
Test-drive mode
When LaunchDarkly receives a valid SAML configuration, SSO enters test-drive mode. Test-drive mode lets you test the SSO integration before deploying the change to the rest of your organization.
When SSO is in test-drive mode, you can test authentication through your IdP, but LaunchDarkly's login screen will continue to use regular password-based authentication.
To use SSO in test-drive mode:
- Log into LaunchDarkly as an administrator.
- Navigate to Account settings, then Security and scroll to the "SSO management" section.
- Click Test-drive SSO. This performs the same authentication request flow that occurs for LaunchDarkly-initiated SSO logins:
- (Optional) If you need to make changes to your setup, you can edit your SAML configuration while in test-drive mode.
After your configuration is working as expected, you can set up user provisioning and enable SSO for your organization. You will automatically exit test-drive mode when you enable SSO.
To exit test-drive mode and keep SSO disabled, delete the SAML configuration metadata from the SAML configuration panel.
User provisioning with SAML
New account members will not be able to sign in from LaunchDarkly's login screen until they have accessed LaunchDarkly through your IdP at least once. To learn how, read Initiating login through your IdP.
LaunchDarkly automatically creates accounts for new account members who sign in through your IdP. Every time an account member signs in, LaunchDarkly also updates the account member's profile with user attributes from the IdP. To learn more, read Understanding default roles.
You can configure your identity provider to send the following attributes when the account member signs in to LaunchDarkly. Each attribute is optional. Specify attribute names with the "basic" format. You can also manage custom attributes in LaunchDarkly.
NameID field formatting
LaunchDarkly only supports the use of email addresses in the NameID field. Do not use other types of identifying strings.
Below is an example of an SSO-provided nameID that LaunchDarkly will accept:
<saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">admin@test.com</saml:NameID>
Setting custom attributes
These attributes are available for SAML SSO provisioning and SCIM provisioning:
Attribute name | Attribute format | Availability | Description |
---|---|---|---|
role | string | SSO and SCIM | One of the built-in LaunchDarkly roles: |
customRole | String array, or comma-separated string | SSO and SCIM | A list of the keys of the custom roles to assign to the account member. These replace the member's existing custom roles. If a member has any custom roles, they supersede the built-in role. The elements of the |
teamKey | String array, or comma-separated string | SSO only | A list of the keys of the teams that the account member belongs to. These replace the member's existing teams. The elements of the |
SAML SSO supports the following naming attributes:
firstName
lastName
SCIM provisioning uses the standard naming attributes:
givenName
familyName
Enabling SSO
When you're satisfied with the SSO integration and are ready to enable it for all account members in LaunchDarkly, enable SSO by following the procedure below.
To enable SSO:
- Log into LaunchDarkly as an administrator.
- Navigate Account settings, then Security and scroll to the "SSO management" section.
- Click Turn on SSO. A confirmation dialog appears.
- Click Turn on.
After you enable SSO, the LaunchDarkly login procedure defers to your identity provider for authentication. Account members will no longer be able to log in with their existing LaunchDarkly password.
Additionally, LaunchDarkly administrator and account owners will no longer be able to invite members to the organization. The only way to add additional account members is to have them log in through your IdP.
To learn more about how to remediate SAML assertion consumer errors, read SSO SAML Error Messages.
Disabling SSO
You can disable SSO at any time. When SSO is disabled, any existing members will still be able to sign into LaunchDarkly with their previous passwords, or reset their passwords.
Users that were provisioned through SSO will be required to reset their password in order to sign into LaunchDarkly.
To disable SSO:
- Log into LaunchDarkly as an administrator.
- Navigate Account settings, then Security and scroll to the "SSO management" section.
- Click Turn off SSO. A confirmation dialog appears.
- Click Turn off.
Changing SSO providers
If you need to change SSO providers, you can test drive the new provider in between disconnecting your old provider and enabling your new provider.
Here's how:
- Disable SSO.
- Update your SAML configuration with the new certificate.
- Enable test-drive mode.
- Test the new SSO provider and confirm it is working as expected.
- (Optional) Reconfigure your user provisioning, if needed.
- Re-enable SSO.
Your logged-in account members can still use LaunchDarkly while SSO is disabled. However, if an account member logs out or their session expires while SSO is disabled, they will need to reset their password before they can log back in. For this reason, we recommend changing SSO providers during scheduled down time.