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

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

1. Security → API → click default (the default authorization server)
2. 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

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
• 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

“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.