Single Sign-On with ADFS

Active Directory Federation Services (ADFS) can be used as an SSO provider for your Buildkite organization. To complete this tutorial, you will need admin privileges for both your ADFS server and Buildkite.

You can also set up SSO providers manually with GraphQL. See the SSO Setup with GraphQL Guide for detailed instructions and code samples.

Step 1. Create a Buildkite SSO Provider

Click the Buildkite Organization Settings' Single Sign On menu item, then choose the ADFS provider from the available options:

Screenshot of the Buildkite SSO Settings Page

On the following page, copy the ACS URL for use in Step 2.

Step 2. Set up Buildkite in the ADFS management console

The instructions below will guide you through using a series of wizards to:

  • Add a 'Relying Party Trust'
  • Add an 'Issuance Transform Rule', a type of 'Claim Rule'
  • Export the Token-signing Certificate
  • Update the Authentication Policy

With these wizards, you'll set up your domain for SSO and retrieve the information the Buildkite team requires to complete the setup process.

This guide was written for, and tested using, Windows Server 2016

Some of the wizard pages and dialog tab names have changed across versions of Windows Server.

For a guide written for Windows Server 2012, the Pagerduty SSO integration guide is very similar to Buildkite. Follow the Pagerduty instructions, and substitute in the Buildkite values from the instructions below.

Step 2.1 Add a Relying Party Trust

From the Actions sidebar, click Add relying party trust... to start the wizard

  1. Welcome: Select Claims aware.
  2. Select data source: Select Enter data about the relying party manually.
  3. Specify display name: Call your relying party Buildkite.
  4. Choose profile: Select ADFS profile.
  5. Configure certificate: Skip this step, as you don't need a token encryption certificate.
  6. Configure URL: Select Enable support for the SAML 2.0 WebSSO protocol. Enter the ACS URL from Buildkite as your Relying party SAML 2.0 SSO service URL.
  7. Configure identifiers: Enter https://<your IDP url>/adfs/services/trust into the Relying party trust identifier field. Click Add to add it to the Relying party trust identifiers list.
  8. Choose Access Control Policy: Choose Permit everyone. You can choose to select specific users, but that will involve further steps that aren't covered by this guide.
  9. Ready to add trust: Review your settings to make sure all the urls are correct.
  10. Finish: Leave the Configure claims issuance policy for this application box checked. Click Close to close the wizard and save your setup.

In the Actions sidebar, you should now have a subheading Buildkite.

Step 2.2 Add an issuance transform rule

From the Buildkite section of the Actions sidebar, click Edit claim issuance policy...

Here we're going to add three rules. Add each rule using the Add Rule button on the Issuance transform rules tab:

Rule 1

  1. Choose rule type: Send LDAP Attributes as claims
  2. Configure claim rule:
    • Claim Rule Name: Get Attributes
    • Attribute Store: Active Directory
    • Mapping of LDAP Attributes to outgoing claim types:
      • LDAP Attribute: Email Addresses, Outgoing claim type: Email address
      • LDAP Attribute: Display-Name, Outgoing claim type: Name
  3. Click Finish to add the rule

Rule 2

  1. Choose rule type: Transform an incoming claim
  2. Configure claim rule:
    • Claim Rule Name: Name ID Transform
    • Incoming Claim Type: Email address
    • Outgoing Claim Type: Name ID
    • Outgoing Name ID Format: Email
    • Select Pass through all claim values
  3. Click Finish to add the rule

Rule 3

  1. Choose rule type: `Send claims using a custom rule`
  2. Configure claim rule:
    • Claim Rule Name: 'Name' Attribute Name Transform
    • Custom Rule:
      c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"]
       => issue(Type = "Name", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType);
  3. Click `Finish` to add the rule
  4. Click `OK` to save and exit the Claim Issuance Policy dialog

For more information on what other attributes Buildkite accepts, see the SAML User Attributes table in the Custom SAML Guide.

Step 2.3 Export the token signing certificate

From the Service section of the ADFS console tree, select the Certificates subsection

  1. Click on the certificate listed under the heading Token-signing
  2. In the CN=ADFS Signing section of the Actions sidebar, click View Certificate...
  3. In the Certificate dialog, select the Details tab
  4. Click the Copy to File... button
  5. Start the Certificate Export Wizard
  6. Export File Format: select Base-64 encoded X.509 (.CER)
  7. File to Export: name your file, and choose where you'd like to export the file
  8. Completing the Certificate Export Wizard: check the settings are correct, and click Finish
  9. Exit the Certificate dialog

Step 2.4 Update the authentication policy

From the Service section of the ADFS console tree, select the Authentication Methods subsection

  1. Under the Primary Authentication Methods header, click the Edit link
  2. In the Intranet section, ensure that the Forms Authentication box is checked
  3. Click OK to exit the dialog

Step 3. Update your Buildkite SSO Provider

On your Buildkite Organization Settings' Single Sign On page, select your ADFS provider from the list of Configured SSO Providers.

Click the 'Edit Settings' button, choose the Manual data option, and enter the IdP data you saved during the previous step:

Login URL The URL where you can log in to your ADFS service. Usually your domain name or IP, with /adfs/ls appended.
Federation Service Identifier The URL that identifies your ADFS service. Usually your domain name or IP, with /adfs/services/trust appended.
X.509 certificate Attach the X.509 certificate that you downloaded during setup

Step 4. Perform a Test Login

Follow the instructions on the provider page to perform a test login. Performing a test login will verify that SSO is working correctly before you activate it for your organization members.

Step 5. Enable the new SSO Provider

Once you've performed a test login you can enable your provider using the Enable button. Activating SSO will not force a log out of existing users, but will cause all new or expired sessions to authorize through ADFS before organization data can be accessed.

If you need to edit or update your ADFS provider settings at any time, you will need to disable the provider first. For more information on disabling a provider, see the disabling SSO section of the SSO overview.