From 42fdc48251f66dcbdd9ac7ffe4b66b7742deef91 Mon Sep 17 00:00:00 2001 From: viniciusdc Date: Tue, 24 Sep 2024 15:39:40 -0300 Subject: [PATCH 1/3] create custom docs page for keycloak groups --- docs/docs/how-tos/configure-keycloak-howto.md | 51 ---- docs/docs/how-tos/group-directory-creation.md | 238 ++++++++++++++++++ 2 files changed, 238 insertions(+), 51 deletions(-) create mode 100644 docs/docs/how-tos/group-directory-creation.md diff --git a/docs/docs/how-tos/configure-keycloak-howto.md b/docs/docs/how-tos/configure-keycloak-howto.md index 16d039f75..4b67748b7 100644 --- a/docs/docs/how-tos/configure-keycloak-howto.md +++ b/docs/docs/how-tos/configure-keycloak-howto.md @@ -132,57 +132,6 @@ Your new user can now log in to Nebari, visit your provided Nebari domain URI wh ![Nebari - Log in to Keycloak page](/img/how-tos/nebari_login_screen.png) -## In-depth look at Roles and Groups - -Groups represent a collection of users that perform similar actions and therefore require similar permissions. By default, Nebari is deployed with the following groups: `admin`, `developer`, and `analyst` (in roughly descending order of permissions and scope). - -:::info -Users in a particular group will also get access to that groups shared folder. So if `user A` belongs to the `developer`, they will also have access to the `~/shared/developer` folder. This also applies to new groups that you create. -::: - -Roles on the other hand represent the type or category of user. This includes access and permissions that this category of user will need to perform their regular job duties. The differences between `groups` and `roles` are subtle. Particular roles (one or many), like `conda_store_admin`, are associated with a particular group, such as `admin` and any user in this group will then assume the role of `conda_store_admin`. - -:::info -These roles can be stacked. This means that if a user is in one group with role `conda_store_admin` and another group with role `conda_store_viewer`, this user ultimately has the role `conda_store_admin`. -::: - -| Group | Access to Nebari Resources | Roles | Permissions Description | -| ------------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `analyst` | | | | -| `developer` | | | | -| `admin` | | | | -| `superadmin` | | | | - -:::info -Check [Conda-store authorization model](https://conda-store.readthedocs.io/en/latest/contributing.html#authorization-model) for more details on conda-store authorization. -::: - -:::caution -The role `jupyterhub_admin` gives users elevated permissions to JupyterHub and should be applied judiciously. As mentioned in the table above, a JupyterHub admin is able to impersonate other users and view the contents of their home folder. For more details, read through the [JupyterHub documentation](https://z2jh.jupyter.org/en/stable/jupyterhub/customizing/user-management.html#admin-users). -::: - -To create new groups or modify (or delete) existing groups, log in as `root` and click **Groups** on the left-hand side. - -As an example, we create a new group named `conda-store-manager`. This group will have administrator access to the [Conda-Store service]. - -1. Click **New** in the upper-right hand corner under **Groups**. - -![Keycloak groups tab screenshot - user groups view](/img/how-tos/keycloak_groups.png) - -- Then, give the new group an appropriate name. - -![Keycloak add group form - name field set to conda-store-manager](/img/how-tos/keycloak_new_group1.png) - -2. Under **Role Mapping**, add the appropriate **Client Roles** as needed; there should be no need to update the **Realm Roles**. - -![Keycloak group conda-store-manager form - role mappings tab focused with expanded client roles dropdown](/img/how-tos/keycloak_new_group2.png) - -In this example, the new group only has one mapped role, `conda_store_admin`; however, it's possible to attach multiple **Client Roles** to a single group. - -![Keycloak group conda-store-manager form - role mappings tab focused ](/img/how-tos/keycloak_new_group3.png) - -Once complete, return to the **Users** section in the dashboard and add the relevant users to this newly created group. - [keycloak-login]: /docs/tutorials/login-keycloak diff --git a/docs/docs/how-tos/group-directory-creation.md b/docs/docs/how-tos/group-directory-creation.md new file mode 100644 index 000000000..792d39515 --- /dev/null +++ b/docs/docs/how-tos/group-directory-creation.md @@ -0,0 +1,238 @@ +--- +id: group-directory-creation +title: Creating and Managing Groups and Directories +description: How to configure Keycloak's and JupyterHub's groups and directories. +--- + +Groups are a fundamental and vital part of the Nebari ecosystem. They are used to manage access to a wide range of services within Nebari, including JupyterHub instances, Keycloak realms, Conda environments, and computing resources. By grouping users based on roles, projects, or departments, Nebari simplifies the management of permissions and resource sharing. + +Beyond managing access, groups play a crucial role in organizing and sharing data across the JupyterHub ecosystem. Each group can have its own shared directory within JupyterHub, allowing users within the same group to collaborate seamlessly by sharing files and resources. This facilitates team collaboration and ensures that data is organized and accessible to those who need it. + +In this document, we will cover: + +- How to create and manage groups and subgroups in Keycloak +- How to assign roles and permissions to groups +- How groups and roles interact within Nebari's services, such as JupyterHub and Conda-Store +- How to manage group directories in JupyterHub + +## Managing Groups in Keycloak + +Keycloak is the identity and access management service used in Nebari. It allows you to create and manage users, groups, roles, and permissions. Groups in Keycloak are collections of users, and they can be assigned specific roles that grant permissions to access various services within Nebari. + +For detailed information on managing groups in Keycloak, refer to the [Keycloak documentation on Group Management](https://www.keycloak.org/docs/latest/server_admin/#_group_management). + +Below we outline the steps specific to Nebari. + +### Creating a New Group + +To create a new group in Keycloak: + +1. **Log in to Keycloak** as an administrator (usually the `root` user). +2. **Navigate to Groups**: Click on **Groups** in the left-hand menu. +3. **Create the Group**: Click the **New** button, enter an appropriate name for your new group (e.g., `conda-store-manager`), and save. + +If you wish to organize your groups hierarchically, you can create subgroups by selecting a parent group and adding a subgroup. + +### Assigning Roles to a Group + +Roles define the permissions and access levels granted to a group. In Nebari, assigning specific roles to groups ensures that users within the group inherit those permissions. + +To assign roles to a group: + +1. **Select the Group**: Navigate to the group you wish to assign roles to. +2. **Go to Role Mappings**: Click on the **Role Mappings** tab. +3. **Assign Client Roles**: + - Under **Client Roles**, select the client application (e.g., `jupyterhub`, `conda-store`). + - From the available roles, select the ones you wish to assign and click **Add selected**. + +**Note:** Nebari-specific roles include `conda_store_admin`, `allow-group-directory-creation-role`, among others. + +For more details on role mappings, see the [Keycloak documentation on Role Mappings](https://www.keycloak.org/docs/latest/server_admin/#role-mappings). + +### Adding Users to a Group + +To add users to a group: + +1. **Navigate to Users**: Click on **Users** in the left-hand menu. +2. **Select a User**: Choose the user you want to add to a group. +3. **Assign to Group**: + - Click on the **Groups** tab within the user's details. + - Click the **Join** button. + - Select the group (and subgroup, if applicable) you wish to add the user to. + - Click **Join** to add the user to the group. + +Repeat this process for all users who should be part of the group. + +### Managing Subgroups + +Subgroups allow you to create a hierarchical structure of groups, representing organizational units, projects, or teams. Subgroups inherit roles and attributes from their parent groups unless explicitly overridden. + +To manage subgroups: + +- **Creating Subgroups**: Select the parent group, navigate to the **Sub Groups** tab, and create a new subgroup. +- **Assigning Roles to Subgroups**: Roles are not automatically inherited; assign roles to subgroups as needed. +- **Use Cases**: Organize groups hierarchically to reflect organizational structures. + +For more information, see the [Keycloak documentation on Group Hierarchies](https://www.keycloak.org/docs/latest/server_admin/#group-hierarchies). + +## Managing Group Directories in JupyterHub + +:::note Important +As of version `2024.9.1`, JupyterHub creates and mounts directories only for groups with the `allow-group-directory-creation-role`. By default, this includes the `admin`, `analyst`, and `developer` groups. Previously, directories were automatically created for all Keycloak groups. This change gives administrators more control over shared directories and overall access management without cluttering the file system. +::: + +### Understanding Group Directories + +A group directory in JupyterHub is a shared folder accessible to all members of a specific group. It provides a shared space within the file system for collaboration. + +An example directory structure: + +```yaml +/shared +├── admin +│ ├── file1.txt +│ └── file2.txt +├── analyst +│ ├── file1.txt +│ └── file2.txt +└── developer + ├── file1.txt + └── file2.txt +``` + +### Assigning the `allow-group-directory-creation-role` to a Group + +To enable directory creation and mounting for a group in JupyterHub, assign the `allow-group-directory-creation-role` to the group in Keycloak. + +#### Steps to Assign the Role: + +1. **Navigate to the Group**: Log in to Keycloak as an administrator and select the group. +2. **Go to Role Mappings**: Click on the **Role Mappings** tab. +3. **Assign the Role**: + - Under **Client Roles**, select the `jupyterhub` client. + - Select `allow-group-directory-creation-role` and click **Add selected**. + +Users in this group will now have access to the group's shared directory in JupyterHub. + +### Rolling Back the Change + +To remove the group's directory access: + +1. **Navigate to the Group's Role Mappings**: Select the group and go to the **Role Mappings** tab. +2. **Remove the Role**: + - Under **Assigned Roles**, select `allow-group-directory-creation-role`. + - Click **Remove selected**. + +**Data Preservation:** No data is deleted when you remove the role; the directory is simply unmounted from users' JupyterLab sessions. + +### Managing Subgroup Directories + +Subgroups can have their own directories in JupyterHub if assigned the `allow-group-directory-creation-role`. Assign the role to subgroups as needed to control access and collaboration. + +## In-Depth Look at Roles and Groups + +Understanding how roles and groups work together is essential for effectively managing access and permissions within Nebari. + +### Groups + +Groups represent collections of users who perform similar functions or belong to the same organizational unit. They simplify user management by allowing you to assign roles and permissions at the group level rather than individually to each user. + +By default, Nebari is deployed with the following groups: + +- **admin**: Users with administrative privileges who can manage the system, configurations, and users. +- **developer**: Users who need access to development tools and environments. +- **analyst**: Users who primarily analyze data and may have restricted access compared to developers. + +Groups can be organized hierarchically using subgroups, allowing for more granular control and reflecting organizational structures. + +:::info +**Shared Directories:** Users in a particular group will have access to that group's shared directory in JupyterHub if the group has the `allow-group-directory-creation-role` assigned. +::: + +### Roles + +Roles define a set of permissions that grant access to specific resources or capabilities within Nebari's services. They are assigned to groups or users and determine what actions they can perform. + +Roles can be of two types: + +- **Realm Roles**: Apply globally across all clients (applications) in Keycloak. +- **Client Roles**: Specific to a client (application), such as `jupyterhub`, `conda-store`, or `grafana`. + +Examples of roles include: + +- `admin`: Grants administrative privileges within a client. +- `developer`: Grants development-related permissions. +- `conda_store_admin`: Allows managing Conda environments in Conda-Store. + +### Interaction Between Roles and Groups + +Roles are assigned to groups, and users inherit those roles through their group memberships. This means that: + +- **Users in a Group Get the Group's Roles**: If a group has certain roles assigned, all users in that group will inherit those roles. +- **Multiple Roles Can Be Assigned**: A group can have multiple roles from different clients, providing access to various services. +- **Roles Are Not Inherited by Subgroups**: Roles need to be explicitly assigned to subgroups if you want them to have specific permissions. + +### Role Hierarchies and Stacking + +Roles can be designed to reflect hierarchical permissions. For example, an `admin` role may encompass all the permissions of a `developer` role. + +:::info +**Role Stacking:** If a user is a member of multiple groups with different roles, they effectively have the combined permissions of all assigned roles. For instance, if a user is in a group with the `conda_store_admin` role and another group with the `conda_store_viewer` role, the user will have administrative privileges in Conda-Store due to the higher permission level of `conda_store_admin`. +::: + +### Assigning Roles to Groups + +When creating or editing a group in Keycloak: + +1. **Select the Group**: Navigate to the group you wish to assign roles to. +2. **Go to Role Mappings**: Click on the **Role Mappings** tab. +3. **Assign Roles**: + - Under **Client Roles**, select the client application. + - Select the roles you wish to assign and click **Add selected**. + +## Access Levels and Permissions + +Roles on the other hand represent the type or category of user. This includes access and permissions that this category of user will need to perform their regular job duties. The differences between `groups` and `roles` are subtle. Particular roles (one or many), like `conda_store_admin`, are associated with a particular group, such as `admin` and any user in this group will then assume the role of `conda_store_admin`. + +:::info +These roles can be stacked. This means that if a user is in one group with role `conda_store_admin` and another group with role `conda_store_viewer`, this user ultimately has the role `conda_store_admin`. +::: + +Below is a summary of default groups, their access to Nebari resources, assigned roles, and permissions descriptions. + +| Group | Access to Nebari Resources | Roles | Permissions Description | +| ------------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `analyst` | | | | +| `developer` | | | | +| `admin` | | | | +| `superadmin` | | | | + +:::info +Check [Conda-store authorization model](https://conda-store.readthedocs.io/en/latest/contributing.html#authorization-model) for more details on conda-store authorization. +::: + +:::caution +The role `jupyterhub_admin` gives users elevated permissions to JupyterHub and should be applied judiciously. As mentioned in the table above, a JupyterHub admin is able to impersonate other users and view the contents of their home folder. For more details, read through the [JupyterHub documentation](https://z2jh.jupyter.org/en/stable/jupyterhub/customizing/user-management.html#admin-users). +::: + +To create new groups or modify (or delete) existing groups, log in as `root` and click **Groups** on the left-hand side. + +As an example, we create a new group named `conda-store-manager`. This group will have administrator access to the [Conda-Store service]. + +1. Click **New** in the upper-right hand corner under **Groups**. + +![Keycloak groups tab screenshot - user groups view](/img/how-tos/keycloak_groups.png) + +- Then, give the new group an appropriate name. + +![Keycloak add group form - name field set to conda-store-manager](/img/how-tos/keycloak_new_group1.png) + +2. Under **Role Mapping**, add the appropriate **Client Roles** as needed; there should be no need to update the **Realm Roles**. + +![Keycloak group conda-store-manager form - role mappings tab focused with expanded client roles dropdown](/img/how-tos/keycloak_new_group2.png) + +In this example, the new group only has one mapped role, `conda_store_admin`; however, it's possible to attach multiple **Client Roles** to a single group. + +![Keycloak group conda-store-manager form - role mappings tab focused ](/img/how-tos/keycloak_new_group3.png) + +Once complete, return to the **Users** section in the dashboard and add the relevant users to this newly created group. From b7248347fbc37ad1ca14e3ff22f306d40c609a97 Mon Sep 17 00:00:00 2001 From: viniciusdc Date: Tue, 24 Sep 2024 19:23:13 -0300 Subject: [PATCH 2/3] replace keycloak role/groups docs --- docs/docs/how-tos/fine-grained-permissions.md | 223 ++++++++++++++++ docs/docs/how-tos/group-directory-creation.md | 238 ------------------ 2 files changed, 223 insertions(+), 238 deletions(-) delete mode 100644 docs/docs/how-tos/group-directory-creation.md diff --git a/docs/docs/how-tos/fine-grained-permissions.md b/docs/docs/how-tos/fine-grained-permissions.md index f682acb22..554b865db 100644 --- a/docs/docs/how-tos/fine-grained-permissions.md +++ b/docs/docs/how-tos/fine-grained-permissions.md @@ -1,3 +1,38 @@ +--- +id: group-directory-creation +title: Creating and Managing Groups and Directories +description: How to configure Keycloak's and JupyterHub's groups and directories. +--- + +Groups are a fundamental and vital part of the Nebari ecosystem. They are used to manage access to a wide range of services within Nebari, including JupyterHub instances, Keycloak realms, Conda environments, and computing resources. By grouping users based on roles, projects, or departments, Nebari simplifies the management of permissions and resource sharing. + +Beyond managing access, groups play a crucial role in organizing and sharing data across the JupyterHub ecosystem. Each group can have its own shared directory within JupyterHub, allowing users within the same group to collaborate seamlessly by sharing files and resources. This facilitates team collaboration and ensures that data is organized and accessible to those who need it. + +In this document, we will cover: + +- How to create and manage groups and subgroups in Keycloak +- How to assign roles and permissions to groups +- How groups and roles interact within Nebari's services, such as JupyterHub and Conda-Store +- How to manage group directories in JupyterHub + +## Managing Groups in Keycloak + +Keycloak is the identity and access management service used in Nebari. It allows you to create and manage users, groups, roles, and permissions. Groups in Keycloak are collections of users, and they can be assigned specific roles that grant permissions to access various services within Nebari. + +For detailed information on managing groups in Keycloak, refer to the [Keycloak documentation on Group Management](https://www.keycloak.org/docs/latest/server_admin/#_group_management). + +Below we outline the steps specific to Nebari. + +### Creating a New Group + +To create a new group in Keycloak: + +1. **Log in to Keycloak** as an administrator (usually the `root` user). +2. **Navigate to Groups**: Click on **Groups** in the left-hand menu. +3. **Create the Group**: Click the **New** button, enter an appropriate name for your new group (e.g., `conda-store-manager`), and save. + +If you wish to organize your groups hierarchically, you can create subgroups by selecting a parent group and adding a subgroup. + # Fine Grained Permissions via Keycloak Nebari provides its users (particularly admins) a way to manage roles and permissions to @@ -83,6 +118,194 @@ for the roles to take in effect. For example let's say we add a set of roles for conda-store again (similarly for `jupyterhub` as well), after the roles are granted/revoked. ::: +### Adding Users to a Group + +To add users to a group: + +1. **Navigate to Users**: Click on **Users** in the left-hand menu. +2. **Select a User**: Choose the user you want to add to a group. +3. **Assign to Group**: + - Click on the **Groups** tab within the user's details. + - Click the **Join** button. + - Select the group (and subgroup, if applicable) you wish to add the user to. + - Click **Join** to add the user to the group. + +Repeat this process for all users who should be part of the group. + +### Managing Subgroups + +Subgroups allow you to create a hierarchical structure of groups, representing organizational units, projects, or teams. Subgroups inherit roles and attributes from their parent groups unless explicitly overridden. + +To manage subgroups: + +- **Creating Subgroups**: Select the parent group, navigate to the **Sub Groups** tab, and create a new subgroup. +- **Assigning Roles to Subgroups**: Roles are not automatically inherited; assign roles to subgroups as needed. +- **Use Cases**: Organize groups hierarchically to reflect organizational structures. + +For more information, see the [Keycloak documentation on Group Hierarchies](https://www.keycloak.org/docs/latest/server_admin/#group-hierarchies). + +## Managing Group Directories in JupyterHub + +:::note Important +As of version `2024.9.1`, JupyterHub creates and mounts directories only for groups with the `allow-group-directory-creation-role`. By default, this includes the `admin`, `analyst`, and `developer` groups. Previously, directories were automatically created for all Keycloak groups. This change gives administrators more control over shared directories and overall access management without cluttering the file system. +::: + +### Understanding Group Directories + +A group directory in JupyterHub is a shared folder accessible to all members of a specific group. It provides a shared space within the file system for collaboration. + +An example directory structure: + +```yaml +/shared +├── admin +│ ├── file1.txt +│ └── file2.txt +├── analyst +│ ├── file1.txt +│ └── file2.txt +└── developer + ├── file1.txt + └── file2.txt +``` + +### Assigning the `allow-group-directory-creation-role` to a Group + +To enable directory creation and mounting for a group in JupyterHub, assign the `allow-group-directory-creation-role` to the group in Keycloak. + +#### Steps to Assign the Role: + +1. **Navigate to the Group**: Log in to Keycloak as an administrator and select the group. +2. **Go to Role Mappings**: Click on the **Role Mappings** tab. +3. **Assign the Role**: + - Under **Client Roles**, select the `jupyterhub` client. + - Select `allow-group-directory-creation-role` and click **Add selected**. + +Users in this group will now have access to the group's shared directory in JupyterHub. + +### Rolling Back the Change + +To remove the group's directory access: + +1. **Navigate to the Group's Role Mappings**: Select the group and go to the **Role Mappings** tab. +2. **Remove the Role**: + - Under **Assigned Roles**, select `allow-group-directory-creation-role`. + - Click **Remove selected**. + +**Data Preservation:** No data is deleted when you remove the role; the directory is simply unmounted from users' JupyterLab sessions. + +### Managing Subgroup Directories + +Subgroups can have their own directories in JupyterHub if assigned the `allow-group-directory-creation-role`. Assign the role to subgroups as needed to control access and collaboration. + +## In-Depth Look at Roles and Groups + +Understanding how roles and groups work together is essential for effectively managing access and permissions within Nebari. + +### Groups + +Groups represent collections of users who perform similar functions or belong to the same organizational unit. They simplify user management by allowing you to assign roles and permissions at the group level rather than individually to each user. + +By default, Nebari is deployed with the following groups: + +- **admin**: Users with administrative privileges who can manage the system, configurations, and users. +- **developer**: Users who need access to development tools and environments. +- **analyst**: Users who primarily analyze data and may have restricted access compared to developers. + +Groups can be organized hierarchically using subgroups, allowing for more granular control and reflecting organizational structures. + +:::info +**Shared Directories:** Users in a particular group will have access to that group's shared directory in JupyterHub if the group has the `allow-group-directory-creation-role` assigned. +::: + +### Roles + +Roles define a set of permissions that grant access to specific resources or capabilities within Nebari's services. They are assigned to groups or users and determine what actions they can perform. + +Roles can be of two types: + +- **Realm Roles**: Apply globally across all clients (applications) in Keycloak. +- **Client Roles**: Specific to a client (application), such as `jupyterhub`, `conda-store`, or `grafana`. + +Examples of roles include: + +- `admin`: Grants administrative privileges within a client. +- `developer`: Grants development-related permissions. +- `conda_store_admin`: Allows managing Conda environments in Conda-Store. + +### Interaction Between Roles and Groups + +Roles are assigned to groups, and users inherit those roles through their group memberships. This means that: + +- **Users in a Group Get the Group's Roles**: If a group has certain roles assigned, all users in that group will inherit those roles. +- **Multiple Roles Can Be Assigned**: A group can have multiple roles from different clients, providing access to various services. +- **Roles Are Not Inherited by Subgroups**: Roles need to be explicitly assigned to subgroups if you want them to have specific permissions. + +### Role Hierarchies and Stacking + +Roles can be designed to reflect hierarchical permissions. For example, an `admin` role may encompass all the permissions of a `developer` role. + +:::info +**Role Stacking:** If a user is a member of multiple groups with different roles, they effectively have the combined permissions of all assigned roles. For instance, if a user is in a group with the `conda_store_admin` role and another group with the `conda_store_viewer` role, the user will have administrative privileges in Conda-Store due to the higher permission level of `conda_store_admin`. +::: + +### Assigning Roles to Groups + +When creating or editing a group in Keycloak: + +1. **Select the Group**: Navigate to the group you wish to assign roles to. +2. **Go to Role Mappings**: Click on the **Role Mappings** tab. +3. **Assign Roles**: + - Under **Client Roles**, select the client application. + - Select the roles you wish to assign and click **Add selected**. + +## Access Levels and Permissions + +Roles on the other hand represent the type or category of user. This includes access and permissions that this category of user will need to perform their regular job duties. The differences between `groups` and `roles` are subtle. Particular roles (one or many), like `conda_store_admin`, are associated with a particular group, such as `admin` and any user in this group will then assume the role of `conda_store_admin`. + +:::info +These roles can be stacked. This means that if a user is in one group with role `conda_store_admin` and another group with role `conda_store_viewer`, this user ultimately has the role `conda_store_admin`. +::: + +Below is a summary of default groups, their access to Nebari resources, assigned roles, and permissions descriptions. + +| Group | Access to Nebari Resources | Roles | Permissions Description | +| ------------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `analyst` | | | | +| `developer` | | | | +| `admin` | | | | +| `superadmin` | | | | + +:::info +Check [Conda-store authorization model](https://conda-store.readthedocs.io/en/latest/contributing.html#authorization-model) for more details on conda-store authorization. +::: + +:::caution +The role `jupyterhub_admin` gives users elevated permissions to JupyterHub and should be applied judiciously. As mentioned in the table above, a JupyterHub admin is able to impersonate other users and view the contents of their home folder. For more details, read through the [JupyterHub documentation](https://z2jh.jupyter.org/en/stable/jupyterhub/customizing/user-management.html#admin-users). +::: + +To create new groups or modify (or delete) existing groups, log in as `root` and click **Groups** on the left-hand side. + +As an example, we create a new group named `conda-store-manager`. This group will have administrator access to the [Conda-Store service]. + +1. Click **New** in the upper-right hand corner under **Groups**. + +![Keycloak groups tab screenshot - user groups view](/img/how-tos/keycloak_groups.png) + +- Then, give the new group an appropriate name. + +![Keycloak add group form - name field set to conda-store-manager](/img/how-tos/keycloak_new_group1.png) + +2. Under **Role Mapping**, add the appropriate **Client Roles** as needed; there should be no need to update the **Realm Roles**. + +![Keycloak group conda-store-manager form - role mappings tab focused with expanded client roles dropdown](/img/how-tos/keycloak_new_group2.png) + +In this example, the new group only has one mapped role, `conda_store_admin`; however, it's possible to attach multiple **Client Roles** to a single group. + +![Keycloak group conda-store-manager form - role mappings tab focused ](/img/how-tos/keycloak_new_group3.png) + +Once complete, return to the **Users** section in the dashboard and add the relevant users to this newly created group. + ### Components Attribute We have seen in the above example the `component` attribute while creating a role. The value of this parameter diff --git a/docs/docs/how-tos/group-directory-creation.md b/docs/docs/how-tos/group-directory-creation.md deleted file mode 100644 index 792d39515..000000000 --- a/docs/docs/how-tos/group-directory-creation.md +++ /dev/null @@ -1,238 +0,0 @@ ---- -id: group-directory-creation -title: Creating and Managing Groups and Directories -description: How to configure Keycloak's and JupyterHub's groups and directories. ---- - -Groups are a fundamental and vital part of the Nebari ecosystem. They are used to manage access to a wide range of services within Nebari, including JupyterHub instances, Keycloak realms, Conda environments, and computing resources. By grouping users based on roles, projects, or departments, Nebari simplifies the management of permissions and resource sharing. - -Beyond managing access, groups play a crucial role in organizing and sharing data across the JupyterHub ecosystem. Each group can have its own shared directory within JupyterHub, allowing users within the same group to collaborate seamlessly by sharing files and resources. This facilitates team collaboration and ensures that data is organized and accessible to those who need it. - -In this document, we will cover: - -- How to create and manage groups and subgroups in Keycloak -- How to assign roles and permissions to groups -- How groups and roles interact within Nebari's services, such as JupyterHub and Conda-Store -- How to manage group directories in JupyterHub - -## Managing Groups in Keycloak - -Keycloak is the identity and access management service used in Nebari. It allows you to create and manage users, groups, roles, and permissions. Groups in Keycloak are collections of users, and they can be assigned specific roles that grant permissions to access various services within Nebari. - -For detailed information on managing groups in Keycloak, refer to the [Keycloak documentation on Group Management](https://www.keycloak.org/docs/latest/server_admin/#_group_management). - -Below we outline the steps specific to Nebari. - -### Creating a New Group - -To create a new group in Keycloak: - -1. **Log in to Keycloak** as an administrator (usually the `root` user). -2. **Navigate to Groups**: Click on **Groups** in the left-hand menu. -3. **Create the Group**: Click the **New** button, enter an appropriate name for your new group (e.g., `conda-store-manager`), and save. - -If you wish to organize your groups hierarchically, you can create subgroups by selecting a parent group and adding a subgroup. - -### Assigning Roles to a Group - -Roles define the permissions and access levels granted to a group. In Nebari, assigning specific roles to groups ensures that users within the group inherit those permissions. - -To assign roles to a group: - -1. **Select the Group**: Navigate to the group you wish to assign roles to. -2. **Go to Role Mappings**: Click on the **Role Mappings** tab. -3. **Assign Client Roles**: - - Under **Client Roles**, select the client application (e.g., `jupyterhub`, `conda-store`). - - From the available roles, select the ones you wish to assign and click **Add selected**. - -**Note:** Nebari-specific roles include `conda_store_admin`, `allow-group-directory-creation-role`, among others. - -For more details on role mappings, see the [Keycloak documentation on Role Mappings](https://www.keycloak.org/docs/latest/server_admin/#role-mappings). - -### Adding Users to a Group - -To add users to a group: - -1. **Navigate to Users**: Click on **Users** in the left-hand menu. -2. **Select a User**: Choose the user you want to add to a group. -3. **Assign to Group**: - - Click on the **Groups** tab within the user's details. - - Click the **Join** button. - - Select the group (and subgroup, if applicable) you wish to add the user to. - - Click **Join** to add the user to the group. - -Repeat this process for all users who should be part of the group. - -### Managing Subgroups - -Subgroups allow you to create a hierarchical structure of groups, representing organizational units, projects, or teams. Subgroups inherit roles and attributes from their parent groups unless explicitly overridden. - -To manage subgroups: - -- **Creating Subgroups**: Select the parent group, navigate to the **Sub Groups** tab, and create a new subgroup. -- **Assigning Roles to Subgroups**: Roles are not automatically inherited; assign roles to subgroups as needed. -- **Use Cases**: Organize groups hierarchically to reflect organizational structures. - -For more information, see the [Keycloak documentation on Group Hierarchies](https://www.keycloak.org/docs/latest/server_admin/#group-hierarchies). - -## Managing Group Directories in JupyterHub - -:::note Important -As of version `2024.9.1`, JupyterHub creates and mounts directories only for groups with the `allow-group-directory-creation-role`. By default, this includes the `admin`, `analyst`, and `developer` groups. Previously, directories were automatically created for all Keycloak groups. This change gives administrators more control over shared directories and overall access management without cluttering the file system. -::: - -### Understanding Group Directories - -A group directory in JupyterHub is a shared folder accessible to all members of a specific group. It provides a shared space within the file system for collaboration. - -An example directory structure: - -```yaml -/shared -├── admin -│ ├── file1.txt -│ └── file2.txt -├── analyst -│ ├── file1.txt -│ └── file2.txt -└── developer - ├── file1.txt - └── file2.txt -``` - -### Assigning the `allow-group-directory-creation-role` to a Group - -To enable directory creation and mounting for a group in JupyterHub, assign the `allow-group-directory-creation-role` to the group in Keycloak. - -#### Steps to Assign the Role: - -1. **Navigate to the Group**: Log in to Keycloak as an administrator and select the group. -2. **Go to Role Mappings**: Click on the **Role Mappings** tab. -3. **Assign the Role**: - - Under **Client Roles**, select the `jupyterhub` client. - - Select `allow-group-directory-creation-role` and click **Add selected**. - -Users in this group will now have access to the group's shared directory in JupyterHub. - -### Rolling Back the Change - -To remove the group's directory access: - -1. **Navigate to the Group's Role Mappings**: Select the group and go to the **Role Mappings** tab. -2. **Remove the Role**: - - Under **Assigned Roles**, select `allow-group-directory-creation-role`. - - Click **Remove selected**. - -**Data Preservation:** No data is deleted when you remove the role; the directory is simply unmounted from users' JupyterLab sessions. - -### Managing Subgroup Directories - -Subgroups can have their own directories in JupyterHub if assigned the `allow-group-directory-creation-role`. Assign the role to subgroups as needed to control access and collaboration. - -## In-Depth Look at Roles and Groups - -Understanding how roles and groups work together is essential for effectively managing access and permissions within Nebari. - -### Groups - -Groups represent collections of users who perform similar functions or belong to the same organizational unit. They simplify user management by allowing you to assign roles and permissions at the group level rather than individually to each user. - -By default, Nebari is deployed with the following groups: - -- **admin**: Users with administrative privileges who can manage the system, configurations, and users. -- **developer**: Users who need access to development tools and environments. -- **analyst**: Users who primarily analyze data and may have restricted access compared to developers. - -Groups can be organized hierarchically using subgroups, allowing for more granular control and reflecting organizational structures. - -:::info -**Shared Directories:** Users in a particular group will have access to that group's shared directory in JupyterHub if the group has the `allow-group-directory-creation-role` assigned. -::: - -### Roles - -Roles define a set of permissions that grant access to specific resources or capabilities within Nebari's services. They are assigned to groups or users and determine what actions they can perform. - -Roles can be of two types: - -- **Realm Roles**: Apply globally across all clients (applications) in Keycloak. -- **Client Roles**: Specific to a client (application), such as `jupyterhub`, `conda-store`, or `grafana`. - -Examples of roles include: - -- `admin`: Grants administrative privileges within a client. -- `developer`: Grants development-related permissions. -- `conda_store_admin`: Allows managing Conda environments in Conda-Store. - -### Interaction Between Roles and Groups - -Roles are assigned to groups, and users inherit those roles through their group memberships. This means that: - -- **Users in a Group Get the Group's Roles**: If a group has certain roles assigned, all users in that group will inherit those roles. -- **Multiple Roles Can Be Assigned**: A group can have multiple roles from different clients, providing access to various services. -- **Roles Are Not Inherited by Subgroups**: Roles need to be explicitly assigned to subgroups if you want them to have specific permissions. - -### Role Hierarchies and Stacking - -Roles can be designed to reflect hierarchical permissions. For example, an `admin` role may encompass all the permissions of a `developer` role. - -:::info -**Role Stacking:** If a user is a member of multiple groups with different roles, they effectively have the combined permissions of all assigned roles. For instance, if a user is in a group with the `conda_store_admin` role and another group with the `conda_store_viewer` role, the user will have administrative privileges in Conda-Store due to the higher permission level of `conda_store_admin`. -::: - -### Assigning Roles to Groups - -When creating or editing a group in Keycloak: - -1. **Select the Group**: Navigate to the group you wish to assign roles to. -2. **Go to Role Mappings**: Click on the **Role Mappings** tab. -3. **Assign Roles**: - - Under **Client Roles**, select the client application. - - Select the roles you wish to assign and click **Add selected**. - -## Access Levels and Permissions - -Roles on the other hand represent the type or category of user. This includes access and permissions that this category of user will need to perform their regular job duties. The differences between `groups` and `roles` are subtle. Particular roles (one or many), like `conda_store_admin`, are associated with a particular group, such as `admin` and any user in this group will then assume the role of `conda_store_admin`. - -:::info -These roles can be stacked. This means that if a user is in one group with role `conda_store_admin` and another group with role `conda_store_viewer`, this user ultimately has the role `conda_store_admin`. -::: - -Below is a summary of default groups, their access to Nebari resources, assigned roles, and permissions descriptions. - -| Group | Access to Nebari Resources | Roles | Permissions Description | -| ------------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `analyst` | | | | -| `developer` | | | | -| `admin` | | | | -| `superadmin` | | | | - -:::info -Check [Conda-store authorization model](https://conda-store.readthedocs.io/en/latest/contributing.html#authorization-model) for more details on conda-store authorization. -::: - -:::caution -The role `jupyterhub_admin` gives users elevated permissions to JupyterHub and should be applied judiciously. As mentioned in the table above, a JupyterHub admin is able to impersonate other users and view the contents of their home folder. For more details, read through the [JupyterHub documentation](https://z2jh.jupyter.org/en/stable/jupyterhub/customizing/user-management.html#admin-users). -::: - -To create new groups or modify (or delete) existing groups, log in as `root` and click **Groups** on the left-hand side. - -As an example, we create a new group named `conda-store-manager`. This group will have administrator access to the [Conda-Store service]. - -1. Click **New** in the upper-right hand corner under **Groups**. - -![Keycloak groups tab screenshot - user groups view](/img/how-tos/keycloak_groups.png) - -- Then, give the new group an appropriate name. - -![Keycloak add group form - name field set to conda-store-manager](/img/how-tos/keycloak_new_group1.png) - -2. Under **Role Mapping**, add the appropriate **Client Roles** as needed; there should be no need to update the **Realm Roles**. - -![Keycloak group conda-store-manager form - role mappings tab focused with expanded client roles dropdown](/img/how-tos/keycloak_new_group2.png) - -In this example, the new group only has one mapped role, `conda_store_admin`; however, it's possible to attach multiple **Client Roles** to a single group. - -![Keycloak group conda-store-manager form - role mappings tab focused ](/img/how-tos/keycloak_new_group3.png) - -Once complete, return to the **Users** section in the dashboard and add the relevant users to this newly created group. From 432c52502e620d3921f18e47727a311ef049b40f Mon Sep 17 00:00:00 2001 From: vinicius douglas cerutti Date: Wed, 25 Sep 2024 22:53:48 -0300 Subject: [PATCH 3/3] update sidebar ref. link --- docs/docs/how-tos/fine-grained-permissions.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docs/how-tos/fine-grained-permissions.md b/docs/docs/how-tos/fine-grained-permissions.md index 554b865db..b95c4813c 100644 --- a/docs/docs/how-tos/fine-grained-permissions.md +++ b/docs/docs/how-tos/fine-grained-permissions.md @@ -1,7 +1,7 @@ --- -id: group-directory-creation -title: Creating and Managing Groups and Directories -description: How to configure Keycloak's and JupyterHub's groups and directories. +id: fine-grained-permissions +title: Creating and Managing Groups, Roles, and Directories +description: How to configure Keycloak's permissions, groups and roles, and manage group directories in JupyterHub. --- Groups are a fundamental and vital part of the Nebari ecosystem. They are used to manage access to a wide range of services within Nebari, including JupyterHub instances, Keycloak realms, Conda environments, and computing resources. By grouping users based on roles, projects, or departments, Nebari simplifies the management of permissions and resource sharing.