Setting up Okta SSO for Bitrise

This guide provides step-by-step instructions on setting up Bitrise as a SAML application on Okta.

SAML SSO restrictions

SAML SSO is only available for a Workspace with the Velocity or Enterprise Build plans.

Since the SAML SSO feature is tied to the above plans, if you decide to downgrade, you will lose this feature. All Workspace members will receive an email about the downgrade and you’ll have two weeks to re-upgrade if you wish to use SAML SSO in your Workspace again.

Before connecting SAML SSO to your Workspace:

  • Make sure you have an Okta administrator who is logged into Okta at hand.

  • Be aware that only the Workspace owner can set up SAML SSO to a Bitrise Workspace.

  • Your account on Bitrise has a Workspace with the Velocity or Enterprise plan.

Adding Bitrise to Okta

Bitrise is not an integrated app in Okta. You have to add Bitrise manually to Okta first, then you can configure SAML SSO on it.

We will be jumping back and forth from the Bitrise Workspace account to Okta so make sure both pages are available. In practice this means the Workspace owner should be logged into Bitrise and the Okta admin should be logged into Okta.

  1. Log into Okta and click Admin.

    add-apps-okta.jpg
  2. On your Dashboard click Add Applications under Shortcuts.

    okta-shortcuts.jpg
  3. Click the green Create New App button.

    okta-create-new-app.jpg

    The Create a New Application Integration screen is displayed.

  4. Select SAML 2.0 option at Sing on method and click Create.

    okta-create-new-app-pop-up.jpg
  5. At General Settings step, type Bitrise into the App name field. (Optionally, you can add an app logo if you wish.) Click Next.

    okta-general-settings.jpg
  6. Head over to your Bitrise Workspace and click the Single Sign On tab on the left menu.

  7. Click the Copy Link button to copy the Assertion Consumer Service URL (ACS URL).

  8. Head back to Okta’s SAML Settings and paste the copied URL from Step 7. to the Single sign on URL input field.

  9. Type Bitrise at the Audience URI (SP Entity ID).

    You can download the Okta certificate file now, and paste its content or upload the file itself in the SAML SSO provider certificate field on your Bitrise Workspace’s Single Sign-On page. Even easier if you leave it for later as you will need to fill out the Assertion Consumer Service URL (ACS URL) on Bitrise anyway. You will fetch this while configuring Bitrise as a SAML app on Okta. Do not hit Configure SSO on the Single Sing-On page of Bitrise just yet.saml-settings-okta-2.jpg

  10. Click Next.

  11. Fill out the Feedback section. Hit Finish.

Congrats! Bitrise has been successfully added to Okta as an app.

Configuring Bitrise as a SAML app for Okta

  1. Click the Assignments tab of your Bitrise app.

    Here you can assign Bitrise to individuals/groups. Make sure you assign Bitrise to all Workspace members who will access the Bitrise Workspace through SAML.okta-assign-user.jpg

  2. Click the Sign-On tab of your Bitrise app. You will see that SAML setup is not completed yet. Click View Setup Instructions.

    view-setup-instructions.jpg

    The How to Configure SAML 2.0 for Bitrise application page is displayed. It summarizes all the information you need to set up the SAML connection between Bitrise and Okta.

    configure-bitrise-okta-1.jpg
  3. Copy the Identity Provider Single Sign-On URL and paste it in your Bitrise Workspace’s SAML SSO provider Single Sign-On URL (SSO URL).

    If you haven’t pasted the Certificate’s content or uploaded the file itself into the SAML SSO provider certificate field of your Bitrise Workspace yet, you can do so now as it is displayed on this page.

  4. Click Configure SSO on your Bitrise Workspace.