Okta

Configure Okta as the identity provider for your Broch deployment.

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

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

Prerequisites

• An Okta account (free developer account available at developer.okta.com)
• Admin access to your Okta organization
• Your Broch server URL (e.g., https://tunnels.company.com)

Step 1: Create an Okta Application

1. Log in to your Okta Admin Console
2. Applications → Applications → Create App Integration
3. Configure:
   • Sign-in method: OIDC - OpenID Connect
   • Application type: Web Application (not Single-Page Application)
4. Click Next
5. Configure the application:
   • App integration name: Broch
   • Grant type: Authorization Code + Refresh Token
   • Sign-in redirect URI: https://tunnels.company.com/auth/callback
   • Sign-out redirect URI: https://tunnels.company.com
6. Click Save
7. Note the Client ID and Client Secret from the application’s General tab

Web Application, not SPA: Broch registers as a confidential Web Application because the server holds a client secret and brokers all OAuth flows. No public client (SPA) registration is needed or used.

Step 2: Configure the Authorization Server

Broch authenticates against Okta’s default authorization server (the authority is https://<domain>/oauth2/default). Two things must be set on it: an access policy that lets the Broch app obtain tokens, and a groups claim so Broch can map admin access.

Open Security → API → click default (the default authorization server).

Access policy

The default server issues tokens only when an access-policy rule matches the request. If no rule applies, login fails at Okta with 400 Bad Request — “Policy evaluation failed for this request” (access_denied).

1. Go to the Access Policies tab
2. If no policy is already assigned to the Broch app, click Add New Access Policy:
   • Name: Broch
   • Assign to: The following clients → select your Broch app. Scope it to Broch rather than All clients — the default server is shared by every app in your org, so an “All clients” policy governs unrelated apps too. (Use All clients only if Broch is the only app on this server.)
3. On that policy, Add Rule:
   • Grant type: Authorization Code only. Broch uses the authorization-code flow plus refresh tokens; it does not use Client Credentials or Device Authorization, so leave those unchecked.
   • User is: Any user assigned the app. Access is gated by the app assignment in Step 3 — you assign the app only to the groups you intend — so you don’t need to list groups again here.
   • Scopes requested: Any scopes (or restrict to openid, profile, email, offline_access)
   • Leave the access- and refresh-token lifetimes at their defaults
4. Click Create

Many Okta orgs ship a “Default Policy / Default Policy Rule” on the default server that already grants this. If one exists and applies to your app (or all clients), you can skip adding a new policy — just confirm it allows the Authorization Code grant.

Groups claim

Okta does not include group membership in tokens by default. Add a groups claim to the default authorization server.

1. Go to the Claims tab → Add Claim

Add the claim twice — once for ID Token, once for Access Token:

Field	Value
Name	groups
Include in token type	ID Token (first), then Access Token (second)
Value type	Groups
Filter	Matches regex — .*
Include in	Any scope

Click Create after each.

If you have many groups and want to limit token size, use a more specific filter such as broch.*.

Step 3: Create Groups and Assign Users

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

1. Directory → Groups → Add Group
2. Configure:
   • Name: broch_admin
   • Description: Broch administrators
3. Click Save
4. Open the group → Assign people → add the users who should have admin access

Assign the application to the group:

1. Applications → Applications → Broch → Assignments
2. Assign → Assign to Groups → assign broch_admin
3. Repeat for any other groups that should have access

Step 4: Configure the Broch Server

AUTHENTICATION__PROVIDER=Okta
AUTHENTICATION__DOMAIN=acme-corp.okta.com
AUTHENTICATION__CLIENTID=<your-client-id>
AUTHENTICATION__CLIENTSECRET=<your-client-secret>
AUTHENTICATION__ADMINROLES=broch_admin

Broch constructs the authority URL as https://<domain>/oauth2/default automatically. Only set AUTHENTICATION__AUDIENCE if you are using a custom authorization server with a different audience.

Restart the server after changing authentication configuration.

Step 5: Test

1. Open the Broch web app and click Sign In — you should be redirected to Okta login
2. Sign in with a user in the broch_admin group — 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 Web Application (not SPA)
• Grant types include Authorization Code and Refresh Token
• Sign-in redirect URI is https://tunnels.company.com/auth/callback
• Client secret noted
• Access policy on the default authorization server grants the Broch app the Authorization Code grant
• groups claim added to both ID Token and Access Token on the default authorization server
• broch_admin group created and users assigned
• Application assigned to the group
• All environment variables set correctly
• Web login and CLI login both work

Troubleshooting

“Policy evaluation failed for this request” / access_denied The default authorization server has no access-policy rule that grants the request. Under Security → API → default → Access Policies, confirm a policy is assigned to the Broch app (or all clients) with a rule allowing the Authorization Code grant (Step 2). Also confirm the signing-in user is assigned the app (Applications → Broch → Assignments, Step 3) — the rule grants only users assigned the app.

“The ‘redirect_uri’ parameter must be a Login redirect URI” error The callback URL Broch sent is not registered on the Okta app. Add https://<your-server>/auth/callback exactly (scheme, host, and path) under the app’s General → Sign-in redirect URIs (Step 1).

“Invalid issuer” error AUTHENTICATION__DOMAIN must be only the domain (e.g., acme-corp.okta.com) — do not include https:// or /oauth2/default. Broch adds these automatically.

User has no admin access Verify the groups claim is on the default authorization server (not just the application). Confirm it is added for both ID Token and Access Token. Check that the user is a member of broch_admin in Directory → Groups.

“Audience mismatch” error By default Okta uses the Client ID as the audience. Remove AUTHENTICATION__AUDIENCE from your config unless you have explicitly configured a custom audience on the authorization server.

Token does not contain groups Use the Token Preview tab on the authorization server (Security → API → default → Token Preview) to verify the groups claim appears for your user with scope openid.