Single Sign-On with Google Workspace (SAML)

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

To complete this tutorial, you will 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 will be able to 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, 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. Attribute mapping can be added 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'll need the whole file, not just a link to the file.

Save your new settings, and you'll be returned to your provider page.

Step 3. Perform a Test Login

Follow the instructions on the provider page to perform a test login. Performing a test login will verify 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 4. 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.