Enable Single Sign On
Overview
Branch offers Security Assertion Markup Language (SAML) / Single Sign-on (SSO) support for the dashboard. This allows you to use your identity provider (IdP) to centralize access to various services for your team and leverage existing directory systems and security groups.
Prerequisites
- Single Sign-on for the Branch dashboard is a paid feature.
- Branch works with Okta and OneLogin, and is compatible with any identity provider that supports SAML.
- For Okta, you may follow the dedicated guide here
Setup SSO
1. Contact Branch
SSO for the Branch dashboard restricts access for designated email domains to a specific dashboard subdomain. Contact your account manager when you are ready to get started. Please provide:
- The email domain(s) that you and your team use and will be required to sign in via SSO.
- The Branch dashboard subdomain you would like your team to use to log in. For example, if you chose
company, then your dashboard subdomain would behttps://company.dashboard.branch.io. - The email addresses of any SSO admins that will be allowed to configure SAML for your team. These SSO admins will also be allowed to log in both via SSO and via regular dashboard login after SSO is enabled so that you have a fallback option to gain access to your account if the configuration goes wrong in some way. These users must also be admins in your Branch dashboard. Please verify that the requested SSO admin users are also present/added with an admin role in your Branch dashboard.
2. Add Branch to your Identity Provider
- Add Branch to your IdP - Add the following SAML attribute mappings:
| SAML Attribute | Field it Should Map to in Your IdP |
|---|---|
email | User's email address |
firstName | User's first name |
lastName | User's last name |
Here is some initial information that your IdP might ask for:
| IdP Field | Value |
|---|---|
| Platform | Web |
| Sign-on method | SAML 2.0 |
| Application name | Branch |
| Logo | Download here |
| ACS URL | https://<subdomain>.dashboard.branch.io/sso/callback |
| Entity ID or Audience URI | https://<subdomain>.dashboard.branch.io |
| SP Metadata | None |
SSO Name ID Format
Branch only supports SSO Name ID Formats, basic or unspecified.
Once this is complete, your IdP will provide you with details that you'll need to add to the Branch dashboard in order to enable SSO.
3. Copy Your IdP Details Back to Branch
- When you have added Branch, your IdP should provide you with an Identity provider Entity ID, an Identity provider SSO URL, and a Public x509 certificate. From the Branch Dashboard, go to Account Settings > SSO and paste in the information to the corresponding fields. Click Save when you're done.
a. If you do not see the above fields it's likely because Branch has not finished enabling your account yet. Please contact your account manager.
4. Add Users to Branch in Your IdP
- Give the appropriate users access to Branch in your identity provider.
a. When you add users to Branch via your IdP in the future you will also have to add them to the team for the appropriate apps in the Branch dashboard. You can do this on the Account Settings > Team page for each app that you want the user to have access to.
Users on Branch But Not Your IdP
If users are on your Branch team in the dashboard but are not given access in your IdP they will no longer be able to log in to the Branch dashboard when SSO is enabled.
5. Enable SSO
- Continue to enable SSO by returning to the Account Settings > SSO page and toggle SAML/SSO to On.
- Click Save at the bottom.
SSO is now enabled and users will have to login via your branded subdomain. When users on your claimed email domain(s) trying to log in, reset password, or sign up the regular way via https://dashboard.branch.io, they will be redirected to your branded subdomain and your IdP login page.
FAQ
Updated 2 months ago