From 674c441935558014fe02aca83ec9103004cbe786 Mon Sep 17 00:00:00 2001 From: Deborah Udoh Date: Sun, 9 Oct 2022 19:37:59 +0100 Subject: [PATCH 1/5] Improve documentation --- docs/source/rbac/roles.md | 23 ++++++++--------------- 1 file changed, 8 insertions(+), 15 deletions(-) diff --git a/docs/source/rbac/roles.md b/docs/source/rbac/roles.md index 551e0cf9..cfdd8c24 100644 --- a/docs/source/rbac/roles.md +++ b/docs/source/rbac/roles.md @@ -1,8 +1,6 @@ -(roles)= - # Roles -JupyterHub provides four roles that are available by default: +JupyterHub provides four (4) roles that are available by default: ```{admonition} **Default roles** - `user` role provides a {ref}`default user scope ` `self` that grants access to the user's own resources. @@ -13,11 +11,11 @@ JupyterHub provides four roles that are available by default: **These roles cannot be deleted.** ``` -These default roles have a default collection of scopes, -but you can define the scopes associated with each role (excluding admin) to suit your needs, +These roles are so named because they have a default collection of scopes. +However, you can define the scopes associated with each role (excluding the admin role) to suit your needs, as seen [below](overriding-default-roles). -The `user`, `admin`, and `token` roles by default all preserve the permissions prior to RBAC. +The `user`, `admin`, and `token` roles, by default, all preserve the permissions prior to Role-based Access Control (RBAC). Only the `server` role is changed from pre-2.0, to reduce its permissions to activity-only instead of the default of a full access token. @@ -31,10 +29,10 @@ Roles can be assigned to the following entities: An entity can have zero, one, or multiple roles, and there are no restrictions on which roles can be assigned to which entity. Roles can be added to or removed from entities at any time. **Users** \ -When a new user gets created, they are assigned their default role `user`. Additionaly, if the user is created with admin privileges (via `c.Authenticator.admin_users` in `jupyterhub_config.py` or `admin: true` via API), they will be also granted `admin` role. If existing user's admin status changes via API or `jupyterhub_config.py`, their default role will be updated accordingly (after next startup for the latter). +When a new user gets created, they are assigned their default role, `user`. Additionally, if the user is created with admin privileges (via `c.Authenticator.admin_users` in `jupyterhub_config.py` or `admin: true` via API), they will be also granted `admin` role. If existing user's admin status changes via API or `jupyterhub_config.py`, their default role will be updated accordingly (after next startup for the latter). **Services** \ -Services do not have a default role. Services without roles have no access to the guarded API end-points, so most services will require assignment of a role in order to function. +Services do not have a default role. Services without roles have no access to the guarded API end-points. So, most services will require assignment of a role in order to function. **Groups** \ A group does not require any role, and has no roles by default. If a user is a member of a group, they automatically inherit any of the group's permissions (see {ref}`resolving-roles-scopes-target` for more details). This is useful for assigning a set of common permissions to several users. @@ -42,8 +40,6 @@ A group does not require any role, and has no roles by default. If a user is a m **Tokens** \ A token’s permissions are evaluated based on their owning entity. Since a token is always issued for a user or service, it can never have more permissions than its owner. If no specific scopes are requested for a new token, the token is assigned the scopes of the `token` role. -(define-role-target)= - ## Defining Roles Roles can be defined or modified in the configuration file as a list of dictionaries. An example: @@ -111,9 +107,8 @@ If no scopes are defined for _new role_, JupyterHub will raise a warning. Provid In case the role with a certain name already exists in the database, its definition and scopes will be overwritten. This holds true for all roles except the `admin` role, which cannot be overwritten; an error will be raised if trying to do so. All the role bearers permissions present in the definition will change accordingly. -(overriding-default-roles)= -### Overriding default roles +### Overriding Default Roles Role definitions can include those of the "default" roles listed above (admin excluded), if the default scopes associated with those roles do not suit your deployment. @@ -152,9 +147,7 @@ c.JupyterHub.load_roles = [ ] ``` -(removing-roles-target)= - -## Removing roles +## Removing Roles Only the entities present in the role definition in the `jupyterhub_config.py` remain the role bearers. If a user, service or group is removed from the role definition, they will lose the role on the next startup. From 18b1df8bc67d219912a8c2d1d925d0041b0bb45f Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sun, 9 Oct 2022 19:07:29 +0000 Subject: [PATCH 2/5] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/source/rbac/roles.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/source/rbac/roles.md b/docs/source/rbac/roles.md index cfdd8c24..f5ef8e30 100644 --- a/docs/source/rbac/roles.md +++ b/docs/source/rbac/roles.md @@ -107,7 +107,6 @@ If no scopes are defined for _new role_, JupyterHub will raise a warning. Provid In case the role with a certain name already exists in the database, its definition and scopes will be overwritten. This holds true for all roles except the `admin` role, which cannot be overwritten; an error will be raised if trying to do so. All the role bearers permissions present in the definition will change accordingly. - ### Overriding Default Roles Role definitions can include those of the "default" roles listed above (admin excluded), From ed71aead2b00b6c9c6f66066b9b91c5e2265749c Mon Sep 17 00:00:00 2001 From: Deborah Udoh Date: Mon, 10 Oct 2022 17:56:35 +0100 Subject: [PATCH 3/5] Update roles.md Co-authored-by: Min RK --- docs/source/rbac/roles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/rbac/roles.md b/docs/source/rbac/roles.md index f5ef8e30..859f172c 100644 --- a/docs/source/rbac/roles.md +++ b/docs/source/rbac/roles.md @@ -11,7 +11,7 @@ JupyterHub provides four (4) roles that are available by default: **These roles cannot be deleted.** ``` -These roles are so named because they have a default collection of scopes. +We call these 'default' roles because they are available by default and have a default collection of scopes. However, you can define the scopes associated with each role (excluding the admin role) to suit your needs, as seen [below](overriding-default-roles). From 835fe8be8fd546e73b14150c2cb76e833f374f99 Mon Sep 17 00:00:00 2001 From: Deborah Udoh Date: Mon, 10 Oct 2022 18:03:13 +0100 Subject: [PATCH 4/5] Update roles.md in line with review --- docs/source/rbac/roles.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/source/rbac/roles.md b/docs/source/rbac/roles.md index 859f172c..cce2200c 100644 --- a/docs/source/rbac/roles.md +++ b/docs/source/rbac/roles.md @@ -1,3 +1,4 @@ +(roles)= # Roles JupyterHub provides four (4) roles that are available by default: @@ -40,6 +41,7 @@ A group does not require any role, and has no roles by default. If a user is a m **Tokens** \ A token’s permissions are evaluated based on their owning entity. Since a token is always issued for a user or service, it can never have more permissions than its owner. If no specific scopes are requested for a new token, the token is assigned the scopes of the `token` role. +(define-role-target)= ## Defining Roles Roles can be defined or modified in the configuration file as a list of dictionaries. An example: @@ -107,6 +109,7 @@ If no scopes are defined for _new role_, JupyterHub will raise a warning. Provid In case the role with a certain name already exists in the database, its definition and scopes will be overwritten. This holds true for all roles except the `admin` role, which cannot be overwritten; an error will be raised if trying to do so. All the role bearers permissions present in the definition will change accordingly. +(overriding-default-roles)= ### Overriding Default Roles Role definitions can include those of the "default" roles listed above (admin excluded), @@ -146,6 +149,7 @@ c.JupyterHub.load_roles = [ ] ``` +(removing-roles-target)= ## Removing Roles Only the entities present in the role definition in the `jupyterhub_config.py` remain the role bearers. If a user, service or group is removed from the role definition, they will lose the role on the next startup. From 53bf7a18aedd83d3bdb36dac9df9d4b982a2edbe Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 10 Oct 2022 17:03:45 +0000 Subject: [PATCH 5/5] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/source/rbac/roles.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/source/rbac/roles.md b/docs/source/rbac/roles.md index cce2200c..4e7e4a10 100644 --- a/docs/source/rbac/roles.md +++ b/docs/source/rbac/roles.md @@ -1,4 +1,5 @@ (roles)= + # Roles JupyterHub provides four (4) roles that are available by default: @@ -42,6 +43,7 @@ A group does not require any role, and has no roles by default. If a user is a m A token’s permissions are evaluated based on their owning entity. Since a token is always issued for a user or service, it can never have more permissions than its owner. If no specific scopes are requested for a new token, the token is assigned the scopes of the `token` role. (define-role-target)= + ## Defining Roles Roles can be defined or modified in the configuration file as a list of dictionaries. An example: @@ -110,6 +112,7 @@ If no scopes are defined for _new role_, JupyterHub will raise a warning. Provid In case the role with a certain name already exists in the database, its definition and scopes will be overwritten. This holds true for all roles except the `admin` role, which cannot be overwritten; an error will be raised if trying to do so. All the role bearers permissions present in the definition will change accordingly. (overriding-default-roles)= + ### Overriding Default Roles Role definitions can include those of the "default" roles listed above (admin excluded), @@ -150,6 +153,7 @@ c.JupyterHub.load_roles = [ ``` (removing-roles-target)= + ## Removing Roles Only the entities present in the role definition in the `jupyterhub_config.py` remain the role bearers. If a user, service or group is removed from the role definition, they will lose the role on the next startup.