Merge pull request #1863 from ThumulaPerera/update-authz-docs

Update authz docs

Author: ThumulaPerera

en/developer-docs/docs/administer/control-access-in-the-choreo-console.md renamed to en/developer-docs/docs/administer/configure-access-control.md

@@ -1,49 +1,19 @@
-# Control Access in the Choreo Console
+# Configure Access Control
 
-In the Choreo Console, you have the ability to manage access to projects and the actions that can be performed within them. Administrators have the capability to restrict project access to specific user groups. This feature is useful when you need certain user groups to have access to particular projects or for a set of projects.
+Before configuring access control in Choreo, review the [Access Control Concepts](../choreo-concepts/access-control.md).
 
-Choreo uses **Roles**, **Groups**, and a **Mapping level** to control access to the Choreo Console as follows:
+Now, let’s walk through a sample scenario for granting access to a specific environment within a project.
 
-- **Role** : Role is a collection of permissions. Choreo has a predefined set of roles with permissions assigned to them. [Learn more](../choreo-concepts/organization.md#roles)
-- **Group** : Group is a collection of users. A user group requires a role or multiple roles to be assigned to it so that the users in those groups get the relevant permissions via the assigned roles. [Learn more](../choreo-concepts/organization.md#groups)
-
-- **Mapping level** : A mapping level defines the extent at which a role-group mapping can be done. Choreo has two defined resource levels.
-    - **Organization** : You can assign a role to a group or associate a group with a role within the organization. This ensures that
-                         all users in a group inherit the permissions granted by that role across all organizational resources.
-                         For example, if a user has edit_project permission at the organization mapping level, that user can edit all the projects in the organization.
-    - **Project** : You can assign a role to a group or associate a group with a role within a specific project resource. This ensures
-                    that users in the group inherit the permissions granted by that role only within the context of the specified project.
-                    For example, If a user has edit_project permission at the project mapping level, that user can only edit the specified project.
-
-
-In Choreo, authorization operates by assigning a role to a group at a specified level. The level at which the role is assigned determines the extent of permissions granted to users.
-
-!!! warning "Important"
-    Avoid assigning multiple roles to a single user across different projects or levels (organization and project). Such assignments can grant users unintended permission to some projects, allowing them to perform tasks they shouldn't have access to. Therefore, it is recommended to assign only one role to a user across projects or levels to ensure proper access control.
-
-!!! info
-    In Choreo, organization-level permissions take precedence over project-level permissions.
-
-To elaborate further, refer to the following diagram.
-
-The following diagram depicts a role-group assignment at a specific resource level. In the diagram, an admin user has assigned the Developer role to all members of the Engineering group within the Engineering Project. This grants users in the Engineering group the ability to perform all actions allowed by the Developer role within the Engineering Project.
-
-![Console access control](../assets/img/administer/access-control-to-console.png)
-
-## Sample scenario
-
-Now that you understand the basic concepts of access control within the Choreo Console, let’s try out a sample scenario to manage access within a project.
-
-Assume you are overseeing the Engineering Project within your organization and you need to grant development access to specific users solely within this project. Here's a step-by-step guide on how to achieve this:
+Assume you are overseeing the Engineering Project within your organization and you need to grant development access to specific users solely within this project. As they are developers, you further need to restrict their access to the Development environment of the project. Here's a step-by-step guide on how to achieve this:
 
 ### Step 1: Create a project
 
 Follow the steps given below to create a project:
 
-1. Go to the [Choreo Console](https://console.choreo.dev/) and sign in. This opens the organization home page.
+1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the organization home page.
 2. On the organization home page, click **+ Create Project**.
 3. Enter a display name, unique name, and description for the project. You can enter the values given below:
-
+    
     !!! info
          In the **Name** field, you must specify a name to uniquely identify your project in various contexts. The value is editable only at the time you create the project. You cannot change the name after you create the project.
 
@@ -80,21 +50,21 @@ Follow the steps given below to assign the **Developer** role to the **Engineeri
 2. In the left navigation menu, click **Settings**.
 3. Click the **Access Control** tab and then click the **Groups** tab.
 4. On the **Groups** tab, search for the **Engineering Project Developer** group and click the corresponding edit icon.
-5. Click **+Add Roles**.
-6. In the **Add Roles to Group in Project** dialog that opens, click the **Roles** list and select **Developer**.
-7. Click **Add**. This assigns the **Developer** role to the group. You should see the mapping level as **Project (Engineering Project)** as follows, indicating the scope of the mapping:
-
-    ![Mapping level](../assets/img/administer/mapping-level.png)
+5. Click **+Assign Roles**. 
+6. In the **Assign Roles to Group in Project** dialog that opens, click the **Roles** list and select **Developer**.
+7. Click **Selected Environments** radio button under **Applicable Environments**
+8. Select **Development** environment from the environment selecction dropdown 
+7. Click **Assign**. This assigns the **Developer** role to the group. You should see the mapping level as **Project (Engineering Project)** and Applicable Environment as **Development** indicating the type of the asssignment:
 
-   This means that you have granted developer access to users in the Engineering Project Developer group in the scope of the Engineering Project.
+   This means that you have granted developer access to users in the Engineering Project Developer group in the scope of the Development environment of the Engineering Project.
 
 Now that you have set up access control, you can proceed to add users to the new group.
 
 ### Step 4: Add users to the group
 
 There are two approaches you can follow to add users to the group.
 
-#### Add a new user as a project developer
+#### Add a new user as a project developer 
 
 Follow the steps given below to add a new user as a project developer:
 
@@ -107,7 +77,7 @@ Follow the steps given below to add a new user as a project developer:
    2. Click the **Groups** list and select **Engineering Project Developer**.
 6. Click **Invite**.
 
-#### Add an existing user as a project developer
+#### Add an existing user as a project developer 
 
 Follow the steps given below to add an existing user as a project developer:
 

en/developer-docs/docs/administer/inviting-members.md

@@ -2,8 +2,10 @@
 
 An organization in Choreo is a logical grouping of users and user resources. A first-time user must create an organization and be a user of it when signing in to Choreo. Users and resources in an organization cannot access resources in another organization unless an admin of the other organization invites them and adds them as a user of that organization.
 
-{% include "inviting-members.md" %}
+## Inviting users
+
+An organization administrator can invite users to the organization by assigning them specific [groups](../choreo-concepts/access-control.md#group). Invited users receive an invitation via email. An invited user must accept the invitation to join the organization and access the resources of that organization.
 
 ## Manage user permission
 
-For details on how Choreo manages user permission, see [Manage user permission](../choreo-concepts/organization.md#manage-user-permission).
+For details on how Choreo manages user permission, see [Access Control](../choreo-concepts/access-control.md).

en/developer-docs/docs/administer/manage-members-of-an-organization.md

@@ -0,0 +1,131 @@
+# Access Control
+
+With Choreo, administrators can control user access to different projects and environments within the organization. 
+At the finest granularity level, an administrator can restrict a user to perform a specific action on a specific project and a specific environment.
+
+## Fundamental Question in Access Control
+
+Access control in any system ultimately comes down to answering the following question.
+
+> *Can this **user** perform this **action** on this **resource**?*
+
+???+ example
+    Can Harry view logs of development environment of engineering project? 
+    
+    - `Harry` is the **user**  
+    - `view logs` is the **action**  
+    - `development environment of engineering project` is the **resource**   
+
+## Permission
+
+In Choreo access control model, a permission is the right to perform a specific action. 
+
+???+ example
+    A user can create a component only if the user has `Create Component` permission.
+
+### Environment Specific Permissions
+
+In Choreo, actions such as `deploy component`, `promote component`, `create configuration groups`, and `view logs` must be performed within the context of an environment. The permissions which give the right to perform such actions are categorized as **Environment Specific** permissions.
+
+!!! note
+    For actions tied to an environment, it is sometimes necessary to allow a user to perform the action in certain environments but not in others; for example, a developer may be allowed to view logs in the development environment but not in the production environment.
+
+## Role
+
+Assigning permissions individually to each user is a time-consuming and error prone task. Users with similar job responsibilities often need the same set of permissions, which is why **roles** exist. A role is a collection of permissions designed to reflect real-world job responsibilities.
+
+Roles simplify permission management. For example, instead of assigning 20 permissions to each of 50 developers (1000 assignments), you can assign the 20 permissions to a Developer role and then assign that role to each developer (20 + 50 assignments).  
+
+!!! info
+    Each organization in Choreo comes with a set of predefined roles with default permissions. Organization administrators can customize these roles or create new ones as needed.
+
+## Group 
+
+A group is a collection of users, usually organized by team or department.
+
+Instead of assigning a role to each user, you assign the role to the group. Every user in the group automatically gets the group’s permissions. This makes updates easier. For example, instead of removing 50 role-to-user assignments and creating 50 new ones, you only need to remove one role-to-group assignment and add one new assignment.
+
+!!! info
+    Each organization in Choreo comes with a set of predefined groups. By default, each group is mapped to a role with the same name. Organization administrators can customize these groups or create new ones as needed.
+
+## Permission to Role Assignment
+
+In Choreo, all permission-to-role assignments apply across the organization. You can’t restrict these assignments to specific resources. For example, you can’t configure Choreo to grant the `View Logs` permission to the `Developer` role only in the Development environment of the Engineering project.
+
+## Role to Group Assignment
+
+The real strength of Choreo Access Control comes from role-to-group assignments. These assignments can include resource-specific restrictions. For example, you can assign the `Developer` role to the `Engineering Project Developer` group, but limit it to the Development environment of the Engineering project.
+
+Each role-to-group assignment has two attributes:
+
+1. **Mapping Level** : Defines whether the assignment applies to the entire `Organization` or only to a specific `Project`.
+2. **Applicable Environment** : Defines whether the assignment applies to `All` environments or only to a specific `Environment`.
+
+By combining these attributes, you can create four types of assignments.
+
+|Assignment Type|Mapping Level|Appicable Environment|
+|-|-|-|
+|`Organization Scoped`|Organization|All|
+|`Project Scoped`|Project|All|
+|`Environement Scoped`|Organization|Environment|
+|`Project-Environment Scoped`|Project|Environment|
+
+!!! warning "Important"
+    Avoid assigning multiple roles to the same group across different projects or mapping levels (organization and project). Doing so can give users unintended permissions in some projects, allowing access to tasks they shouldn’t perform. To ensure proper access control, assign only one role to a group across projects or mapping levels.
+
+## Extent of Access granted through different Role to Group assignment types
+
+Recall the [Fundamental Question in Access Control](#fundamental-question-in-access-control). 
+
+> *Can this **user** perform this **action** on this **resource**?*
+
+Based on this question, the extent of access has two parts.
+
+1. Allowed **actions**
+
+2. Allowed **resources** (the resources on which those actions can be performed)
+
+Next, let’s go through each role-to-group assignment type to see the extent of access it grants. We’ll look at both the allowed **actions** and the allowed **resources**. 
+
+### Organization Scoped Assignments
+
+- Actions permitted by the role are allowed on resources within the organization. 
+- All other actions are not allowed.
+
+!!! note
+    Actions permitted by a role are the actions linked to the permissions assigned to the role.
+
+### Project Scoped Assignments
+
+- Actions permitted by the role are allowed on resources within the specific project. 
+- All other actions are not allowed.
+
+### Environement Scoped Assignments
+
+- Environment specific actions permitted by the role are allowed on resources within the specific environment of the organization.
+- Other actions permitted by the role are allowed on resources within the organization.
+- All other actions are not allowed.
+
+!!! note
+    **Environment specific actions** permitted by a role are the actions linked to the [**environment specific permissions**](#environment-specific-permissions) assigned to the role.
+
+For environement scoped assignments, allowing **non environment specific** actions on resources across organization is intentional. This design aligns with real world Access Control use cases. 
+
+!!! example
+    Suppose you assign the Developer role to the Engineering Developer group, but only for the Development environment of the Engineering project. The purpose of this assignment is not to prevent developers from performing actions like `build component`, which don’t depend on a specific environment. Instead, the goal is to restrict developers from performing actions such as `promote component` on environments they aren’t authorized to access, like Production.
+
+!!! warning "Important"
+    Exercise care when creating environment scoped role-to-group assignments. Only environment specific actions are restricted to that environment; all other actions remain allowed on resources across the organization.
+
+### Project-Environment Scoped Assignments
+
+- Environment Specific actions permitted by the role are allowed on resources within the specific Environment of the specific Project.
+- Other actions permitted by the role are allowed on resources within the specific Project.
+- All other actions are not allowed.
+
+Similar to previous case, allowing **non environment specific** actions on resources across project is intentional. This design aligns with real world Access Control use cases.
+
+!!! warning "Important"
+    Exercise care when creating project-environment scoped role-to-group assignments. Only environment specific actions are restricted to that environment; all other actions remain allowed on resources across the project.
+
+Now that you understand the access control concepts in Choreo, see [Configure Access Control](../administer/configure-access-control.md) for a walkthrough on how to set it up.

en/developer-docs/docs/assets/img/administer/access-control-to-console.png

@@ -6,44 +6,13 @@ An organization in Choreo is a logical grouping of users and user resources. A f
 
 If you are a member of more than one organization, you can switch from one organization to another when necessary. To do this, select the required organization from the **Organization** list in the Choreo Console header.
 
-{% include "../administer/inviting-members.md" %}
+## Inviting users
 
-## Manage user permission
-
-Choreo manages user permissions with groups and roles.
-
-### Groups
-
-A group in Choreo is a collection of users, each with one or more roles assigned to them. Users within a group inherit the permissions associated with the roles assigned to that group. For instance, if a user is added to the `API Publisher` group, they will automatically receive the `API Publisher` role.
-
-Choreo comes with predefined groups already configured with specific roles, as follows:
+An organization administrator can invite users to the organization by assigning them specific [groups](../choreo-concepts/access-control.md#group). Invited users receive an invitation via email. An invited user must accept the invitation to join the organization and access the resources of that organization.
 
-- **API Publisher**: A collection of users who have the API Publisher role.
-- **API Subscriber**: A collection of users who have the API Subscriber role.
-- **Admin** : A collection of users who have the Admin role.
-- **Billing Admin** : A collection of users who have the Billing Admin role.
-- **Choreo DevOps** : A collection of users who have the Choreo DevOps role.
-- **Developer** : Users who develop, deploy, and manage cloud native applications at scale.
-- **External API Subscriber**: A collection of users who have the External API Subscriber role.
-
-When creating a new group to invite members, be sure to assign a role to the group to ensure users have the required permissions.
-
-### Roles
-
-Choreo roles are defined as follows:
-
-- **Admin**: Performs all administrative tasks including user management, Developer Portal customization, project management, analytics configuration, and domain management.
-- **API Publisher**: Discovers, creates, publishes, deletes, tests, and manages APIs.
-- **API Subscriber**: Subscribes to APIs, manages subscriptions and applications, and generates and manages API keys.
-- **Billing Admin**: Handles billing administration including viewing tiers, managing organizations and invoices, and managing subscriptions and payment methods.
-- **Choreo DevOps**:   Manages deployment, monitoring, and reliability of components in Choreo.
-- **Choreo Platform Engineer**: Performs infrastructure, governance, service mesh, and monitoring tasks.
-- **Developer**: Develops, deploys, and manages cloud-native applications at scale.
-- **External API Subscriber**: Consumes APIs with Developer Portal access and can join an organization exclusively for API usage.
-- **Environment Manager (Deprecated):** Previously responsible for managing deployment environments.
-- **Viewer**: Views and monitors applications, APIs, and environments without making changes.
+## Manage user permission
 
-_Note: The **Choreo DevOps** role has been replaced with the **Choreo Platform Engineer** role. However, organizations that previously had Choreo DevOps role will continue to see and use both roles with their existing functionality._
+For details on how Choreo manages user permission, see [Access Control](access-control.md).
 
 ## Organization ID