Setting up AD FS SSO for Bitrise

This guide provides step-by-step instructions on setting up SAML SSO using Microsoft Active Directory Federation Services (AD FS).

Before you start ⚓

Before connecting SAML SSO to your Workspace on Bitrise, make sure:

• The AD FS administrator is at hand during the SAML SSO configuration process.
• As with other Workspace management actions, only the Bitrise Workspace owner can set up SAML SSO to a Bitrise Workspace.
• Your account on Bitrise has a Workspace with the Velocity and Enterprise Build plans. If it doesn’t have an Workspace, go ahead and create one. Setting up SAML SSO is the same for existing and brand new Workspaces on Bitrise.

Navigating to 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. On your Bitrise Dashboard click your avatar, then click Profile settings in the dropdown.
2. The Overview page displays all the Workspaces you’re a member of. Select the Workspace where you wish to set up the SAML SSO connection.
3. On the left menu bar, click the Single Sign-On which will take you to the Enable Single Sign-On page.
4. Continue with Configuring SAML SSO on Bitrise and AD FS.

Configuring SAML SSO on Bitrise and AD FS ⚓

In this tutorial we will be jumping back and forth between Bitrise and AD FS so it is recommended that both tools are available during this process.

1. Add the Identity provider sign-on URL from AD FS in the SAML SSO provider Single Sign-On URL (SSO URL) field of Bitrise. For example, a valid value is https://<AD FS URL>.com/adfs/ls.

Exporting a certificate ⚓

1. You have to add a certificate generated by AD FS to the SAML SSO provider certificate field of the Single Sign-On page on Bitrise. If you’ve already created a certificate on AD FS, you can export it in PEM format from the AD FS server. If you haven’t created one yet, follow the instructions on Microsoft’s official guide: Obtain and Configure TS and TD Certificates for AD FS.
2. In Server Manager, click Tools, and select AD FS Management.
3. Select the Certificates folder on the left menu pane.
4. Click a certificate under Token-signing. This brings up the Certificates window.
5. Click Details tab on the Certificate page.
6. Hit Next on the Certificate Export Wizard window.
7. Select the Base-64 encoded X.509 (.CER) the export file format. Click Next.
8. Give it a name in the File name field and hit Save.
9. Have a final look at your certificate settings. If you need to modify any of those, click the backward arrow next to Certificate Export Wizard. Otherwise, click Finish. Make sure you leave the AD FS window open as you will need it in a minute.
10. Open the exported certificate by a text editor and copy/paste its content to the SAML SSO provider certificate field or upload the file itself from your local computer.
11. Save the settings by clicking Configure SSO on Bitrise. Let’s continue the SAML SSO configuration on AD FS by adding Bitrise.

Adding Bitrise as a relying party trust to AD FS ⚓

Once you are finished with exporting the certificate, you can continue with adding Bitrise as a relying party trust to AD FS. The Add Relying Party Trust Wizard guides you through the steps.

1. On AD FS, click Relying Party Trust on the left menu bar, then click Relying Party Trust.
2. Select Add Relying Party Trust under Actions.
3. On the Welcome page, select the Claims aware option and hit Start.
4. On the Select Data Source page, click the Enter data about the relying party manually option on the bottom of the page. Click Next.
5. On the Specify Display Name page, add a Display name, for example MyCorp. Click Next.
6. Specify a token encryption certificate on the Configure Certificate page is optional. Click Next.
7. On the Configure URL page, select Enable support for the SAML 2.0 WebSSO protocol and copy paste the Assertion Consumer Service URL (ACS URL) from Bitrise to the Relying party SAML 2. 0 SSO service URL field on AD FS. Click Next.
8. On the Configure Identifiers page, add Bitrise in the Relying party trust identifier field. Click Add, then hit Next.
9. Do not modify the default access control policy on the Choose Access Control Policy page so that everyone can access this SAML SSO connection. Click Next.
10. On the Ready to Add Trust page, review the settings and click Next.
11. On the Finish page, tick the checkbox to edit claims issuance policy for Bitrise. Click Close.

Configuring claim rules ⚓

1. On the Edit Claim Issuance Policy page, click the Add Rule button and hit OK.
2. Create a Send LDAP Attributes as Claims claim rule and click Next.
3. On the Configure Claim Rule page:
   • Add a rule name, for example Send E-mail, in the Claim rule name field.
   • Select an Attribute Store which is most likely the Active Directory.
   • In the Mapping of LDAP attributes to outgoing claim types field select E-mail Addresses.
4. Click Finish.
5. Add another new rule that turns an E-mail to a formatter NameID. To do so, click Add rule in the Edit Claim Issuance Policy page again.
6. On the Select Rule Template, select Transform an Incoming Claim option in the Claim rule template dropdown. Click Next.
7. Give a name to the new rule, for example, Transform E-mail.
8. Select E-Mail Address as the Incoming Claim Type.
9. Select NameId as the Outgoing claim type.
10. Choose Email as the Outgoing name ID format.
11. Hit OK to finish the process.

What’s next? ⚓

Learn how you can log into your Workspace now that SAML SSO is set up.

You might wan to check out Workspace member’s SAML SSO statuses once the connection is up.

You might want to enforce SAML SSO login to the Workspace once all Workspace members have authorized their SAML SSO connection to the Workspace.

Disabling SAML SSO is very simple - learn how.