Single sign-on with Okta

To add Okta as an SSO provider for your Buildkite organization, you need admin privileges for both Okta and Buildkite.

Setting up SSO with SAML

To set up single sign-on, follow the SAML configuration guide.

Using SCIM to provision and manage users

Customers on the Buildkite Enterprise plan can optionally enable automatic deprovisioning for their Buildkite users.

Supported SCIM features

  • Create users
  • Deactivate users (deprovisioning)

Buildkite does not bill you for users that you add to your Okta Buildkite app until they sign in to your Buildkite organization.

Configuration instructions

Using the SCIM provisioning settings in Okta, Buildkite customers on the Enterprise plan can automatically remove user accounts from your Buildkite organization. In Okta this feature is called 'Deactivating' a user. You need an enabled Okta SSO Provider before you can set up SCIM.

User deprovisioning

User deprovisioning is an Enterprise only feature and automatically enabled. If you are using a custom provider as an Enterprise customer, please contact support@buildkite.com to have the 'SCIM for Custom SAML' feature flag enabled.

After creating your SSO Provider in Buildkite, you will need the Base URL and API Token from your Okta SSO Provider Settings:

Screenshot of the Buildkite Okta Settings SCIM Deprovisioning section

Go to your Buildkite application in Okta to set up deprovisioning:

  1. On the Sign On tab in the Okta Buildkite application, edit the Credentials Details settings, select Email for the Application username format and click Save.
  2. On the Provisioning tab, select Integration from the left side menu.
  3. Click Configure API Integration.
  4. Select the Enable API integration option and enter the URL and API token copied from your Buildkite SSO Provider settings.
  5. Click Test API Credentials and then Save once successfully verified.
  6. Select To App from the left side menu.
  7. Edit the Provisioning to App settings, and enable Create Users and Deactivate Users.
  8. Save and test your settings.

Provisioning existing users

Buildkite creates accounts for existing Okta users with just-in-time user provisioning (JIT provisioning). To deprovision users, you need to sync them.

This can be done one of two ways:

  1. Removing and re-assigning the users and groups to the Okta Buildkite app, or
  2. If your Okta tenant has Lifecycle Management enabled, then you can use the Provision User function on the Assignments tab of the Okta Buildkite app.

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"