browser flow override

docs/REFERENCE.md

@@ -1141,6 +1141,30 @@ ignore:
 - Check Gitea Actions tab for workflow run status and logs
 - Monitor Anthropic usage dashboard for token consumption
 
+### Keycloak Browser Flow (IdP Auto-Redirect)
+
+**File**: `infra/values/base/keycloak-values.yaml` (inside `forte-realm.json`)
+
+The realm uses a custom browser authentication flow (`browser-auto-idp`) that skips the Keycloak login page and redirects directly to the Entra ID identity provider.
+
+**Flow executions**:
+
+| Priority | Authenticator | Requirement | Purpose |
+|----------|--------------|-------------|---------|
+| 10 | `auth-cookie` | ALTERNATIVE | Reuse existing session (no redirect) |
+| 20 | `identity-provider-redirector` | ALTERNATIVE | Auto-redirect to `forte-entra` IdP |
+
+**Key fields in realm JSON**:
+- `"browserFlow": "browser-auto-idp"` — overrides the default `browser` flow at realm level
+- `"authenticationFlows"` — defines the custom flow with its executions
+- `"authenticatorConfig"` — sets `defaultProvider: "forte-entra"` on the redirector
+
+**Why custom flow**: The default KC browser flow shows a username/password form with an IdP button. Since all authentication is via Entra ID, the custom flow eliminates this step. The `auth-cookie` execution preserves session reuse so returning users aren't redirected again.
+
+**Important**: The `forte-entra` identity provider must exist in Keycloak (currently configured manually in the KC admin console). If the IdP alias changes, update the `defaultProvider` value in the realm JSON.
+
+---
+
 ### Keycloak Client Registrar
 
 **Type**: CronJob (deployed via Keycloak Helm chart `extraDeploy`)