Auth0

Configure Auth0 as the identity provider for your Broch deployment.

These steps reflect Auth0’s configuration UI as of the time of writing. IdP interfaces change — if anything looks different or doesn’t work as described, refer to the Auth0 documentation or contact [email protected].

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

Prerequisites

• An Auth0 account (free tier works for evaluation)
• Admin access to your Auth0 tenant
• Your Broch server URL (e.g., https://broch.{your-domain})

Step 1: Create an Auth0 Application

1. Log in to your Auth0 Dashboard
2. Applications → Applications → + Create Application
3. Configure:
   • Name: Broch
   • Application Type: Regular Web Applications
4. Click Create
5. On the Settings tab, note:
   • Domain (e.g., {your-tenant}.auth0.com)
   • Client ID
   • Client Secret — keep this secure; it goes on the server only

Custom domain? If you’ve configured an Auth0 custom domain (e.g., sso.{your-domain}) — available on paid plans — use that hostname in place of the tenant domain throughout this guide. Broch fetches its discovery document from whichever host you configure, and Auth0 returns endpoints (authorization_endpoint, issuer, etc.) matching that host. Operators that want users to see their branded sso.{your-domain} in the login URL must set AUTHENTICATION__DOMAIN to the custom domain.

Configure Application URLs

In the Application URIs section:

Setting	Value
Allowed Callback URLs	https://broch.{your-domain}/auth/callback
Allowed Logout URLs	https://broch.{your-domain}

Note: “Allowed Web Origins” is not required. The Broch server handles all Auth0 communication server-side — there are no browser-based OIDC requests.

Step 2: Create an Auth0 API

The API makes Auth0 issue a JWT access token carrying each user’s roles and permissions. Broch requests it by its Identifier (AUTHENTICATION__AUDIENCE).

1. Applications → APIs → + Create API
2. Configure:
   • Name: Broch API
   • Identifier (Audience): https://broch.{your-domain} (your Broch server URL)
   • Signing Algorithm: RS256
3. Click Create

Enable RBAC

On the API’s Settings tab, under RBAC Settings:

• Enable RBAC: ON
• Add Permissions in the Access Token: ON

Add Permissions

On the API’s Permissions tab, add:

Permission	Description
broch_admin	Full administrative access to Broch

Grant the Broch Application Access

Auth0 APIs can require each application to be explicitly authorized before it may request tokens for them on a user’s behalf. If yours does and Broch isn’t authorized, every sign-in fails with Client "…" is not authorized to access resource server "…". Authorize it either way.

On the API’s Application Access tab, find the Broch application from Step 1, authorize User Access, and select the broch_admin permission.

Step 3: Create a Role

broch_admin is an example name. Use whatever you like — the only requirement is that the role name matches the value you set in AUTHENTICATION__ADMINROLES (Step 5).

1. User Management → Roles → + Create Role
2. Configure:
   • Name: broch_admin
   • Description: Broch administrator
3. Click Create

On the role’s Permissions tab, click Add Permissions, select the Broch API, and add broch_admin.

On the role’s Users tab, assign the role to users who should have admin access.

Create a role for your developers the same way, for example developers, with its own permission on the Broch API, and assign it to the people who will open tunnels. Share Policies grant tunnel access by role.

Step 4: Create a Post-Login Action

Auth0 access tokens do not include email, name, or role names by default. A Post-Login Action adds these claims so the Broch server can read them.

1. Actions → Flows → Login
2. Click + between Start and Complete → Build from scratch
3. Name it Add Broch Claims, runtime Node 18, click Create
4. Replace the default code with:

exports.onExecutePostLogin = async (event, api) => {
  if (event.authorization) {
    api.accessToken.setCustomClaim('email', event.user.email);
    api.accessToken.setCustomClaim('name', event.user.name || event.user.email);
    api.accessToken.setCustomClaim('email_verified', event.user.email_verified);
    api.accessToken.setCustomClaim('roles', event.authorization.roles);
  }
};

Click Deploy, then add it to the flow:

1. Return to Actions → Flows → Login
2. Drag the Add Broch Claims action into the flow between Start and Complete
3. Click Apply

Why both RBAC and the Action? RBAC adds permissions claims that survive token refresh. The Action adds roles, email, and name claims that are set on interactive login. Broch reads both.

Step 5: 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__DOMAIN becomes authDomain, and so on. On a self-managed install, set them in the environment:

AUTHENTICATION__PROVIDER=Auth0
AUTHENTICATION__DOMAIN={your-tenant}.auth0.com
AUTHENTICATION__CLIENTID=<your-client-id>
AUTHENTICATION__CLIENTSECRET=<your-client-secret>
# Required: the API Identifier from Step 2. Broch will not start without it.
AUTHENTICATION__AUDIENCE=https://broch.{your-domain}
AUTHENTICATION__ADMINROLES=broch_admin
# AUTHENTICATION__SCOPES is optional — Broch always requests openid,profile,email,offline_access.
# Set it only to ADD scopes (e.g. an API resource scope); it never replaces the required set.

If you’ve enabled an Auth0 custom domain, set AUTHENTICATION__DOMAIN to the custom domain (e.g., sso.{your-domain}) — not the tenant domain. Users will then see your branded hostname in the login URL, and issued JWTs will carry iss=https://sso.{your-domain}/.

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 6: Test

1. Open the Broch web app and click Sign In — you should be redirected to Auth0 login
2. Sign in with a user 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

• Application type is Regular Web Application (not SPA)
• Callback URL set to https://broch.{your-domain}/auth/callback
• API created; its Identifier matches AUTHENTICATION__AUDIENCE exactly
• Broch application authorized for User Access on the API
• RBAC enabled with “Add Permissions in the Access Token” on
• broch_admin permission added to the API
• broch_admin role created, permission assigned, users assigned
• Post-Login Action deployed and added to the Login flow
• All environment variables set correctly
• Web login and CLI login both work

Troubleshooting

“Unauthorized” errors after login Verify AUTHENTICATION__AUDIENCE matches the API identifier exactly. Confirm RBAC is enabled. Check that the Post-Login Action is both deployed and added to the Login flow.

User has no admin access Confirm the broch_admin permission is on the API, the role has the permission, and the user has the role. If just assigned, the user must log out and back in for the roles claim to update.

Sign-in fails with Client "…" is not authorized to access resource server "…" The Broch application has no user access to the API. Authorize it on the API’s Application Access tab (Step 2).

Sign-in fails with “Service not found” AUTHENTICATION__AUDIENCE does not match any API in your tenant. Copy the API’s Identifier exactly, including scheme and any trailing slash.

Login redirects fail Verify the Callback URL in Auth0 includes /auth/callback exactly and matches your Broch server URL.