Skip to main content

Setting up Okta SSO for Bitrise

Abstract

Add SAML SSO to your Bitrise Workspace using Okta.

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.

    okta_2.png

  2. From the left menu, select Applications under the Applications section.

  3. Click on the Create App Integration button.

    app_integration_okta.png

    This opens the Create a new app integration window.

  4. Select SAML 2.0 option as the Sign-in method and click Next.

    create_new_app_integration.png

  5. At the General Settings step, type Bitrise into the App name field. (Optionally, you can add an app logo if you wish.) Click Next.

    general_settings_okta.png

  6. Head over to your Bitrise Workspace and click the Single Sign On tab on the left menu.

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

  8. Head back to Okta’s Configure SAML page 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.

  10. Set the Name ID format to EmailAddress.

    configure_sso.png

  11. Click Next.

  12. Fill out the Feedback section. Hit Finish.

  13. In Applications, go to the Sign-on tab, and click Edit next to Settings.

  14. Scroll down to the Credential Details section, and make sure that Application username format is set to Email.

    credential_details.png

  15. Click Save.

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.

    assignments_okta.png

  2. Click the Sign-On tab of your Bitrise app. You will see that SAML setup is not completed yet. Scroll down, and click View SAML setup instructions.

    saml_instructions.png

    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 SSO URL field.

    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.

    saml_sso_url.png

  4. Click Configure SSO on your Bitrise Workspace.

That's it! From now on, whenever you access the Single Sign-on page, you can configure the SAML SSO settings.

Setting up SCIM provisioning in Okta

You can set up SCIM provisioning for Bitrise using Okta.

Managing Workspace groups

While SCIM is a great way to manage the access of your users for Bitrise Workspaces, you will have to do some initial configuration for your groups in Bitrise after finishing setting up the SCIM provisioning. For more information about configuring your groups, check out Adding Workspace groups to a project team.

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 in to Okta.

  1. On Bitrise, configure domain control and generate your SCIM credentials. You need to have:

    • A verified domain.

    • An SCIM base URL and an SCIM authentication token.

    Make sure you save both of these because you will need them during the process later.

  2. Log into Okta and click Admin.

  3. From the left menu, select Applications under the Applications section.

  4. Select your Bitrise app.

  5. Click the General tab of your Bitrise app.

  6. Click Edit next to the App Settings section and select the SCIM option using the radio button next to Provisioning.

    scim_setting.png

  7. Click Save.

    A new tab called Provisioning will appear.

  8. Head back to Okta, and select the Provisioning tab, then click on Edit.

  9. Paste the SCIM base URL you copied from Bitrise in the SCIM connector base URL field.

  10. Add userName in the Unique identifier field for users field.

    scim_connection_2.png

  11. Select which provisioning actions you would like to enable using the checkboxes next to Supported provisioning actions.

    Push Groups are mandatory

    Please note that you must enable Push Groups. This is because on Bitrise, Workspace membership works via groups and Okta/SCIM can control our Workspace groups via Push Groups.

  12. Select HTTP Header from the Authorization Mode dropdown menu.

  13. Copy and paste your SCIM authentication token in the Authorization field.

  14. Click Test Connector Configuration to test if everything is working correctly.

    test_connector.png

  15. Close the Test Connector Configuration window and click Save.

  16. Click the Provisioning tab of your Bitrise app, then click on Edit next to the Provisioning to App section.

    scim_provisioning.png

  17. Select which provisioning options you would like to enable and click Save.

    Sync password

    We recommend keeping the Sync Password setting disabled.

That's it! You can now use SCIM provisioning in Okta to manage the access of your users to Bitrise.

Pushing Okta groups to Bitrise using SCIM

You can push groups from Okta to Bitrise using SCIM provisioning. Pushing a group either links an Okta group to an existing Bitrise group or creates a new group in your Bitrise Workspace.

Either way, by pushing a group, you set up synchronization between an Okta group and a Bitrise group.

  1. Log into Okta and click Admin.

  2. From the left menu, select Applications under the Applications section.

  3. Select your Bitrise app.

  4. Click the Push Groups tab.

  5. Click on Push Groups and choose a filtering method.

    push_groups.png

  6. Find the group(s) you want to push.

  7. You must either create a new group, which will create a brand new group in your Bitrise Workspace or link the Okta group to an existing Bitrise group.

    You can choose between these methods using the dropdown menu under the Match result & push action.

    Linking a group

    If you decide to link an Okta group to an existing Bitrise group, keep the following in mind:

    • If the Okta and Bitrise group names are different, the Bitrise group will be automatically renamed to match the name of the Okta group.

    • When you manually push a group connected to an existing Bitrise group, if the group had members who were only added on Bitrise and not included in the Okta group, then they will be removed as Okta becomes the single source of truth.

    linkGroup.png

  8. Click Save.

    When the Push Status changes to Active, the synchronization between Okta and Bitrise is ready. Your group should be updated in a couple of seconds on your Bitrise Workspace as well.

    push_status_active.png

Synchronizing groups and users between Okta and Bitrise

After pushing Okta groups to Bitrise, you can synchronize your groups and users between Okta and Bitrise. To do so, you must manage the app integration assignments in Okta:

  1. Log into Okta and click Admin.

  2. From the left menu, select Applications under the Applications section.

  3. Select your Bitrise app.

  4. Make sure that Create Users and Deactivate Users options are enabled on the Provisioning tab.

    provisioning_settings.png

    Deprovisioning users

    If you deprovision a user with SCIM, the user will be automatically logged off Bitrise and their PATs will be disabled.

  5. Go to the Assignments tab.

  6. Click Assign and choose Assign to People to synchronize individual users or Assign to Groups to synchronize groups.

    assign_people.png

  7. Select the users or groups that you would like to synchronize, then click Done.

    Domain verification

    New users without verified domains will receive an email invitation to join the Workspace.

    Existing users will also receive a verification email unless you verify your company domain: Configuring domain control.

  8. After synchronizing your groups and users, you can check the Push Groups tab to see if the synchronization is finished.

    You can also manually push your updates by clicking on the dropdown menu in the Push Status column and selecting Push now.

    push_now.png

    "Push now" overrides the Bitrise group

    Users not included in your Okta group will be automatically removed from the linked Bitrise group.

In this section: