Setting up single sign-on with GraphQL

Buildkite's single sign-on (SSO) can be set up by emailing support, or you can set it up manually using our GraphQL APIs. This tutorial covers how to set up SSO manually using GraphQL.

For details on every available option available in the GraphQL APIs, please use the documentation sidebar built into the GraphQL explorer.

Finding your organization's GraphQL ID

For every type of SSO provider, you need your Buildkite organization's GraphQL ID. You can find your organization's GraphQL ID using the following GraphQL query:

query OrganizationId {
  organization(slug: "myorg") {
    id
  }
}

Setting up G Suite

Step 1

The first step in setting up a G Suite SSO provider is to use the ssoProviderCreate mutation to create a new provider in your Buildkite organization:

mutation CreateProvider {
  ssoProviderCreate(input: {
    organizationId: "<organization id>",
    type: GOOGLE_GSUITE,
    googleHostedDomain: "myorg.com",
    discloseGoogleHostedDomain: true,
    emailDomain: "myorg.com",
    emailDomainVerificationAddress: "admin@myorg.com"
  }) {
    ssoProvider {
      id
      state
      url
    }
  }
}

You need the provider's id from the output of this mutation in step three.

Step 2

The second step is to use the url that was returned above to perform a test login. Open the url in a browser, and perform a test login using G Suite.

Once you complete the test login, you can do the final step: enabling the provider using the ssoProviderEnable mutation. Running this mutation will require all your users to authorize using your G Suite provider before they can access your organization on Buildkite.

mutation EnableProvider {
  ssoProviderEnable(
    input: {
      id: "<provider id>"
    }
  ) {
    ssoProvider {
      state
      url
    }
  }
}

You should now see that the provider's state is enabled.

See the SSOProviderUpdatePayload documentation for other properties that can be configured on your SSO provider, such as sessionDurationInHours and note.

Setting up SAML (Google Cloud Identity, Okta, OneLogin, ADFS and others)

Step 1

The first step in setting up a SAML-based provider is to use the ssoProviderCreate mutation to create a new provider in Buildkite. This mutation returns the details you'll need for your SSO provider's system.

The emailDomainVerificationAddress requires the same domain as emailDomain, and must be one of admin@, administrator@, postmaster@, or webmaster@.

mutation CreateProvider {
  ssoProviderCreate(input: {
    organizationId: "<organization id>",
    type: SAML,
    emailDomain: "myorg.com",
    emailDomainVerificationAddress: "admin@myorg.com"
  }) {
    ssoProvider {
      id
      state
      ... on SSOProviderSAML {
        serviceProvider {
          metadata {
            url
          }
          ssoURL
          issuer
        }
      }
    }
  }
}

You need the provider's id from the output of this mutation in steps three and four.

Step 2

The next step is to log into your SSO provider's system and set up Buildkite using the details from the GraphQL response above.

If the SSO provider supports a metadata URL, you can use the url property of the metadata object. If your SSO provider does not support metadata URL, use the ssoURL property for the ACS URL or SSO URL, and the issuer property for the Issuer or Entity ID.

Step 3

If your provider shows a metadata URL to complete the setup, you can use that with the ssoProviderUpdate mutation to have Buildkite automatically complete the setup. This will not yet affect any of your Buildkite users.

mutation UpdateProviderMetaData {
  ssoProviderUpdate(input: {
    id: "<provider id>",
    identityProvider: {
      metadata: {
        url: "https://myssoprovider.com/metadata/..."
      }
    }
  }) {
    ssoProvider {
      state
      url
      ... on SSOProviderSAML {
        serviceProvider {
          ssoURL
          issuer
        }
      }
    }
  }
}

If your SSO provider didn't provide a metadata URL, then copy SSO URL, Issuer (also known as Entity ID), and Certificate into the ssoProviderUpdate mutation:

mutation UpdateProviderMetaData {
  ssoProviderUpdate(input: {
    id: "<provider id>",
    identityProvider: {
      ssoURL: "https://myssoprovider.com/...",
      issuer: "https://myssoprovider.com/...",
      certificate: "---BEGIN CERT---..."
    }
  }) {
    ssoProvider {
      state
      url
      ... on SSOProviderSAML {
        serviceProvider {
          ssoURL
          issuer
        }
      }
    }
  }
}

If your SSO provider requests additional info, use the ssoURL property for the ACS URL or SSO URL, and the issuer property for the Issuer or Entity ID.

Step 4

You can now perform a test login from your SSO provider's web interface, or using the url returned from the update mutation.

Once you complete the test login, you can do the final step: enabling the provider using the ssoProviderEnable mutation. Running this mutation will require all your users to authorize using your SSO provider before they can access your organization on Buildkite.

mutation EnableProvider {
  ssoProviderEnable(
    input: {
      id: "<provider id>"
    }
  ) {
    ssoProvider {
      state
    }
  }
}

You should now see that the provider's state is enabled.

See the SSOProviderUpdatePayload documentation for other properties that can be configured on your SSO provider, such as sessionDurationInHours and note.

Finding an SSO provider's details

If you need to find the ID of a particular SSO provider, you can query the ssoProviders field of your organization:

query FindProviders {
  organization(slug: "<organization id>") {
    ssoProviders(first: 100) {
      edges {
        node {
          id
          type
          state
          createdAt
          enabledAt
          url
          emailDomain
          emailDomainVerificationAddress
          emailDomainVerifiedAt
        }
      }
    }
  }
}

Some provider types have additional fields which you can query using GraphQL's Inline Fragment syntax, for example:

query FindProviders {
  organization(slug: "<organization id>") {
    ssoProviders(first: 100) {
      edges {
        node {
          id
          url
          ... on SSOProviderSAML {
            identityProvider {
              ssoURL
              issuer
              certificate
              metadata {
                xml
                url
              }
            }
          }
          ... on SSOProviderGoogleGSuite {
            googleHostedDomain
            discloseGoogleHostedDomain
          }
        }
      }
    }
  }
}

Disabling an SSO provider

If you need to disable an SSO provider, you can do so using the ssoProviderDisable mutation.

mutation DisableProvider {
  ssoProviderDisable(input:{
    id: "<provider id>",
    disabledReason: "Disabled because..."
  }) {
    ssoProvider {
      state
      url
    }
  }
}