Skip to content
Mainbranch

Microsoft Entra ID SSO

This guide covers how to configure Single Sign-On (SSO) using Microsoft Entra ID (formerly Azure AD) for your Mainbranch workspace.

Overview

Section titled “Overview”

Microsoft Entra ID SSO enables your users to sign in to Mainbranch using their Microsoft 365 accounts. This provides:

  • Seamless sign-in experience
  • Centralized authentication
  • Automatic access management
  • Support for Microsoft’s MFA policies

Prerequisites

Section titled “Prerequisites”

Before configuring SSO:

  • Admin access to Mainbranch
  • Microsoft 365 admin or Azure admin access
  • Access to Azure Portal

Configuration Steps

Section titled “Configuration Steps”

  1. Create App Registration in Azure

    Register an application in Microsoft Entra ID for Mainbranch.

  2. Configure Redirect URI

    Add the Mainbranch redirect URI to your app registration.

  3. Create Client Secret

    Generate a client secret for authentication.

  4. Enter Credentials in Mainbranch

    Go to Workspace settings > Setup > Authentication and enter:

    • Application (Client) ID
    • Client Secret
    • Directory (Tenant) ID

  5. Test the Connection

    Test SSO by signing out and signing back in with Microsoft.

Azure Portal Setup

Section titled “Azure Portal Setup”

Creating the App Registration

Section titled “Creating the App Registration”
  1. Sign in to Azure Portal
  2. Navigate to Microsoft Entra ID > App registrations
  3. Click New registration
  4. Enter application name (e.g., “Mainbranch SSO”)
  5. Select supported account types (typically single tenant)
  6. Add the Mainbranch redirect URI as a Web platform
  7. Click Register

Generating Client Secret

Section titled “Generating Client Secret”
  1. In your app registration, go to Certificates & secrets
  2. Click New client secret
  3. Add a description and select expiration
  4. Click Add
  5. Copy the secret value immediately (it won’t be shown again)

Required Permissions

Section titled “Required Permissions”

The app requires these Microsoft Graph permissions:

  • openid — Basic authentication
  • email — User email address
  • profile — User profile information

Grant admin consent for these permissions.

Domain and Tenant Configuration

Section titled “Domain and Tenant Configuration”

Single Tenant

Section titled “Single Tenant”

For organizations with one Microsoft tenant:

  1. Enter your Tenant ID
  2. Only users from this tenant can sign in

User Access

Section titled “User Access”

Control who can access Mainbranch:

  • Use Azure AD group restrictions
  • Configure conditional access policies
  • Require Mainbranch invitations if needed

Secret Rotation

Section titled “Secret Rotation”

Client secrets should be rotated periodically.

Rotating Secrets

Section titled “Rotating Secrets”
  1. Create a new secret in Azure
  2. Update the secret in Mainbranch
  3. Test sign-in works
  4. Delete the old secret in Azure

User Access and Provisioning

Section titled “User Access and Provisioning”

Automatic Provisioning

Section titled “Automatic Provisioning”

With SSO configured:

  • Users signing in for the first time are automatically added
  • No manual invitation required
  • Users receive default member role

Controlling Access

Section titled “Controlling Access”

Limit access using:

  • Azure AD group assignments
  • Conditional access policies
  • Mainbranch invitation requirements

Managing SSO Configuration

Section titled “Managing SSO Configuration”

Updating Configuration

Section titled “Updating Configuration”

To update SSO settings:

  1. Go to authentication settings in Mainbranch
  2. Update credentials or settings
  3. Save changes
  4. Test with a sign-in

Disabling SSO

Section titled “Disabling SSO”

To disable Microsoft SSO:

  1. Go to authentication settings
  2. Disable Microsoft SSO
  3. Ensure alternative authentication is available

Security Considerations

Section titled “Security Considerations”

Best Practices

Section titled “Best Practices”
  • Use minimum required permissions
  • Enable Azure AD security features
  • Monitor sign-in logs
  • Rotate secrets regularly

MFA Support

Section titled “MFA Support”

Microsoft MFA is fully supported:

  • Users with MFA complete it during sign-in
  • Mainbranch respects your MFA policies
  • Conditional access policies apply

Conditional Access

Section titled “Conditional Access”

Azure AD conditional access works with Mainbranch:

  • Location-based restrictions
  • Device compliance requirements
  • Risk-based authentication

Troubleshooting

Section titled “Troubleshooting”

”Invalid Client” Error

Section titled “”Invalid Client” Error”
  • Verify Application ID is correct
  • Check that client secret is valid
  • Ensure the app registration exists

Redirect URI Mismatch

Section titled “Redirect URI Mismatch”
  • Verify URI matches exactly in Azure
  • Check for correct protocol (HTTPS)
  • Ensure no trailing slashes unless configured

Tenant Issues

Section titled “Tenant Issues”
  • Verify Tenant ID is correct
  • Check user is in the correct tenant
  • Review tenant restrictions

Users Cannot Sign In

Section titled “Users Cannot Sign In”
  • Verify app has required permissions
  • Check admin consent was granted
  • Review Azure AD sign-in logs

Best Practices

Section titled “Best Practices”

Setup

Section titled “Setup”
  • Document your app registration
  • Use clear naming for the app
  • Test with non-admin account first

Maintenance

Section titled “Maintenance”
  • Set reminders for secret rotation
  • Review permissions periodically
  • Monitor Azure sign-in logs

Security

Section titled “Security”
  • Enable Azure AD security defaults
  • Use conditional access appropriately
  • Don’t share credentials

Next Steps

Section titled “Next Steps”