Single sign-on with OneLogin

You can use OneLogin as an SSO provider for your Buildkite organization. To complete this tutorial, you need admin privileges for both OneLogin and Buildkite.

Step 1. Add the Buildkite app to your OneLogin account

Log into your OneLogin account, and follow these steps:

  1. In the Apps tab of your OneLogin organization's Admin area, select the Add App button to search the OneLogin directory.
  2. Search for 'Buildkite'.
  3. Add the Buildkite app to your OneLogin account.
  4. Click on the Configuration tab of your new Buildkite application.
  5. Enter your Buildkite organization slug.
  6. Click the Save button in the top right to save your configuration.

Step 2. Create an SSO provider

In your Buildkite organization Settings' Single Sign On menu item, choose the OneLogin provider:

Screenshot of the Buildkite SSO Settings Page

On the following screen in the setup form, enter your IdP data. The following three required fields can be found in the SSO tab on the Buildkite app page in OneLogin:

SAML 2.0 Endpoint (HTTP) The URL where you can log in to OneLogin's SAML service.
Issuer URL The URL that identifies your OneLogin service.
X.509 certificate The public key certificate generated for you by OneLogin. You need the whole file, not just a link to the file.

You can also set up SSO providers manually with GraphQL.

See the SSO setup with GraphQL guide for detailed instructions and code samples.

Step 3. Perform a test login

Follow the instructions on the provider page to perform a test login. Performing a test login verifies 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 OneLogin before organization data can be accessed.

If you need to edit or update your OneLogin 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:

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"