Single sign-on with Google Workspace (SAML)

As an alternative to Google Workspace SSO using OpenID, you can use Google Workspace as an SSO provider for your Buildkite organization using SAML.

To complete this tutorial, you need admin privileges for both Google Workspace and Buildkite.

You can also set up SSO providers manually with GraphQL.

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

After following these steps, your Google Workspace users can sign in to Buildkite using their Google account.

Step 1. Create a Buildkite SSO provider

Click the Buildkite organization Settings' Single Sign On menu item, then choose the custom SAML provider from the available options:

Screenshot of the Buildkite SSO Settings Page

Choose the Provide IdP Metadata Later option when configuring your Custom SAML provider.

On the following page, copy the ACS URL for use in Step 2.

Step 2. Add Buildkite in Google Workspace

Log into your Google Admin Console, and follow these instructions:

  1. In the Apps area of the console, select the Web and mobile apps submenu.
  2. Click the Add App menu at the top of the table and choose Search for apps.
  3. Search for Buildkite, and select Buildkite Web (SAML).
  4. Copy the SSO URL and Entity ID, and download the Certificate. You'll need these in Step 3.
  5. Enter the following service provider details:
    • ACS URL: the URL you copied in Step 1. Replace any existing value suggested by Google.
    • Entity ID: https://buildkite.com
  6. You can add attribute mapping after the initial setup and testing. Click Finish to complete the setup.

Step 3. Update your Buildkite SSO provider

On your Buildkite organization Settings' Single Sign On page, select your Custom SAML provider from the list of Configured SSO Providers.

Click the Edit Settings button, choose the Manual data option, and enter the IdP data you saved in Step 2:

SAML 2.0 Endpoint (HTTP) The SSO URL you copied down during the previous step.
Issuer URL The Entity ID that you copied down during the previous step.
X.509 certificate The public key certificate generated for you by Google Workspace that you downloaded during the previous step. You need the whole file, not just a link to the file.

Save your settings. Your provider page opens.

Step 4. 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.

According to Google, "Changes may take up to 24 hours to propagate to all user". Some changes may take at least several hours, so if the test login fails, it is worth waiting and trying again.

Step 5. Enable the new SSO provider

Once you've performed a test login, you can enable your provider using the Enable button. Activating SSO will not force a log out of existing users, but will cause all new or expired sessions to authorize through Google Workspace before organization data can be accessed.

The users will need to sign into Buildkite by clicking the Buildkite icon in the Google Apps menu. You can find this menu by clicking the 9-dot "waffle" icon.

Buildkite in Google Apps menu

If you need to edit or update your Google Workspace (SAML) 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"