Skip to content

Commit cc16dd6

Browse files
bugraoz93vincbeck
bugraoz93
and
vincbeck
authored
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 <97131062+vincbeck@users.noreply.github.com> * Update Keycloak client configuration documentation for clarity and accuracy --------- Co-authored-by: Vincent <97131062+vincbeck@users.noreply.github.com>
1 parent b72df7b commit cc16dd6

4 files changed

Lines changed: 168 additions & 0 deletions

File tree

‎contributing-docs/21_keycloak_client_settings.rst‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
.. Licensed to the Apache Software Foundation (ASF) under one
2+
or more contributor license agreements. See the NOTICE file
3+
distributed with this work for additional information
4+
regarding copyright ownership. The ASF licenses this file
5+
to you under the Apache License, Version 2.0 (the
6+
"License"); you may not use this file except in compliance
7+
with the License. You may obtain a copy of the License at
8+
9+
.. http://www.apache.org/licenses/LICENSE-2.0
10+
11+
.. Unless required by applicable law or agreed to in writing,
12+
software distributed under the License is distributed on an
13+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
KIND, either express or implied. See the License for the
15+
specific language governing permissions and limitations
16+
under the License.
17+
18+
Setting up Keycloak Client for Breeze
19+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
20+
To fully integrate Keycloak into local Airflow development with Breeze, you need to configure a Keycloak client.
21+
You can start by using the ``breeze start-airflow --integration keycloak`` command,
22+
which launches Airflow with Keycloak support and starts a Keycloak instance with default settings.
23+
24+
Next, create a Keycloak client for Airflow in the Keycloak admin console, accessible at ``http://localhost:48080/``.
25+
During client creation, the relevant configuration section is called ``Login Settings``;
26+
after the client is created, this section appears as ``Access Settings``.
27+
28+
.. list-table::
29+
:header-rows: 1
30+
:widths: 25 75 75
31+
32+
* - Field
33+
- Local (Breeze) Value
34+
- Local (Breeze) Templated Value
35+
* - Root URL
36+
- http://localhost:28080
37+
- ${authBaseUrl}
38+
* - Home URL
39+
- http://localhost:28080
40+
- <Not Usable>
41+
* - Valid Redirect URIs
42+
- http://localhost:28080/*
43+
- <Not Usable>
44+
* - Valid Post Logout Redirect URIs
45+
- http://localhost:28080/*
46+
- <Not Usable>
47+
* - Web Origins
48+
- http://localhost:28080
49+
- ${authBaseUrl}
50+
51+
After you configure the client, the settings will persist as long as the Docker volumes are not removed.
52+
To obtain the client credentials, open the ``Credentials`` tab of the client you created.

‎providers/keycloak/docs/auth-manager/index.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,3 +47,10 @@ It enables you to manage users, roles, groups, and permissions entirely within K
4747
:maxdepth: 2
4848

4949
token
50+
51+
**Setup client Access/Login Settings**
52+
53+
.. toctree::
54+
:maxdepth: 2
55+
56+
manage/login

‎providers/keycloak/docs/auth-manager/manage/login.rst‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
.. Licensed to the Apache Software Foundation (ASF) under one
2+
or more contributor license agreements. See the NOTICE file
3+
distributed with this work for additional information
4+
regarding copyright ownership. The ASF licenses this file
5+
to you under the Apache License, Version 2.0 (the
6+
"License"); you may not use this file except in compliance
7+
with the License. You may obtain a copy of the License at
8+
9+
.. http://www.apache.org/licenses/LICENSE-2.0
10+
11+
.. Unless required by applicable law or agreed to in writing,
12+
software distributed under the License is distributed on an
13+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
KIND, either express or implied. See the License for the
15+
specific language governing permissions and limitations
16+
under the License.
17+
18+
================================================
19+
Manage login settings with Keycloak auth manager
20+
================================================
21+
This topic is related to the Keycloak ``Login Settings``.
22+
These settings appear when you create a client in Keycloak, and remain accessible afterward under the ``Access Settings`` tab.
23+
They play an important role in limiting the client's scope and reducing its potential impact area.
24+
25+
Keycloak Client Configuration Guide
26+
===================================
27+
This document explains how to properly configure a Keycloak client using your production HTTP(S) URL
28+
(``<https://yourcompany.airflow.com>``).
29+
30+
Overview
31+
--------
32+
Client configuration is a crucial part of enabling Keycloak authentication for your application.
33+
You must ensure that Client Authentication, Authorization, and the Authentication Flow are correctly configured.
34+
35+
Set ``Client Authentication`` to ``ON``.
36+
Set ``Authorization`` to ``ON``.
37+
For ``Authentication Flow`` values, refer to the table below.
38+
39+
Login settings (After Client is Created)
40+
----------------------------------------
41+
.. list-table::
42+
:header-rows: 1
43+
:widths: 30 70
44+
45+
* - Field
46+
- Value
47+
* - Standard Flow
48+
- ON
49+
* - Direct Access Grants
50+
- ON
51+
* - Implicit Flow
52+
- OFF
53+
* - Service accounts roles
54+
- ON (by default if configuration overridden from Keycloak)
55+
* - OAuth 2.0 Device Authorization Grant
56+
- OFF
57+
* - OIDC CIBA Grant
58+
- OFF
59+
60+
To enable your application to authenticate users through Keycloak, you must configure the following fields in your Keycloak client:
61+
62+
* Root URL
63+
* Home URL
64+
* Valid Redirect URIs
65+
* Valid Post Logout Redirect URIs
66+
* Web Origins
67+
* Admin URL (optional)
68+
69+
Login Settings (While Creating Client)/Access Settings (After Client is Created)
70+
--------------------------------------------------------------------------------
71+
.. list-table::
72+
:header-rows: 1
73+
:widths: 30 40
74+
75+
* - Field
76+
- Production Value
77+
* - Root URL
78+
- https://yourcompany.airflow.com
79+
* - Home URL
80+
- https://yourcompany.airflow.com
81+
* - Valid Redirect URIs
82+
- https://yourcompany.airflow.com/*
83+
* - Valid Post Logout Redirect URIs
84+
- https://yourcompany.airflow.com/*
85+
* - Web Origins
86+
- https://yourcompany.airflow.com
87+
88+
Logout settings (After Client is Created)
89+
-----------------------------------------
90+
.. list-table::
91+
:header-rows: 1
92+
:widths: 30 70
93+
94+
* - Field
95+
- Value
96+
* - Front channel logout
97+
- ON
98+
99+
Notes on Keycloak Template Variables
100+
------------------------------------
101+
102+
``${authBaseUrl}``
103+
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.

‎providers/keycloak/docs/security.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,9 @@
1616
under the License.
1717
1818
.. include:: /../../../devel-common/src/sphinx_exts/includes/security.rst
19+
20+
21+
Setting up Keycloak Client
22+
==========================
23+
You can both create or use an existing Keycloak realm and create a client for Airflow in it.
24+
To create a client, follow the `Keycloak Client </auth-manager/manage/login.html>`_

0 commit comments

Comments
 (0)