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 set up your SSO provider in your Buildkite organization's Single Sign On Settings.
Manual 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 email@example.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 firstname.lastname@example.org 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.|
|Name ID||The field used to identify users. Email Address.|
If your custom provider needs further information, please email email@example.com.
Step 2. Create an SSO Provider in Buildkite
In your Buildkite Organization Settings' Single Sign On menu item, choose the Custom SAML provider:
On the following screen you can choose to either set up using a Meta Data URL from your IdP or by entering the following 3 fields:
|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.|
Step 3. Perform a Test Login
Follow the instructions 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 4. 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:
||A boolean value that describes whether the user should be provisioned with admin permissions Example: true|
||A string of the user's email address Example: "firstname.lastname@example.org"|
||A string of the user's full name Example: "Han Solo"|
||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
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: