Skip to main content

Configuring SAML SSO on Bitrise

Abstract

Workspace members can log in to a Bitrise workspace using their own SAML SSO provider’s system. With SAML SSO, workspaces will be able to apply the security guidelines of their SAML SSO provider when accessing their Bitrise workspace.

Workspace members can log in to a Bitrise workspace using their own SAML SSO provider’s system. With SAML SSO, workspaces will be able to apply the security guidelines of their SAML SSO provider when accessing their Bitrise workspace.

SAML SSO can also be enforced on a workspace: enforcing makes SAML SSO the only for logging in to the workspace.

Verifying your domain

You can add and verify your corporate domains from where you will manage Bitrise users. You can have multiple verified domains on Bitrise but you can only add one domain at a time. Multiple subdomains of the same domain count as different domains as Bitrise expects an exact match.

Verifying your domain is a requirement for configuring SCIM and it makes it much more convenient for users to sign up and log in to Bitrise via SAML SSO. We recommend starting your SAML SSO setup with verifying your domain as the process can take some time.

  1. Log in to Bitrise and hover over the left navigation bar.

  2. Make sure you have the right workspace selected in the Workspace menu.

  3. Select Settings.

    workspace-settings-new.png

  4. On the left, select Single sign-on.

  5. Select the Domains tab.

  6. In the Domain control section, click Add domain.

  7. Enter your domain name in the dialog box, and click Next.

    Handling subdomains

    Bitrise expects an exact match for the domain names. If you use subdomains, you need to add the full name of the subdomain. For example, if you own mydomain.com and you want to use its subdomain external.mydomain.com, you should write it out the subdomain's name when setting up domain control on Bitrise.

  8. You will see a domain verification code. You need to add this code to as a DNS TXT record at your domain provider.

  9. Click Copy and close to copy the verification code and close the dialog box.

After you've added the DNS TXT record at your domain provider, we'll commence domain verification. This can take up to 72 hours. You will receive an email once it is completed.

Setting up SAML SSO for a Bitrise workspace

In this tutorial, we describe how workspace owners can set up their SAML SSO and invite workspace members to set up their own connections.

Before connecting SAML SSO to your workspace, you need:

  • A SAML SSO provider (Identity Provider) that you can connect Bitrise to and the administrator to the SAML SSO provider is at hand.

  • An owner or manager of the workspace. Workspace members with the role of contributor or viewer can't set up SAML SSO.

To start configuring SAML SSO:

  1. Log in to Bitrise and hover over the left navigation bar.

  2. Make sure you have the right workspace selected in the Workspace menu.

  3. Select Settings.

    workspace-settings-new.png

  4. Select the Single Sign-On tab on the left.

  5. Click Configure SAML SSO. It opens the Setup connection screen.

  6. Log in to your SAML SSO provider and add Bitrise as a SAML SSO application, using the values from the Setup connection screen in your Bitrise workspace settings:

    sso-setup.png

    • Copy the Assertion Consumer Service URL (ACS URL) by clicking Copy. The provider sends the SAML response to the ACS URL. Some providers call it Reply URL, Callback URL, or Single Sign-On URL.

    • Copy the Single Logout URL by clicking Copy. The provider sends the SAML logout response to the Single Logout URL.

    You will receive configuration values from your SAML SSO provider.

  7. Add your SAML SSO provider configuration values:

    • SSO URL: Bitrise sends the SAML request to the SSO URL. Some providers call it Login URL.

    • SSO Logout URL (optional): Bitrise sends the SAML logout request to the SSO Logout URL.

    • Application Identifier (optional): This is necessary if multiple workspaces use the same identity provider. This may be called Entity ID, Audience URI, or something similar.

  8. Upload the SAML SSO provider certificate.

    You can either upload the file or paste the certificate manually.

    sso-certificate.png

  9. Click Save changes.

If you’ve completed the steps, you and workspace members should get a verification email about SAML SSO connected to the respective workspace.

Checking SAML SSO statuses on Bitrise

