Skip to main content

SAML SSO in Bitrise

Abstract

Velocity and Enterprise users can create and log in to a Bitrise Workspace using their own SAML SSO provider’s system to provide an extra layer of security.

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.

Before connecting SAML SSO to your Workspace, make sure:

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

  • Your account on Bitrise has a Velocity or an Enterprise Build Platform plan. If it doesn’t have a Workspace, go ahead and create one. Setting up SAML SSO is the same for existing and brand new Workspaces on Bitrise.

  • Only the Workspace owner can set up SAML SSO to a Bitrise Workspace.

Navigating to the Single Sign-On page of Bitrise

If you are a Workspace owner on Bitrise, you will have to use the Single Sign-On tab to set up a SAML SSO connection between your SAML SSO provider and your Bitrise Workspace.

  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 menu bar, click Single Sign-On which will take you to the Single Sign-On page.

    enablesinglesignon.jpg

  5. Continue with setting up SAML SSO for your Workspace on Bitrise.

Authorizing SAML SSO

Once the Workspace owner has set up SAML SSO, everyone in the Workspace has to authorize SAML SSO before logging in to their Workspace via SAML SSO.

  1. Make sure you’re logged into Bitrise in the usual way. Use the same browser window to continue.

  2. Bitrise sends a verification e-mail to all Workspace members. By clicking the Log In via SAML SSO button or using the provided URL, Workspace members can authorize themselves for SAML SSO login. The email also shows the Workspace owner’s email address (should you need to contact them.) Click the Log In via SAML SSO button or copy-paste the URL to a NEW TAB of the same browser.

  3. You’re directed to Bitrise to Allow “Workspace name” to sign you in page.

    • Click Authorize if you trust the Workspace to control your Bitrise account sign-in process.

      If you’re already logged in to your SAML SSO provider, you’ll be automatically taken to your Bitrise Dashboard.

      If you’re not, you’ll be prompted to log in on your SAML SSO provider’s site, and then taken to your Bitrise Dashboard.

    • Click Don’t Allow if the invitation email is from an untrusted source.

      SAML SSO in Workspaces

      Note that if you are using a different non-matching email address, you will get the below error message. Make sure you log in with the right email address both on Bitrise, as well as on your SSO provider site.noconnectedsamlsso.png

If all went well, you should be landing on our Bitrise Dashboard.

Joining a SAML SSO Workspace as a new member

If a Bitrise Workspace owner invites you to a Workspace, you should get an email invitation to join the Workspace via SAML SSO. Let’s see how!

  1. Go to your mailbox and find our email titled Saml invitation instructions.

  2. Click the Sign in via SSO button or copy the provided URL and paste it into a new browser. Our Almost there page appears.

  3. Provide a Username you would like to use in your Bitrise Workspace. Please use only letters, numbers, underscores (_), dashes (-) and dots (.) in your username. The Email field is non-editable.

  4. Click the Finish Sign-up button. If all went well, you’re landing on Bitrise and can add your first app.

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.

Adding a new user to a Workspace with enforced SAML SSO

Once SAML SSO is enforced on a Workspace, you can still add new users to it. But in this case, it's important to differentiate between the two types of new users:

  • Users with existing accounts on Bitrise: We recommend that the Workspace admin turns off the enforced SSO and invites the user to the Workspace. The invited Bitrise user has to go through the invitation process and enable their SSO connection. Once that is done, the Workspace admin can turn the Enforce SSO switch back on.

  • Users who are new to Bitrise and haven't registered an account yet: The Workspace admin doesn't need to turn off enforced SSO: simply invite the new user who should then complete the sign-up procedure as described: Joining a SAML SSO Workspace as a new member.

    Alternatively, the new user can go directly to the sign-up page, and click the SAML button then follow the instructions to achieve the same goal.

Logging in via SAML SSO

If the SAML SSO connection has been already added to your Workspace and you have enabled your SAML SSO connection too, you can easily log in to your Bitrise account without having to use a password and email address.

Expired SAML SSO certificate

If your SAML SSO certificate has expired, and you cannot log into Bitrise through SAML SSO, you can contact our Support team to help you log in.

  1. Click Login via SSO on our login page.

    SAML SSO in Workspaces

  2. You will be redirected to the Initiate Single Sign-On page.

  3. Provide your Workspace name in the Bitrise Workspace’s Name field.

  4. Click Continue with SSO to log in.

    • If you’re logged in on your SSO provider site, you will be automatically landing on your Bitrise Dashboard.

    • If you’re logged out on your SSO provider site, you will be redirected there to log in. After the successful login, you will be redirected to your Bitrise dashboard.

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 Sing-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: