diff --git a/providers/keycloak/docs/auth-manager/manage/permissions.rst b/providers/keycloak/docs/auth-manager/manage/permissions.rst index 644c21e963c86..94d665ac63dac 100644 --- a/providers/keycloak/docs/auth-manager/manage/permissions.rst +++ b/providers/keycloak/docs/auth-manager/manage/permissions.rst @@ -19,4 +19,75 @@ Manage user permissions with Keycloak auth manager ================================================== -To be completed +You can set-up and manage user permissions with Keycloak auth manager in different ways: + +1. Using Airflow CLI +2. Using Keycloak console + +With Airflow CLI +---------------- +Setting up the permissions can be done using CLI commands. +They can create the permissions and needed resources easily. + +There are two options to create the permissions: + +* Create all permissions (Scopes, Resources, Permissions) in one go using one CLI command +* Create all permissions (Scopes, Resources, Permissions) step-by-step using the CLI commands + +CLI commands take the following parameters: + +* ``--username``: Keycloak admin username +* ``--password``: Keycloak admin password +* ``--user-realm``: Keycloak user realm +* ``--client-id``: Keycloak client id (default: admin-cli) + +Please check the `Keycloak auth manager CLI `_ documentation for more information about accepted parameters. + +One-go creation of permissions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +There is a single command do all the magic for you. + +This command will create scopes, resources and permissions in one-go. + +.. code-block:: bash + + airflow keycloak create-all + +Step-by-step creation of permissions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +First we need to create scopes for the permissions. These scopes later will be used in Keycloak authorization [1]. + +This command will create scopes for certain types of permissions. + +.. code-block:: bash + + airflow keycloak create-scopes + +This command will create resources for certain types of permissions. + +.. code-block:: bash + + airflow keycloak create-resources + +Finally, with the command below, we create the permissions using the previously created scopes and resources. + +.. code-block:: bash + + airflow keycloak create-permissions + +This will create + +* read-only permissions +* admin permissions +* user permissions +* operations permissions + +More resources about permissions can be found in the official documentation of Keycloak: + +1- `Keylcloak Authorization Process `_ + +2- `Keycloak Permission Overview `_ + +3- `Keycloak Creating scope-based Permissions `_ diff --git a/providers/keycloak/docs/cli-refs.rst b/providers/keycloak/docs/cli-refs.rst new file mode 100644 index 0000000000000..eef6311221f82 --- /dev/null +++ b/providers/keycloak/docs/cli-refs.rst @@ -0,0 +1,26 @@ + .. 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. + +Command Line Interface (CLI) +============================ + +Provider CLI has been integrated with Apache Airflow CLI ``airflow`` command. + +.. argparse:: + :module: airflow.providers.keycloak.auth_manager.keycloak_auth_manager + :func: get_parser + :prog: airflow diff --git a/providers/keycloak/docs/index.rst b/providers/keycloak/docs/index.rst index 4cd175d3ae9ae..45001d1bbe146 100644 --- a/providers/keycloak/docs/index.rst +++ b/providers/keycloak/docs/index.rst @@ -44,6 +44,7 @@ Python API <_api/airflow/providers/keycloak/index> Configuration Keycloak auth manager token API + CLI .. toctree:: :hidden: diff --git a/providers/keycloak/src/airflow/providers/keycloak/auth_manager/keycloak_auth_manager.py b/providers/keycloak/src/airflow/providers/keycloak/auth_manager/keycloak_auth_manager.py index c269210b5e8bd..d91b5030bdab9 100644 --- a/providers/keycloak/src/airflow/providers/keycloak/auth_manager/keycloak_auth_manager.py +++ b/providers/keycloak/src/airflow/providers/keycloak/auth_manager/keycloak_auth_manager.py @@ -16,6 +16,7 @@ # under the License. from __future__ import annotations +import argparse import json import logging from typing import TYPE_CHECKING, Any @@ -34,7 +35,7 @@ from airflow.api_fastapi.auth.managers.base_auth_manager import ResourceMethod as ExtendedResourceMethod from airflow.api_fastapi.common.types import MenuItem -from airflow.cli.cli_config import CLICommand, GroupCommand +from airflow.cli.cli_config import CLICommand, DefaultHelpParser, GroupCommand from airflow.configuration import conf from airflow.exceptions import AirflowException from airflow.providers.keycloak.auth_manager.cli.definition import KEYCLOAK_AUTH_MANAGER_COMMANDS @@ -69,6 +70,17 @@ RESOURCE_ID_ATTRIBUTE_NAME = "resource_id" +def get_parser() -> argparse.ArgumentParser: + """Generate documentation; used by Sphinx argparse.""" + from airflow.cli.cli_parser import AirflowHelpFormatter, _add_command + + parser = DefaultHelpParser(prog="airflow", formatter_class=AirflowHelpFormatter) + subparsers = parser.add_subparsers(dest="subcommand", metavar="GROUP_OR_COMMAND") + for group_command in KeycloakAuthManager.get_cli_commands(): + _add_command(subparsers, group_command) + return parser + + class KeycloakAuthManager(BaseAuthManager[KeycloakAuthManagerUser]): """ Keycloak auth manager.