This is an automated email from the ASF dual-hosted git repository.
bugraoz pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new cc16dd60ac7 Add Keycloak login settings management documentation
(#58605)
cc16dd60ac7 is described below
commit cc16dd60ac78ffff9e2b6c49a3afac677adcd92c
Author: Bugra Ozturk <[email protected]>
AuthorDate: Wed Nov 26 21:36:04 2025 +0100
Add Keycloak login settings management documentation (#58605)
* add Keycloak login settings management documentation
* move local parts to contributing doc and update user docs
* Apply suggestion from @vincbeck
Co-authored-by: Vincent <[email protected]>
* Update Keycloak client configuration documentation for clarity and
accuracy
---------
Co-authored-by: Vincent <[email protected]>
---
contributing-docs/21_keycloak_client_settings.rst | 52 +++++++++++
providers/keycloak/docs/auth-manager/index.rst | 7 ++
.../keycloak/docs/auth-manager/manage/login.rst | 103 +++++++++++++++++++++
providers/keycloak/docs/security.rst | 6 ++
4 files changed, 168 insertions(+)
diff --git a/contributing-docs/21_keycloak_client_settings.rst
b/contributing-docs/21_keycloak_client_settings.rst
new file mode 100644
index 00000000000..1cfaf537166
--- /dev/null
+++ b/contributing-docs/21_keycloak_client_settings.rst
@@ -0,0 +1,52 @@
+ .. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ .. http://www.apache.org/licenses/LICENSE-2.0
+
+ .. Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+Setting up Keycloak Client for Breeze
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+To fully integrate Keycloak into local Airflow development with Breeze, you
need to configure a Keycloak client.
+You can start by using the ``breeze start-airflow --integration keycloak``
command,
+which launches Airflow with Keycloak support and starts a Keycloak instance
with default settings.
+
+Next, create a Keycloak client for Airflow in the Keycloak admin console,
accessible at ``http://localhost:48080/``.
+During client creation, the relevant configuration section is called ``Login
Settings``;
+after the client is created, this section appears as ``Access Settings``.
+
+.. list-table::
+ :header-rows: 1
+ :widths: 25 75 75
+
+ * - Field
+ - Local (Breeze) Value
+ - Local (Breeze) Templated Value
+ * - Root URL
+ - http://localhost:28080
+ - ${authBaseUrl}
+ * - Home URL
+ - http://localhost:28080
+ - <Not Usable>
+ * - Valid Redirect URIs
+ - http://localhost:28080/*
+ - <Not Usable>
+ * - Valid Post Logout Redirect URIs
+ - http://localhost:28080/*
+ - <Not Usable>
+ * - Web Origins
+ - http://localhost:28080
+ - ${authBaseUrl}
+
+After you configure the client, the settings will persist as long as the
Docker volumes are not removed.
+To obtain the client credentials, open the ``Credentials`` tab of the client
you created.
diff --git a/providers/keycloak/docs/auth-manager/index.rst
b/providers/keycloak/docs/auth-manager/index.rst
index 9dc2a231d97..e5726490744 100644
--- a/providers/keycloak/docs/auth-manager/index.rst
+++ b/providers/keycloak/docs/auth-manager/index.rst
@@ -47,3 +47,10 @@ It enables you to manage users, roles, groups, and
permissions entirely within K
:maxdepth: 2
token
+
+**Setup client Access/Login Settings**
+
+.. toctree::
+ :maxdepth: 2
+
+ manage/login
diff --git a/providers/keycloak/docs/auth-manager/manage/login.rst
b/providers/keycloak/docs/auth-manager/manage/login.rst
new file mode 100644
index 00000000000..db7fc462cbc
--- /dev/null
+++ b/providers/keycloak/docs/auth-manager/manage/login.rst
@@ -0,0 +1,103 @@
+ .. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ .. http://www.apache.org/licenses/LICENSE-2.0
+
+ .. Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+================================================
+Manage login settings with Keycloak auth manager
+================================================
+This topic is related to the Keycloak ``Login Settings``.
+These settings appear when you create a client in Keycloak, and remain
accessible afterward under the ``Access Settings`` tab.
+They play an important role in limiting the client's scope and reducing its
potential impact area.
+
+Keycloak Client Configuration Guide
+===================================
+This document explains how to properly configure a Keycloak client using your
production HTTP(S) URL
+(``<https://yourcompany.airflow.com>``).
+
+Overview
+--------
+Client configuration is a crucial part of enabling Keycloak authentication for
your application.
+You must ensure that Client Authentication, Authorization, and the
Authentication Flow are correctly configured.
+
+Set ``Client Authentication`` to ``ON``.
+Set ``Authorization`` to ``ON``.
+For ``Authentication Flow`` values, refer to the table below.
+
+Login settings (After Client is Created)
+----------------------------------------
+.. list-table::
+ :header-rows: 1
+ :widths: 30 70
+
+ * - Field
+ - Value
+ * - Standard Flow
+ - ON
+ * - Direct Access Grants
+ - ON
+ * - Implicit Flow
+ - OFF
+ * - Service accounts roles
+ - ON (by default if configuration overridden from Keycloak)
+ * - OAuth 2.0 Device Authorization Grant
+ - OFF
+ * - OIDC CIBA Grant
+ - OFF
+
+To enable your application to authenticate users through Keycloak, you must
configure the following fields in your Keycloak client:
+
+* Root URL
+* Home URL
+* Valid Redirect URIs
+* Valid Post Logout Redirect URIs
+* Web Origins
+* Admin URL (optional)
+
+Login Settings (While Creating Client)/Access Settings (After Client is
Created)
+--------------------------------------------------------------------------------
+.. list-table::
+ :header-rows: 1
+ :widths: 30 40
+
+ * - Field
+ - Production Value
+ * - Root URL
+ - https://yourcompany.airflow.com
+ * - Home URL
+ - https://yourcompany.airflow.com
+ * - Valid Redirect URIs
+ - https://yourcompany.airflow.com/*
+ * - Valid Post Logout Redirect URIs
+ - https://yourcompany.airflow.com/*
+ * - Web Origins
+ - https://yourcompany.airflow.com
+
+Logout settings (After Client is Created)
+-----------------------------------------
+.. list-table::
+ :header-rows: 1
+ :widths: 30 70
+
+ * - Field
+ - Value
+ * - Front channel logout
+ - ON
+
+Notes on Keycloak Template Variables
+------------------------------------
+
+``${authBaseUrl}``
+This resolves to **Keycloak's own base URL**, not your application's URL. You
should not use it as the Root URL for your Airflow application.
diff --git a/providers/keycloak/docs/security.rst
b/providers/keycloak/docs/security.rst
index 15a0ebbb2d0..2aea19bc44c 100644
--- a/providers/keycloak/docs/security.rst
+++ b/providers/keycloak/docs/security.rst
@@ -16,3 +16,9 @@
under the License.
.. include:: /../../../devel-common/src/sphinx_exts/includes/security.rst
+
+
+Setting up Keycloak Client
+==========================
+You can both create or use an existing Keycloak realm and create a client for
Airflow in it.
+To create a client, follow the `Keycloak Client
</auth-manager/manage/login.html>`_
