Single sign-on with a SAML provider

You can use any identify provider that supports SAML 2.0 to authorize access to your Buildkite organization. If there isn't a Buildkite guide for your chosen provider, you can set up SAML using the instructions below.

SAML customization is available to customers on the Buildkite Enterprise plan.

There are two workflows for setting up a new SAML provider, depending on your IdP's setup process: if you require an ACS URL from Buildkite to complete your IdP's setup, or if you can complete the setup without anything from Buildkite.

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

Set up with an ACS URL

If your IdP requires information from Buildkite as part of the setup process, generate your unique Buildkite URLs first and enter the rest of your IdP information later.

Get your ACS URL and configure your IdP

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

Screenshot of the Buildkite SSO Settings Page

Choose the Provide IdP Metadata Later option when configuring your Custom SAML Provider. On the following screen you'll find the ACS URL in the Service Provider section:

Screenshot of the Service Provider section in the Custom SAML SSO Provider details page

If you IdP supports meta-data URL setup, you can find your unique Buildkite organization meta-data URL below the ACS URL.

Update your Buildkite SAML provider

In your Buildkite Single Sign On menu, select your custom SAML provider from the list of Configured SSO Providers.

Click the Edit Settings button, and choose an option for entering your IdP's information: a meta-data URL from your IdP, an XML file from your IdP, or by entering the data manually.

Manual data entry requires the following three fields:

SAML 2.0 Endpoint (HTTP) The SAML endpoint for your chosen provider.
Issuer URL The identifying URL of your chosen provider.
X.509 certificate The public key certificate for your chosen provider.
Screenshot of the Buildkite Custom SAML Settings Page

After completing your chosen option, Perform a test login, then Enable the new SSO provider.

Set up manually

There are two ways to set up your custom provider: using your Buildkite meta-data XML URL, or manually adding your Buildkite data into your identity provider.

Set up your IdP

Manual setup is different for each provider, however it usually requires the following fields:

Single sign-on URL Your unique SSO service URL from Buildkite that will be sending requests to your identity provider.
Entity Identifier https://buildkite.com
Name ID The field used to identify users. Email Address.

If your IdP requires an ACS URL before it will provide the above information, follow the instructions in the Set up with an ACS URL section to generate one.

If your custom provider needs further information, please email support@buildkite.com.

Create a Buildkite SAML provider

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

Screenshot of the Buildkite SSO Settings Page

Choose an option for entering your IdP's information: a meta-data URL from your IdP, an XML file from your IdP, or by entering the data manually.

Manual data entry requires the following three fields:

SAML 2.0 Endpoint (HTTP) The SAML endpoint for your chosen provider.
Issuer URL The identifying URL of your chosen provider.
X.509 certificate The public key certificate for your chosen provider.
Screenshot of the Buildkite Custom SAML Settings Page

After completing your chosen option, Perform a test login, then Enable the new SSO provider.

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.

Enable the new SSO provider

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

If you need to edit or update your 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.

SAML user attributes

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

Attribute Description
admin A boolean value that describes whether the user should be provisioned with admin permissions
Example: true
email A string of the user's email address
Example: "person@company.com"
name A string of the user's full name
Example: "Han Solo"
teams A comma separated list of team UUIDs. A team's UUID can be found on the Team Settings page in Buildkite.
Example: a1aaaa1a-b2bb-cccc-d4dd-aa2aaa6aaaaa,b5bbbbbb-3aaa-dd1d-aaa1-eee4eee6eeee

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"