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 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:
Go to your Buildkite application in Okta to set up deprovisioning:
- 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.
- On the Provisioning tab, select Integration from the left side menu.
- Click Configure API Integration.
- Select the Enable API integration option and enter the URL and API token copied from your Buildkite SSO Provider settings.
- Click Test API Credentials and then Save once successfully verified.
- Select To App from the left side menu.
- Edit the Provisioning to App settings, and enable Create Users and Deactivate Users.
- 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:
- Removing and re-assigning the users and groups to the Okta Buildkite app, or
- 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"