Single Sign-On with Okta

Okta can be used as an SSO provider for your Buildkite organization. To complete this tutorial, you will need admin privileges for both Okta and Buildkite.

Step 1. Add the Buildkite App to your Okta Account

Log into your Okta account, and follow these steps:

  1. Click the Admin button in Okta to access your Admin dashboard
  2. In the Shortcuts menu, click 'Add Applications' to search the Okta application directory
  3. Search for 'Buildkite'
  4. Click 'Add' to add the Buildkite app to your Okta account
  5. Give your application a name in the 'General Settings' form
  6. In the Buildkite application in Okta, select the tab labelled 'Sign On'
  7. In the Sign On section 'Settings', click the 'Identity Provider Metadata' link and copy the URL for use in the next step
  8. Select the tab labelled 'Applications'
  9. Assign your user account or group to the application so that you will be able to complete a test login

Step 2. Create an SSO Provider

In your Buildkite Organization Settings' Single Sign On menu item, choose the Okta provider:

Screenshot of the Buildkite SSO Settings Page

On the following screen in the Metadata URL field, enter the 'Identity Provider Metadata' link that you copied in the previous step.

Screenshot of the Buildkite Okta Settings Page

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 to perform a test login. Performing a test login will verify 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 Okta before organization data can be accessed.

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