docs(keycloak): Update documentation for Keycloak auth manager CLI usage and permission management

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 </cli-refs.html>`_ 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 <https://www.keycloak.org/docs/latest/authorization_services/index.html#the-authorization-process>`_
+
+2- `Keycloak Permission Overview <https://www.keycloak.org/docs/latest/authorization_services/index.html#_permission_overview>`_
+
+3- `Keycloak Creating scope-based Permissions <https://www.keycloak.org/docs/latest/authorization_services/index.html#_policy_overview>`_

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

providers/keycloak/docs/index.rst

@@ -44,6 +44,7 @@
     Python API <_api/airflow/providers/keycloak/index>
     Configuration <configurations-ref>
     Keycloak auth manager token API <api-ref/token-api-ref>
+    CLI <cli-refs>
 
 .. toctree::
     :hidden:

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.