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://broch.{your-domain})

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://broch.{your-domain}/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: Add API Permissions and Grant Admin Consent

Broch requests the standard OIDC scopes: openid, profile, email, offline_access. In tenants that restrict user consent (common), sign-in is blocked with “Need admin approval” until an admin consents.

1. API permissions → + Add a permission → Microsoft Graph → Delegated permissions
2. Select openid, profile, email, and offline_access (under OpenId permissions)
3. Click Add permissions
4. Click Grant admin consent for [your tenant] and confirm

New registrations include User.Read by default. Broch never calls Microsoft Graph on behalf of users; it is safe to remove or leave.

Step 5: Configure App Roles

App roles determine which users have admin access to Broch. They are the only way a named role reaches the token: Entra puts assigned app-role values in the roles claim, while security groups arrive as object IDs, not names.

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

broch_admin is an example value. Use whatever you like — the only requirement is that the app-role value matches what you set in AUTHENTICATION__ADMINROLES (Step 6). It’s also the default Admin roles on the Azure Marketplace form, authAdminRoles on the Azure CLI and AuthAdminRoles on AWS, so those deployments work with this setup unchanged.

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 Broch Admin role, click Assign

Create a second app role the same way for your developers, for example with the value developers, and assign it to the users or groups who will open tunnels. Share Policies grant tunnel access by role, and on Entra only app roles reach the token by name.

Step 6: Configure the Broch Server

On the Azure Marketplace form or the AWS console, enter these values in the identity provider fields. With the Azure CLI, set the matching parameters in main.bicepparam, with the client secret on the command line: AUTHENTICATION__TENANTID becomes authTenantId, and so on. The Marketplace form sets the instance itself. On a self-managed install, set them in the environment:

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=broch_admin

After changing authentication configuration, recreate the server container so it reads the new values: docker compose up -d on Docker Compose, where a restart keeps the old ones. On an appliance, change it in /opt/broch/.env: see Operating the Appliance.

Step 7: 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 Broch 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://broch.{your-domain}/auth/callback
• Client secret created and copied
• Delegated permissions openid, profile, email, offline_access added and admin consent granted
• broch_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://broch.{your-domain}/auth/callback exactly.

“Need admin approval” at sign-in, or AADSTS65001: consent_required The delegated permissions are missing or unconsented. Complete Step 4: add openid, profile, email, offline_access and click 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 broch_admin app role is assigned to the user (or a group they belong to) in Enterprise applications → Users and groups.