SAML with a Custom Provider

Any identify provider that supports SAML 2.0 can be used 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.

Set up your provider

There are two ways to set up your custom provider: using the Buildkite meta-data XML to your identity provider, or manually adding your Buildkite data into your identity provider. After setting up your provider, you'll need to send the Buildkite team your application information.

Self-service SSO provisioning in Buildkite is available via our GraphQL explorer. For further information, see the GraphQL SSO Setup Guide.

Before starting your provider setup

Email the Buildkite team at support@buildkite.com to request your unique SSO service URL, you will need this during set up.

Step 1. Option A - Setting up with meta-data

A custom URL containing your organization's metadata can be generated. You can request the URL from support@buildkite.com alongside your SSO service URL. The custom endpoint contains all the information you need to set up SAML with any provider.

Step 1. Option B - Setting up manually

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 custom provider needs further information, please email support@buildkite.com.

Step 2. Send your application information to Buildkite

After completing your identity provider's setup process, email support@buildkite with the following information:

Domain name The domain you use with your SAML provider for which you want to enable SSO. This must match one of the emails you have verified with your Buildkite account.
Organization slug The Buildkite organization for which you want to enable SSO.
SAML 2.0 Endpoint (HTTP) The SAML endpoint for your chosen provider.
Issuer URL The identifing URL of your chosen provider.
X.509 certificate The public key certificate for your chosen provider.

When we receive your email, Buildkite support will set up SSO in test mode and reply with instructions for performing a test login.

Step 3. Perform a Test Login

Follow the instructions sent by Buildkite support to perform a test login. Performing a test login will verify that SSO is working correctly, before it is activated for all your organization members.

Step 4. Buildkite Support will Activate SSO

Once you've performed a test login, reply to the previous email and Buildkite support will activate SSO for your entire Buildkite organization. Activating SSO will log out all of your organization’s members, to ensure that all data access is authorized through your chosen provider.

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"