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://tunnels.company.com)

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., acme-corp.auth0.com)
   • Client ID
   • Client Secret — keep this secure; it goes on the server only

Configure Application URLs

In the Application URIs section:

Setting	Value
Allowed Callback URLs	https://tunnels.company.com/auth/callback
Allowed Logout URLs	https://tunnels.company.com

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 represents your Broch server and is used to validate access tokens.

1. Applications → APIs → + Create API
2. Configure:
   • Name: Broch API
   • Identifier (Audience): https://tunnels.company.com (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

Step 3: Create a Role

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.

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

AUTHENTICATION__PROVIDER=Auth0
AUTHENTICATION__DOMAIN=acme-corp.auth0.com
AUTHENTICATION__CLIENTID=<your-client-id>
AUTHENTICATION__CLIENTSECRET=<your-client-secret>
AUTHENTICATION__AUDIENCE=https://tunnels.company.com
AUTHENTICATION__SCOPES=openid,profile,email,offline_access
AUTHENTICATION__ADMINROLES=broch_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 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://tunnels.company.com/auth/callback
• API created with audience identifier matching your server URL
• 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.

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