From f363afa08794b34411470dd05d1edced824cbae3 Mon Sep 17 00:00:00 2001
From: Danijel Simeunovic <danijel.simeunovic@fortedigital.com>
Date: Thu, 14 May 2026 23:43:40 +0200
Subject: [PATCH] browser flow override

---
 docs/REFERENCE.md                      | 24 +++++++++++++++++++++
 infra/values/base/keycloak-values.yaml | 30 ++++++++++++++++++++++++++
 2 files changed, 54 insertions(+)

diff --git a/docs/REFERENCE.md b/docs/REFERENCE.md
index bfa7f46..3eae2a8 100644
--- a/docs/REFERENCE.md
+++ b/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`)
diff --git a/infra/values/base/keycloak-values.yaml b/infra/values/base/keycloak-values.yaml
index 644fb35..c00a1d3 100644
--- a/infra/values/base/keycloak-values.yaml
+++ b/infra/values/base/keycloak-values.yaml
@@ -188,6 +188,36 @@ keycloakConfigCli:
             ]
           }
         ],
+        "browserFlow": "browser-auto-idp",
+        "authenticationFlows": [
+          {
+            "alias": "browser-auto-idp",
+            "description": "Browser flow with auto-redirect to Forte Entra IdP",
+            "providerId": "basic-flow",
+            "topLevel": true,
+            "builtIn": false,
+            "authenticationExecutions": [
+              {
+                "authenticator": "auth-cookie",
+                "authenticatorFlow": false,
+                "requirement": "ALTERNATIVE",
+                "priority": 10
+              },
+              {
+                "authenticator": "identity-provider-redirector",
+                "authenticatorFlow": false,
+                "requirement": "ALTERNATIVE",
+                "priority": 20,
+                "authenticatorConfig": {
+                  "alias": "forte-entra-redirector",
+                  "config": {
+                    "defaultProvider": "forte-entra"
+                  }
+                }
+              }
+            ]
+          }
+        ],
         "groups": [
           {
             "name": "k8s",