Entra ID

Configure Azure Entra ID (formerly Azure Active Directory) as the identity provider for your Broch deployment.

These steps reflect the Azure portal as of the time of writing. Microsoft’s UI changes frequently — if anything looks different or doesn’t work as described, refer to the Entra ID documentation or contact [email protected].

Broch uses server-brokered authentication: the server is registered as a confidential Web Application in Entra ID. End users are redirected through the server — they never interact with Entra ID directly from the browser or CLI. The server holds the client secret; it is never exposed to clients.

Prerequisites

• Azure Portal access with permission to create app registrations
• An active Azure AD tenant
• Your Broch server URL (e.g., https://tunnels.company.com)

Step 1: Create an App Registration

1. Go to portal.azure.com → Microsoft Entra ID → App registrations → + New registration
2. Configure:
   • Name: Broch
   • Supported account types: Accounts in this organizational directory only (or multi-tenant if needed)
   • Redirect URI: Leave blank for now
3. Click Register
4. Note the Application (client) ID and Directory (tenant) ID from the overview page

Step 2: Configure Authentication

1. In your app registration, click Authentication → + Add a platform → Web
2. Set the Redirect URI: https://tunnels.company.com/auth/callback (replace with your actual Broch server URL)
3. Click Configure
4. Verify:
   • Implicit grant: both Access tokens and ID tokens should be unchecked
   • Allow public client flows: No

Step 3: Create a Client Secret

1. Certificates & secrets → + New client secret
2. Set a description and expiration period (12 or 24 months recommended)
3. Click Add and immediately copy the Value — it is only shown once

Step 4: Configure App Roles

App roles determine which users have admin access to Broch.

1. App roles → + Create app role
2. Configure:
   • Display name: Admin
   • Allowed member types: Users/Groups
   • Value: Admin
   • Description: Broch administrators
   • Enable this app role: checked
3. Click Apply

Assign the role to users or groups:

1. Microsoft Entra ID → Enterprise applications → find Broch
2. Users and groups → + Add user/group
3. Select the users or groups that should have admin access, select the Admin role, click Assign

Step 5: Configure the Broch Server

Add to your .env or deployment configuration:

AUTHENTICATION__PROVIDER=AzureAd
AUTHENTICATION__INSTANCE=https://login.microsoftonline.com/
AUTHENTICATION__TENANTID=<your-tenant-id>
AUTHENTICATION__CLIENTID=<your-client-id>
AUTHENTICATION__CLIENTSECRET=<your-client-secret>
AUTHENTICATION__ADMINROLES=Admin

Restart the server after changing authentication configuration.

Step 6: Test

1. Open the Broch web app and click Sign In — you should be redirected to Microsoft login
2. Sign in with an account assigned the Admin role — you should land on the admin dashboard
3. Run broch auth login from the CLI — it opens your browser for the same flow and returns authenticated

Verification Checklist

• App registration created with correct client ID and tenant ID
• Authentication platform set to Web (not SPA)
• Redirect URI is https://tunnels.company.com/auth/callback
• Client secret created and copied
• Admin app role created and assigned to at least one user or group
• All environment variables set correctly
• Web login and CLI login both work

Troubleshooting

AADSTS50011: redirect_mismatch The redirect URI in Entra ID does not match your server URL. Verify it is set to https://tunnels.company.com/auth/callback exactly.

AADSTS65001: consent_required Grant admin consent in the Azure Portal: App registrations → your app → API permissions → Grant admin consent.

invalid_client The client secret is wrong or has expired. Check Certificates & secrets and create a new one if needed.

User has no admin access Confirm the Admin app role is assigned to the user (or a group they belong to) in Enterprise applications → Users and groups.