diff --git a/contributing-docs/21_keycloak_client_settings.rst b/contributing-docs/21_keycloak_client_settings.rst new file mode 100644 index 0000000000000..1cfaf5371662e --- /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 + - + * - Valid Redirect URIs + - http://localhost:28080/* + - + * - Valid Post Logout Redirect URIs + - http://localhost:28080/* + - + * - 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 9dc2a231d978c..e572649074465 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 0000000000000..db7fc462cbc00 --- /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 +(````). + +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 15a0ebbb2d054..2aea19bc44c72 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 `_