AWS auth manager documentation: manage environment section (#38932)

docs/apache-airflow-providers-amazon/auth-manager/manage/index.rst

@@ -18,3 +18,205 @@
 ================================================
 Manage Airflow environment with AWS auth manager
 ================================================
+
+When the AWS auth manager is used, all users and their permissions are no longer managed by
+Airflow itself but by AWS through two different services: AWS IAM Identity Center (users) and Amazon Verified
+Permissions (permissions).
+
+Manage users through AWS IAM Identity Center
+============================================
+
+Users
+-----
+
+All users having access to the Airflow environment must be defined in AWS IAM Identity Center.
+You can use AWS IAM Identity center as identity source or as a proxy between the identity source
+(e.g. Active Directory) and the Airflow environment.
+`See documentation for more details on how to manage your identity source <https://docs.aws.amazon.com/singlesignon/latest/userguide/identities.html>`__.
+
+You can see the list of users defined in AWS IAM Identity Center by following these steps.
+
+1. Open the `IAM Identity Center console <https://console.aws.amazon.com/singlesignon>`_.
+2. Choose **Users**.
+
+Groups
+------
+
+You can use groups in AWS IAM Identity center to group users in logical entities (e.g. by team, by department, ...).
+Later, these groups can be used in Amazon Verified Permissions to assign permissions to a group of users.
+`See documentation to add users to groups <https://docs.aws.amazon.com/singlesignon/latest/userguide/adduserstogroups.html>`__.
+
+You can see the list of groups defined in AWS IAM Identity Center by following these steps.
+
+1. Open the `IAM Identity Center console <https://console.aws.amazon.com/singlesignon>`_.
+2. Choose **Groups**.
+
+Assign users and groups to the Airflow environment
+--------------------------------------------------
+
+.. note::
+  All users and groups defined in AWS IAM Identity Center do not have automatically access to the Airflow environment.
+  You need to manually assign which user can access to Airflow.
+
+To assign users and groups to Airflow, please follow the steps below.
+
+1. Open the `IAM Identity Center console <https://console.aws.amazon.com/singlesignon>`_.
+
+.. note::
+  If you manage users in AWS Managed Microsoft AD, make sure that the IAM Identity Center console is using the AWS
+  Region where your AWS Managed Microsoft AD directory is located before taking the next step.
+
+2. Choose **Applications**.
+3. Choose the **Customer managed** tab.
+4. In the list of applications, choose the application name ``Airflow``.
+5. On the application details page, in the **Assigned users and groups** section, choose **Assign users and groups**.
+6. In the **Assign users or groups** page, select the different users and groups you want to assign to Airflow.
+   You can also search users and groups.
+   You can specify multiple users or groups by selecting the applicable accounts as they appear in search results.
+7. Choose **Assign users**.
+
+Manage user permissions through Amazon Verified Permissions
+===========================================================
+
+AWS auth manager uses Amazon Verified Permissions to define and verify user permissions.
+It uses `Cedar language <https://www.cedarpolicy.com/>`__ to define fine-grained permissions for users.
+AWS auth manager uses one policy store to store all policies related to the Airflow environment.
+To manage these policies, please follow the steps below.
+
+1. Open the `Amazon Verified Permissions console <https://console.aws.amazon.com/verifiedpermissions>`_.
+2. Choose the policy store used by Airflow (by default its description is ``Airflow``).
+3. In the navigation pane on the left, choose **Policies**.
+4. On the **Policies** page, you can see the list of policies. To create a new policy, please follow steps below.
+
+  a. Choose **Create policy**.
+  b. Under **Create policy**, choose **Create static policy**.
+
+Policy format
+-------------
+
+Policies are defined using Cedar language in Amazon Verified Permissions.
+For a complete documentation, `see cedar language website <https://www.cedarpolicy.com/>`__.
+In cedar language, a policy is composed of three elements:
+
+* **Principal**. Who is making the request?
+* **Action**. What operation does the principal want to perform?
+* **Resource**. What does the principal want to perform the action on?
+
+Each of these three elements can have limited values in the context of the Airflow environment.
+You can see the list of principals, actions and resources in the policy store schema by following the steps below.
+
+1. Open the `Amazon Verified Permissions console <https://console.aws.amazon.com/verifiedpermissions>`_.
+2. Choose the policy store used by Airflow (by default its description is ``Airflow``).
+3. In the navigation pane on the left, choose **Schema**.
+
+Example of policies
+-------------------
+
+Here are some example of policies you can define in Amazon Verified Permissions.
+You can use them as-is if they fit exactly your use case.
+You can also modify and/or combine them to create your owned tailor made policies.
+
+Give all permissions to specific user
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ ::
+
+  permit(
+    principal == Airflow::User::"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
+    action,
+    resource
+  );
+
+.. note::
+  You must reference the user by its user ID and not its username or any other attribute.
+  You can find the user ID in AWS IAM Identity Center.
+
+
+Give all permissions to a group of users
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ ::
+
+  permit(
+    principal in Airflow::Group::"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
+    action,
+    resource
+  );
+
+.. note::
+  You must reference the group by its group ID and not its name. You can find the group ID in AWS IAM Identity Center.
+
+Give read-only permissions to a group of users
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ ::
+
+  permit(
+    principal in Airflow::Group::"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
+    action in [
+      Airflow::Action::"Configuration.GET",
+      Airflow::Action::"Connection.GET",
+      Airflow::Action::"Custom.GET",
+      Airflow::Action::"Dag.PUT",
+      Airflow::Action::"Dag.GET",
+      Airflow::Action::"Menu.MENU",
+      Airflow::Action::"Pool.GET",
+      Airflow::Action::"Variable.GET",
+      Airflow::Action::"Dataset.GET",
+      Airflow::Action::"View.GET"
+    ],
+    resource
+  );
+
+Give DAG specific permissions to a group of users
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The policy below gives all DAG related permissions of the DAG ``test`` to a group of users.
+
+ ::
+
+  permit(
+    principal in Airflow::Group::"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
+    action,
+    resource == Airflow::Dag::"test"
+  );
+
+The policy below gives all DAG related permissions of the DAGs ``financial-1`` and ``financial-2`` to a group of users.
+
+ ::
+
+  permit(
+    principal in Airflow::Group::"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
+    action,
+    resource in [Airflow::Dag::"financial-1", Airflow::Dag::"financial-2"]
+  );
+
+The policy below gives access to logs of the DAG ``test`` to a group of users.
+
+ ::
+
+  permit(
+    principal in Airflow::Group::"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
+    action,
+    resource == Airflow::Dag::"test"
+  ) when {
+    context has dag_entity && context.dag_entity == "TASK_LOGS"
+  };
+
+Forbid specific action to specific user
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+All policies defined in Amazon Verified Permissions are taken into account when doing an authorization check.
+For example, if both one **permit** and one **forbid** policies match the request, the access will be denied to the user.
+This can be useful if, for example, you want to restrict access to a specific user who belongs to a group that is
+granted all permissions.
+
+The policy below removes access of DAGs ``secret-dag-1`` and ``secret-dag-2`` from a specific user.
+
+ ::
+
+  forbid(
+    principal == Airflow::User::"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
+    action,
+    resource in [Airflow::Dag::"secret-dag-1", Airflow::Dag::"secret-dag-2"]
+  );

docs/apache-airflow-providers-amazon/auth-manager/setup/amazon-verified-permissions.rst

@@ -97,7 +97,7 @@ Manually
 Please follow the instructions below to update the Amazon Verified Permissions policy store schema to its latest version.
 
 1. Open the `Amazon Verified Permissions console <https://console.aws.amazon.com/verifiedpermissions>`_.
-2. Choose the policy store used by Airflow (by default, its description is ``Airflow``).
+2. Choose the policy store used by Airflow (by default its description is ``Airflow``).
 3. In the navigation pane on the left, choose **Schema**.
 4. Choose **Edit schema** and then choose **JSON mode**.
 5. Enter the content of `the latest schema version <https://github.com/apache/airflow/blob/main/airflow/providers/amazon/aws/auth_manager/avp/schema.json>`_

docs/apache-airflow-providers-amazon/auth-manager/setup/identity-center.rst

@@ -112,7 +112,7 @@ Once the application is created, you need to configure the attribute mappings.
 2. Choose **Actions**.
 3. Under **Actions**, choose **Edit attribute mappings**.
 4. On the **Attribute mappings** page, you need to configure the different attribute mappings between your identity
-   provider and AWS IAM Identity Center. For more information on attribute mappings, see the
+   source and AWS IAM Identity Center. For more information on attribute mappings, see the
    `IAM Identity Center documentation <https://docs.aws.amazon.com/singlesignon/latest/userguide/attributemappingsconcept.html>`_.
    The AWS auth manager needs two attributes: **id** and **groups**.
    If you use the default Identity Center directory as identity source, you can use the configuration below: