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

EDIT ON GITHUB

Active Directory Federation Services (ADFS)

Read time: 3 minutes
Last edited: Jan 05, 2022

Overview

This topic explains how to configure SSO integration between a self-hosted Active Directory Federation Services (ADFS) server and LaunchDarkly.

ADFS is a service provided by Microsoft as a standard role for Windows Server. It provides a web login using existing Active Directory credentials.

Troubleshooting ADFS-based SSO

If you need information about ADFS errors during configuration, troubleshoot it by accessing the ADFS logs in the Windows Event Viewer.

Prerequisites

To give your team access to LaunchDarkly through ADFS, you need the following components:

  • An Enterprise LaunchDarkly account.
  • A signed SSL certificate.
  • An Active Directory instance where all users have an email address attribute.
  • A Microsoft Server instance with ADFS installed and configured.
Setting up ADFS

This topic does not tell you how to set up ADFS. To learn how to set up ADFS, read Microsoft's documentation.

Setting up LaunchDarkly fields

Here is a table explaining LaunchDarkly fields:

LaunchDarkly fieldNotes
Sign-on URLCopy the Token Signing certificate to a Base-64 encoded x.509 file and import it into LaunchDarkly
X.509 certificateDefault value: https://YOUR-DOMAIN/adfs/ls/.
If the default value fails, confirm that the endpoint is enabled and the URL path is correct.
Find the endpoint in Service > Endpoints Search for an endpoint with the SAML 2.0/WS-Federation type.

For more information on configuring LaunchDarkly's SSO, read Single sign-on.

Adding Relying Party Trust

To add Rely Party Trust:

  1. Log into the ADFS Management tool.
  2. Click Add Relying Party Trust.... The Add Relying Party Trust Wizard opens:
The Add Relying Party Trust field is called out.
The Add Relying Party Trust field is called out.
  1. Click Start. Keep the default value, which is Claims aware:
The Welcome screen for the setup wizard.
The Welcome screen for the setup wizard.
  1. Choose Enter data about the relying party manually:
The Select Data Source screen.
The Select Data Source screen.
  1. Click Next. The "Specify Display Name" screen opens.
  2. Set a display name of your choosing.
  3. Click Next. The "Configure Certificate" screen opens.
  4. You do not need to choose a certificate. Click Next.
  5. Select Enable support for the SAML 2.0 WebSSO protocol.
  6. Enter the Assertion consumer service URL from the SSO section of LaunchDarkly into the Relying party SAML 2.0 SSO service URL field.
  7. Click Next.
  8. In the Relying party trust identifier field, enter app.launchdarkly.com.
  9. Click Add.
  10. Click Next. The "Choose Access control Policy" screen opens.
  11. You do not need to change any access control policies. Click Next.
  12. Review your changes and click Next.
  13. If you are satisfied with the configuration, click Close.

After you have successfully completed this procedure, a new LaunchDarkly trust will appear in the ADFS Management tool.

Setting up Claim issuance Policies

To set up a Claim Issuance Policy:

  1. Log into the ADFS Management tool.
  2. Select the LaunchDarkly Trust.
  3. Click Edit Claim Issuance Policy... in the dropdown. The "Edit Claim Issuance Policy" window opens.
  4. Click Add Rule.
  5. Set Claim rule template to Transform an Incoming Claim.
  6. Click Next:
The Select Rule Template screen.
The Select Rule Template screen.
  1. Set the following options:
  • Claim rule name: Enter a human-readable name, such as "Email to NameID".
  • Incoming claim type: E-Mail Address
  • Outgoing claim type: Name ID
  • Outgoing name ID format: Email
  1. Select Pass through all claim values.
  2. Click Finish.

ADFS is now configured with LaunchDarkly.

For more information on claim rules, read Microsoft's Create a Rule to Transform an Incoming Claim.

Configuring custom roles

You can map LaunchDarkly custom role attributes to ADFS using a Claim issuance Policy. To learn more about SSO provisioning for roles and custom roles, read Custom attributes.

Before you can map custom role attributes, you must get your ADFS groups. To learn how, read Microsoft's Microsoft's Create a Rule to Send Claims Using a Custom Rule.

Your rule will look something like this:

The edit rule window.
The edit rule window.

To send claims using a custom rule:

  1. Log into the ADFS Management tool.
  2. Select LaunchDarkly Trust.
  3. Click Edit Claim Issuance Policy... in the dropdown. The "Edit Claim Issuance Policy" window opens.
  4. Click Add Rule.
  5. Set Claim rule template to Send Claims using a custom rule.
  6. Click Next.
  7. Enter a human-readable name, such as "Map groups to LD custom roles".
  8. In the Custom rule window, enter the following:
 c:[Type == "http://temp/variable"]
 => issue(Type = "customRole", Value = c.Value)

Here is an image of the custom rule:

A custom rule entered in the edit rule window.
A custom rule entered in the edit rule window.
  1. Click OK.

You can now assign ADFS members to custom role groups using the "Member of" tab within user properties.

Test drive and enable

After you successfully complete the procedures in this topic, you can log in through ADFS when test drive is enabled. For more information about test drive, read Test drive mode.

If you are able to successfully log in with test drive enabled, you can enable SSO fully. For more information about enabling SSO, read Enabling SSO.