Now that the Workspace owner has set up SAML SSO for the Workspace, all Workspace members (including the Workspace owner) can check their other Workspace member’s SAML SSO statuses on the Team tab.

Accessing the Single Sign-on tab

The Single Sign-On tab is only available for the Workspace owner.

There are two kinds of SAML SSO statuses on Bitrise.

  • SAML IS ENABLED: Login via SAML SSO is enabled.

  • SAML IS DISABLED: The Workspace member has not enabled the SAML SSO connection yet. To enable it, the Workspace member has to follow the instructions in the verification email from Bitrise.

  1. Go to your Workspace’s profile page.

  2. Select Team from the left menu.

  3. Go to the Members tab to check the Workspace member’s SAML status.

    saml_status.png

Enforcing SAML SSO on a Workspace

Enforcing SAML SSO on your Workspace provides an extra layer of security: you can enforce your own security guidelines to your Bitrise Workspace (for example, password format requirements, two-factor authentication).

Enforced SAML SSO

Enforcing SAML SSO in your Workspace makes SAML SSO the only way for logging in/signing up to the Workspace.

One Workspace only

You cannot be a member in two Workspaces that enforced SAML SSO on Bitrise.

  1. Log in to Bitrise and hover over the left navigation bar.

  2. Make sure you have the right workspace selected in the Workspace menu.

  3. Select Settings.

    workspace-settings-new.png

  4. Go to your Workspace’s Single Sign On tab.

  5. Check the Enforce SAML SSO checkbox to enforce SAML SSO.

    enforce_saml.png

    Unable to enforce SAML SSO

    A Workspace owner cannot enforce SAML SSO on the Workspace if Workspace members have not enabled their SAML SSO connection yet or they enabled SAML SSO with another Workspace that enforces SAML SSO.

  6. Click Save changes.

Now Workspace members can only log in via SAML SSO.

Disabling a Workspace's SAML SSO

If you disable SAML SSO, Workspace members will be able to sign in with the regular sign-in procedure.

  1. Log in to Bitrise and hover over the left navigation bar.

  2. Make sure you have the right workspace selected in the Workspace menu.

  3. Select Settings.

    workspace-settings-new.png

  4. Go to the Single Sign-On tab.

  5. If SAML SSO has been enforced on the Workspace before, toggle Enforce under Enforce SAML SSO off.

  6. Click Disable SSO.

    A confirmation pop-up appears where you can confirm/cancel your action. Please note that by clicking the Disable SSO button, you will disable SAML SSO for all Workspace members. Once it’s done, Workspace members will be able to log in through their normal Bitrise credentials.

    disable_sso.png

You will receive an SSO has been disabled email from Bitrise ([email protected]) which confirms the disabled SAML SSO for the Workspace.

Disabling a Workspace member's SAML SSO

If you are a Workspace owner, you can disable a Workspace member’s SAML SSO connection to the Workspace on Bitrise. There are two ways to do so:

  • Remove the user from the Workspace.

  • Remove the user from the SAML SSO provider which means the user would not be able to log in with SAML SSO any more.

Updating SAML SSO configuration

You can update a Workspace’s configured SAML SSO using the Configure SAML SSO provider button on the Single Sign-On page.

This comes in handy if your SAML SSO provider’s certificate has expired and you wish to insert the new certificate on Bitrise. Another use case is, for example, if SAML SSO has been configured a while ago and now you wish to check the current configuration details.

Accessing the Update SSO button

As with other SAML SSO configurations, only the Workspace owner can access and use the Update SSO button.

  1. As the owner of the Workspace, click your Workspace’s Single Sign-On tab.

  2. Click the Configure SAML SSO provider button. Now you can access the configuration details of Workspace’s SAML SSO.

    configure_update_sso.png

  3. Make the changes and click Save changes.

    From now on any SAML SSO request will use the new configuration automatically.

In this section:

A Workspace is an environment that allows you to manage your Bitrise apps and the team members working on the apps. You can create multiple Workspaces, and you can be invited to Workspaces by other Bitrise users. To be able to add apps and run builds, you either need to be part of a Workspace, or you have to be an outside contributor on an app's team.