Single sign-on support

You can use a single sign-on (SSO) provider to protect access to your organization's data in Buildkite. Buildkite supports many different SSO providers, and you can configure multiple SSO providers for a single Buildkite organization.

SSO is available to customers on the Buildkite Team, Business, and Enterprise plans.

Supported providers

Buildkite supports the following SSO providers:

Adding SSO

Many of the SSO providers can be configured by an organization admin using Organisation Settings → SSO Settings:

Screenshot of the Buildkite SSO Settings Page

You can also configure SSO manually using the GraphQL API.

Once configured, all access to organization data requires signing into your SSO provider:

Screenshot of the SSO protecting access to data

Disabling and removing SSO

If you need to edit your SSO settings, temporarily stop logins using SSO, or want to delete your SSO provider, you'll first need to disable it.

There are two ways to disable a provider:

  1. Using the 'Disable' button in your SSO provider Settings, or
  2. Using the GraphQL API

If you have switched off all of your SSO providers, users will be required to log in using a username and password. If users don't have a password, and need access while SSO is switched off, they can perform a 'Forgotten Password' reset.

Migrating from one SSO provider to another SSO provider

If you are the administrator of an organization within Buildkite with an existing SSO provider set up, and you want to switch to a different SSO provider, these are the steps you need to take:

  1. Add a new SSO provider, verify it, and allow login from both SSO providers. The users in your organization can continue to sign in and use the same user accounts within Buildkite as long as the emails stay the same.
  2. Disable and remove the SSO provider you no longer need. If the user credentials (email) stay the same, this is all you need to migrate from one SSO provider to another.

📘

If you are also changing the email provider, make sure that Buildkite users in your organization sign in to their existing accounts when performing single sign-on through the new provider to prevent your organization being billed twice for the same users.

If you'd like to have some help with the migration, contact support@buildkite.com.

SSO session duration

You can configure the SSO Session Duration to timeout after a predetermined time. When the specified duration elapses, the user will be signed out of the session.

To set the Session Duration you can either use the GraphQL API or complete the following steps via the settings interface.

First select the SSO Provider you would like to configure.

Screenshot of the Buildkite SSO Settings Page

Then click Update Session Duration from the Session Duration section of the SSO Provider settings page.

Screenshot of the Buildkite SSO Settings Page

You can configure the session duration to any timeout between 6 hours and 8,760 hours (1 year).

Screenshot of the Buildkite SSO Session Duration Configuration

Frequently asked questions

Can some people in the organization use SSO and others not?

Yes, team maintainers can select whether a user is 'required' to use SSO or whether it is 'optional'. You can find this setting in the organization's user settings.

Do you support JIT provisioning?

Yes, we do.

What happens if a person leaves our company?

You will need to manually remove them from your Buildkite organization. This will not affect access to the user's personal account or any other organizations they are a member of.

Can I use different SSO providers for my Buildkite organization at the same time?

Yes, as an admin you need to add and verify a new SSO provider. Next, you need to allow login from both SSO providers in the Organization settings. As long as the sign-in emails stay the same, the users in your organization can continue to sign in and use the same user accounts within Buildkite.

Can we enable SSO on multiple domains for one organization?

Yes, by adding multiple SSO providers. You can enable as many different identity providers for your organization as you need.

Will enabling SSO disrupt my team?

No, SSO must be verified before being enabled, and can easily be switched off if required. Once enabled, users will see a new "SSO" badge on the organization and will be required to authorise with your SSO provider to access organization data.

Will enabling SSO affect builds, agents or pipelines?

No, all of your builds, agents, and pipelines will continue to run as normal.

Does enabling SSO affect billing?

No, enabling SSO will not affect how much you are billed. However, whenever a new user signs in to Buildkite using SSO, they will be added to your organization as if you had invited them.

Can I sync my identity provider's groups with my Buildkite teams?

Yes, if you are able to associate your provider's groups with your Buildkite team UUIDs, you can adjust the SAML assertion to send 'teams' as an additional SAML User Attribute.

I want to rename my Buildkite organization. Will it affect my SSO provider(s)?

No, SSO providers are setup using a unique identifier and are unaffected when a Buildkite organization is renamed.

Can I merge two organizations that use different SSO providers?

In short, yes, you can. However, merging Buildkite organizations that already have SSO providers might be a tricky scenario, and it's highly recommended that you contact support@buildkite.com for help or guidance before you attempt such migration.

Why am I being asked for my password in the "Authorization Required" screen when signing in using SSO?

Signing in to your Buildkite organization requires authentication and authorization with both Buildkite and your SSO provider. Authentication determines if you are who you claim to be. Authorization determines if you have the correct permissions within the Buildkite organization you're trying to access.

Both authentication and authorization are necessary because SSO using one Buildkite organization shouldn't provide access to your other Buildkite organizations. Confirming your password is Buildkite's way to ensure that you are who you say you are. Once you've authenticated with Buildkite, it determines which organizations your account is authorized to access.

I'm already a member of a Buildkite organization. Should I create a new Buildkite user account if I want to work within a different organization (pet project, open source work, etc.)?

Some people choose to have multiple user accounts, one per Buildkite organization. It's fine to do this, but it can be slightly inconvenient as such an approach does not provide easy tools for switching between accounts. You will need to use different browsers or log in and out quite often.

It's recommended to have a single Buildkite user account and join multiple organizations when required.