Single sign-on with Azure Active Directory (Azure AD)

Step 1. Create a Buildkite SSO provider

In your Buildkite organization Settings, click Single Sign On, then choose the custom SAML provider from the available options:

1. Choose the Provide IdP Metadata Later option when configuring your custom SAML provider
2. Copy the Assertion Consumer Service (ACS) URL for use in Step 2

Step 2. Add Buildkite in Azure AD

In your Azure Admin Console, follow these instructions:

1. Choose Azure Active Directory, and under Quick actions, choose Add enterprise application.
2. Click + Create your own application.
3. Give your application a name, for example 'Buildkite'.
4. Choose Integrate any other application you don't find in the gallery (Non-gallery) and click Create.
5. Choose Set up single sign on, then SAML, then in the Basic SAML Configuration box, choose Edit.
6. Enter the following configuration and save:
   • Identifier (Entity ID): https://buildkite.com
   • Reply URL (Assertion Consumer Service URL): the ACS URL you copied in Step 1
7. Copy the App Federation Metadata Url value from the SAML Signing Certificate box for use in Step 3.

Step 3. Update your Buildkite SSO provider

On your Buildkite organization Settings' Single Sign On page, select the custom SAML provider from the list of Configured SSO Providers.

1. Click the Edit Provider button, choose the Configure Using IdP Meta Data URL option, and enter the App Federation Metadata Url you copied in Step 2.
2. Save your new settings. Buildkite returns you to your custom SAML provider page.

Step 4. Perform a test login

On your Custom SAML provider page, click Perform Test Login to verify that SSO is working correctly before you activate it for your organization members.

If you receive an error from Microsoft about the user not being assigned to the application, you can assign an initial user:

1. In your Azure Admin Console, select the new Buildkite enterprise app.
2. Choose Users and groups from the navigation sidebar.
3. Click Add user/group.
4. Select the user and click Assign.

Then, on your Buildkite organization Settings' Single Sign On page, select the custom SAML provider from the list of Configured SSO Providers, and retry the test login.

Step 5. Enable the new SSO provider

Once you've performed a test login you can enable your SSO provider using the Enable button. Enabling the SSO provider will not force a log out of any signed in users, but will cause all new or expired sessions to authorize through Azure AD before accessing any organization data.

Using SCIM to provision and manage users

Enterprise customers can automatically add and remove user accounts from their Buildkite organization using the SCIM provisioning settings in Azure AD.

Supported SCIM features

• Create users
• Deactivate users (deprovisioning)

Configuration instructions

Adding and removing users accounts in Azure AD is called provisioning. You need an enabled Azure AD SSO Provider for your Buildkite Organization before you can set up SCIM provisioning.

After enabling your Azure AD SSO provider in Buildkite, get the Base URL and API Token from your Azure AD SSO provider settings:

Then go to your Azure Admin Console and select the new Buildkite enterprise app to set up provisioning:

1. Choose Provisioning from the navigation sidebar, then click Get started.
2. Select Automatic provisioning mode and enter the following details:
   • Tenant URL: the Base URL from your Buildkite SSO Provider settings
   • Secret Token: the API Token from your Buildkite SSO Provider settings
3. Click Test Connection, and when you receive confirmation the settings are valid, save.
4. Disable group synchronization:
   1. Expand Mappings, then click Provision Azure Active Directory Groups.
   2. Toggle Enabled to No and click Save.
5. Customize the User mappings:
   1. Expand Mappings, then click Provision Azure Active Directory Users.
   2. Keep the following four mappings, and delete any others:
      • userPrincipalName to userName
      • Switch([IsSoftDeleted], , "False", "True", "True", "False") to active
      • givenName to name.givenName
      • surname to name.familyName
6. Toggle Provisioning Status to On and save.
7. Return to the Provisioning menu of your Azure AD enterprise app and view the Current cycle status section:
   • If provisioning is working, this will say Initial cycle completed.
   • If errors are displayed, click View provisioning logs for more details on what went wrong.

SAML user attributes

Buildkite accepts a subset of the SAML attributes from identity providers. The accepted attributes are:

When using the teams attribute, you can also specify roles. The maintainer or member role can be appended to the team UUID.

For example, the following code will specify the member role for the first team and the maintainer role for the second team:

teams="b5bbbbbb-3aaa-dd1d-aaa1-eee4eee6eeee/member, a1aaaa1a-b2bb-cccc-d4dd-aa2aaa6aaaaa/maintainer"