Skip to content

Improve rbac/roles documentation #4071

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Oct 12, 2022
Merged

Improve rbac/roles documentation #4071

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
674c441
Improve documentation
NPDebs Oct 9, 2022
18b1df8
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Oct 9, 2022
ed71aea
Update roles.md
NPDebs Oct 10, 2022
835fe8b
Update roles.md in line with review
NPDebs Oct 10, 2022
53bf7a1
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Oct 10, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions docs/source/rbac/roles.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe this is actually required for cross-linking from other documents, and shouldn't be removed.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, yes! I was going to ask.

I saw this, and didn't know what the purpose was. Naturally, I took it out...instead of asking for clarification. 🤦🏽‍♀️

In hindsight, that's a really dumb thing to do.

# 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 <default-user-scope-target>` `self` that grants access to the user's own resources.
Expand All @@ -13,11 +13,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,
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).

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.

Expand All @@ -31,10 +31,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.
Expand Down Expand Up @@ -113,7 +113,7 @@ In case the role with a certain name already exists in the database, its definit

(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.
Expand Down Expand Up @@ -154,7 +154,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.

Expand Down