add examples for jupyterhub and conda-store permissions

nebari-dev · Jun 24, 2024 · 2d84655 · 2d84655
1 parent 8349cfe
commit 2d84655
Show file tree

Hide file tree

Showing 10 changed files with 84 additions and 4 deletions.
diff --git a/docs/docs/how-tos/fine-grained-permissions.md b/docs/docs/how-tos/fine-grained-permissions.md
@@ -15,10 +15,90 @@ particular service (say jupyterhub) should be created within the keycloak client
 
 This can be accessed at `<nebari-url>/auth/admin/master/console/#/realms/nebari/clients`
 
-We'll take a look at how to manage permissions for following services via Keycloak:
+## Creating a Role
 
-## JupyterHub
+The process for creating a role is similar, irrespective of the service. To create a role for a
+service
 
-The permissions
+- 1. Select the corresponding client for the same and click on "Add Role".
 
-## Conda Store
+ ![Keycloak client add jupyterhub role](/img/how-tos/keycloak_jupyterhub_client.png)
+
+- 2. On the Add Role form, write a meaningful name and description for the role on what this role plans to accomplish and hit "Save".
+
+ ![Keycloak clients add jupyterhub role form](/img/how-tos/keycloak_jupyterhub_add_role.png)
+
+- 3. Now the role should be created, but it does nothing. Lets adds some permissions to it, by clicking on the "Attributes" tab
+ and adding scopes for the same.
+
+ ![Keycloak clients add jupyterhub role form](/img/how-tos/keycloak_add_role_attributes.png)
+
+## Adding Role to Group(s) / User(s)
+
+Creating a role in keycloak has no effect on any user or group's permissions. To be able to grant a set of permissions
+to user or group, we need to attach the role to user or group. To add a role to a user:
+
+- 1. Select users on the left sidebar and enter the username in the lookup.
+
+ ![Keycloak clients add jupyterhub role form](/img/how-tos/keycloak_select_user.png)
+
+- 2. Select that user and click on the "Role Mappings" tab.
+
+ ![Keycloak clients add jupyterhub role form](/img/how-tos/user_role_mapping_tab.png)
+
+- 3. Select the client for which role needs to be added to the user.
+
+ ![Keycloak clients add jupyterhub role form](/img/how-tos/user_role_mapping_roles.png)
+
+- 4. Select the role in the "Available Roles" and click on "Add Selected >>".
+
+ ![Keycloak clients add jupyterhub role form](/img/how-tos/user_role_mapping_add_role.png)
+
+Follow the same steps by clicking on the groups tab and selecting a group to attach a role to a
+group.
+
+In the above section, we learnt how to create a role with some attributes and attach that to a user or a group.
+Now we will learn how to create scopes to grant a particular set of permissions to the user.
+
+## Components Attribute
+
+We have seen in the above example the `component` attribute while creating a role. The value of this param
+depends on the type of component in the service, we're creating a role for, current we only have two components:
+
+- `jupyterhub`: to create jupyterhub native roles in `jupyterhub` client.
+- `conda-store`: to create conda-store roles in `conda_store` client
+
+## JupyterHub Scopes
+
+The syntax for `scopes` attribute for a jupyterhub role in Keycloak in Nebari follows the native RBAC scopes syntax
+for JupyterHub itself. The documentation for the same can be found [here](https://jupyterhub.readthedocs.io/en/stable/rbac/scopes.html#scope-conventions).
+
+Below is an example for the same.
+
+Scopes for allowing users to share apps in Nebari's jhub-apps launcher:
+
+`shares!user,read:users:name,read:groups:name`
+
+The `scopes` defined above consists of three scopes:
+
+- `shares!user`: permissions to share user's server
+- `read:users:name`: permissions to read other user's names
+- `read:groups:name`: permissions to read other groups's names
+
+To be able to share a server to a group or a user you need to be read other user's or group's names and must have
+permissions to be able to share your server, this is what this set of permissions implement.
+
+## Conda Store Scopes
+
+The scopes for roles for conda-store client describes level on permission on a namespace.
+
+Below are some examples for the same:
+
+`admin!namespace=analyst,developer!namespace=nebari-git`
+
+The `scopes` defined above consists of two scopes:
+
+- `admin!namespace=analyst`: `admin` access to namespace `analyst`
+- `developer!namespace=nebari-git`: ``developer` access to namespace `nebari-git`
+
+When attached to a user or a group, the above-mentioned permissions will be granted to the user/group.
diff --git a/docs/static/img/how-tos/keycloak_add_role_attributes.png b/docs/static/img/how-tos/keycloak_add_role_attributes.png
diff --git a/docs/static/img/how-tos/keycloak_clients.png b/docs/static/img/how-tos/keycloak_clients.png
diff --git a/docs/static/img/how-tos/keycloak_jupyterhub_add_role.png b/docs/static/img/how-tos/keycloak_jupyterhub_add_role.png
diff --git a/docs/static/img/how-tos/keycloak_jupyterhub_client.png b/docs/static/img/how-tos/keycloak_jupyterhub_client.png
diff --git a/docs/static/img/how-tos/keycloak_select_user.png b/docs/static/img/how-tos/keycloak_select_user.png
diff --git a/docs/static/img/how-tos/keycloak_user.png b/docs/static/img/how-tos/keycloak_user.png
diff --git a/docs/static/img/how-tos/user_role_mapping_add_role.png b/docs/static/img/how-tos/user_role_mapping_add_role.png
diff --git a/docs/static/img/how-tos/user_role_mapping_roles.png b/docs/static/img/how-tos/user_role_mapping_roles.png
diff --git a/docs/static/img/how-tos/user_role_mapping_tab.png b/docs/static/img/how-tos/user_role_mapping_tab.png