Identity Providers

Broch signs everyone in through your identity provider. The Broch server is the only OAuth client: it brokers every sign-in, from the browser and the CLI, and issues its own tokens. Your IdP’s MFA, conditional access and group policies apply as usual.

What Every Provider Needs

• One app registration per deployment, as a Web Application (confidential client). Its client secret stays on the server.
• The redirect URI: your server URL plus /auth/callback, such as https://broch.{your-domain}/auth/callback. The server URL is the subdomain plus the DNS zone you choose when you deploy.
• An admin role your first admin holds, passed in the token. Broch grants admin by role; there’s no local admin account. On Entra ID it must be an app role, which you can assign to a group.
• A role for your developers. Share Policies grant tunnel access by role, so the people who’ll open tunnels need one in the token too.

Step-by-Step Guides

• Auth0 — RBAC and a post-login action
• Entra ID — App roles
• Okta — Groups and an authorization server
• Generic OIDC — Any other OpenID Connect provider

Every deployment asks for the client ID, secret and admin role from this setup. Contact [email protected] if you need help.

Why Broch Is the Only OAuth Client

Simpler to configure

One app registration covers every Broch client — web app, CLI, and any future client. You configure one redirect URI (your server URL), one client secret, and one set of scopes. Adding or updating a client needs no change in your IdP.

More secure than public clients

Public clients (SPAs and native apps that handle OAuth directly) cannot keep a client secret. This forces them to rely on PKCE and short-lived tokens stored in browser memory or local storage — both reachable by malicious scripts. The IETF OAuth 2.0 Security Best Current Practice (RFC 9700) explicitly recommends against issuing tokens to public clients when a confidential client is feasible.

The Backend for Frontend (BFF) pattern addresses this by moving all token handling to the server. Tokens are never sent to the browser; the browser holds only a session cookie. This eliminates the XSS token-theft risk entirely. The OAuth 2.0 for Browser-Based Apps specification recommends the BFF pattern for any application that needs to call APIs on behalf of a user.

Recovering From a Broken IdP Configuration

IdP configuration saved through the admin UI persists to the database and overrides the AUTHENTICATION__* environment values on the next restart. That creates one failure mode worth knowing in advance: if the persisted client secret expires or is rotated at the IdP (Entra enforces secret expiry of 24 months or less), every sign-in fails with invalid_client — including the admin sign-in you’d use to fix it. Updating the environment variable doesn’t help, because the persisted value still wins.

The break-glass is BROCH_AUTH_CONFIG_RESET:

BROCH_AUTH_CONFIG_RESET=true

Set it and restart the server. On Docker Compose, the compose file doesn’t pass this variable: add BROCH_AUTH_CONFIG_RESET: 'true' to the broch service’s environment: block and run docker compose up -d. At boot, Broch clears the persisted IdP configuration and falls back to your AUTHENTICATION__* environment values, or to setup if none are set. Sign in, re-enter the corrected configuration in the admin UI if you manage it there, then remove the variable: while it is set, every restart clears the persisted configuration again.

The server log names this lever when the IdP rejects the client credentials, so you’ll find it again under pressure: look for invalid_client in the server output.