hazza/jupyterhub
1
0
Fork 0
mirror of https://github.com/jupyterhub/jupyterhub.git synced 2025-10-18 15:33:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

[pre-commit.ci] auto fixes from pre-commit.com hooks

Browse Source 
for more information, see https://pre-commit.ci
This commit is contained in:
pre-commit-ci[bot]
2025-02-18 21:07:16 +00:00
parent 6be4893bfa
commit 7add99c09a
2 changed files with 104 additions and 91 deletions
Download Patch File Download Diff File Expand all files Collapse all files

137
docs/source/_static/rest-api.yml
View File

@@ -62,8 +62,7 @@ paths:
properties:
class:
type: string
description:
The Python class currently active for JupyterHub
description: The Python class currently active for JupyterHub
Authentication
version:
type: string
@@ -73,8 +72,7 @@ paths:
properties:
class:
type: string
description:
The Python class currently active for spawning
description: The Python class currently active for spawning
single-user notebook servers
version:
type: string
@@ -258,8 +256,7 @@ paths:
parameters:
- $ref: "#/components/parameters/userName"
requestBody:
description:
Updated user info. At least one key to be updated (name or admin)
description: Updated user info. At least one key to be updated (name or admin)
is required.
content:
application/json:
@@ -268,13 +265,11 @@ paths:
properties:
name:
type: string
description:
the new name (optional, if another key is updated i.e.
description: the new name (optional, if another key is updated i.e.
admin)
admin:
type: boolean
description:
update admin (optional, if another key is updated i.e.
description: update admin (optional, if another key is updated i.e.
name)
required: true
responses:
@@ -291,8 +286,7 @@ paths:
post:
operationId: post-user-activity
summary: Notify Hub of activity for a given user
description:
Notify the Hub of activity by the user, e.g. accessing a service
description: Notify the Hub of activity by the user, e.g. accessing a service
or (more likely) actively using a server.
parameters:
- $ref: "#/components/parameters/userName"
@@ -372,8 +366,7 @@ paths:
description: The user's notebook server has started
content: {}
202:
description:
The user's notebook server has not yet started, but has been
description: The user's notebook server has not yet started, but has been
requested
content: {}
security:
@@ -387,8 +380,7 @@ paths:
- $ref: "#/components/parameters/userName"
responses:
202:
description:
The user's notebook server has not yet stopped as it is taking
description: The user's notebook server has not yet stopped as it is taking
a while to stop
content: {}
204:
@@ -420,8 +412,7 @@ paths:
description: The user's notebook named-server has started
content: {}
202:
description:
The user's notebook named-server has not yet started, but has
description: The user's notebook named-server has not yet started, but has
been requested
content: {}
security:
@@ -457,8 +448,7 @@ paths:
required: false
responses:
202:
description:
The user's notebook named-server has not yet stopped as it
description: The user's notebook named-server has not yet stopped as it
is taking a while to stop
content: {}
204:
@@ -472,8 +462,7 @@ paths:
get:
operationId: get-user-shared
summary: List servers shared with user
description:
Returns list of Shares granting the user access to servers owned
description: Returns list of Shares granting the user access to servers owned
by others (new in 5.0)
parameters:
- $ref: "#/components/parameters/userName"
@@ -587,8 +576,7 @@ paths:
expires_in:
type: number
example: 3600
description:
lifetime (in seconds) after which the requested token
description: lifetime (in seconds) after which the requested token
will expire. Omit, or specify null or 0 for no expiration.
note:
type: string
@@ -1262,8 +1250,7 @@ paths:
get:
operationId: get-proxy
summary: Get the proxy's routing table
description:
A convenience alias for getting the routing table directly from
description: A convenience alias for getting the routing table directly from
the proxy
parameters:
- $ref: "#/components/parameters/paginationOffset"
@@ -1275,8 +1262,7 @@ paths:
application/json:
schema:
type: object
description:
configurable-http-proxy routing table (see configurable-http-proxy
description: configurable-http-proxy routing table (see configurable-http-proxy
docs for details)
security:
- oauth2:
@@ -1296,8 +1282,7 @@ paths:
summary: Notify the Hub about a new proxy
description: Notifies the Hub of a new proxy to use.
requestBody:
description:
Any values that have changed for the new proxy. All keys are
description: Any values that have changed for the new proxy. All keys are
optional.
content:
application/json:
@@ -1389,8 +1374,7 @@ paths:
get:
operationId: get-auth-cookie
summary: Identify a user from a cookie
description:
Used by single-user notebook servers to hand off cookie authentication
description: Used by single-user notebook servers to hand off cookie authentication
to the Hub
parameters:
- name: cookie_name
@@ -1515,13 +1499,11 @@ paths:
properties:
proxy:
type: boolean
description:
Whether the proxy should be shutdown as well (default
description: Whether the proxy should be shutdown as well (default
from Hub config)
servers:
type: boolean
description:
Whether users' notebook servers should be shutdown
description: Whether users' notebook servers should be shutdown
as well (default from Hub config)
required: false
responses:
@@ -1666,8 +1648,7 @@ components:
type: string
server:
type: string
description:
The user's notebook server's base URL, if running; null if
description: The user's notebook server's base URL, if running; null if
not.
pending:
type: string
@@ -1699,8 +1680,7 @@ components:
properties:
name:
type: string
description:
The server's name. The user's default server has an empty name
description: The server's name. The user's default server has an empty name
('')
ready:
type: boolean
@@ -1763,15 +1743,13 @@ components:
state:
type: object
properties: {}
description:
Arbitrary internal state from this server's spawner. Only available
description: Arbitrary internal state from this server's spawner. Only available
on the hub's users list or get-user-by-name method, and only with admin:users:server_state
scope. None otherwise.
user_options:
type: object
properties: {}
description:
User specified options for the user's spawned instance of a
description: User specified options for the user's spawned instance of a
single-user server.
RequestIdentity:
description: |
@@ -1940,8 +1918,7 @@ components:
items:
type: string
group:
description:
the group being shared with (exactly one of 'user' or 'group'
description: the group being shared with (exactly one of 'user' or 'group'
will be non-null, the other will be null)
type:
- object
@@ -1950,8 +1927,7 @@ components:
name:
type: string
user:
description:
the user being shared with (exactly one of 'user' or 'group'
description: the user being shared with (exactly one of 'user' or 'group'
will be non-null, the other will be null)
type:
- object
@@ -1965,8 +1941,7 @@ components:
format: date-time
ShareCode:
description:
A single sharing code. There is at most one of these objects per
description: A single sharing code. There is at most one of these objects per
(server, user) or (server, group) combination.
type: object
properties:
@@ -2002,8 +1977,7 @@ components:
properties:
id:
type: string
description:
The id of the API token. Used for modifying or deleting the
description: The id of the API token. Used for modifying or deleting the
token.
user:
type: string
@@ -2013,22 +1987,19 @@ components:
description: The service that owns the token (undefined of owned by a user)
roles:
type: array
description:
Deprecated in JupyterHub 3, always an empty list. Tokens have
description: Deprecated in JupyterHub 3, always an empty list. Tokens have
'scopes' starting from JupyterHub 3.
items:
type: string
scopes:
type: array
description:
List of scopes this token has been assigned. New in JupyterHub
description: List of scopes this token has been assigned. New in JupyterHub
3. In JupyterHub 2.x, tokens were assigned 'roles' instead of scopes.
items:
type: string
note:
type: string
description:
A note about the token, typically describing what it was created
description: A note about the token, typically describing what it was created
for.
created:
type: string
@@ -2059,13 +2030,11 @@ components:
properties:
token:
type: string
description:
The token itself. Only present in responses to requests for
description: The token itself. Only present in responses to requests for
a new token.
id:
type: string
description:
The id of the API token. Used for modifying or deleting the
description: The id of the API token. Used for modifying or deleting the
token.
user:
type: string
@@ -2075,22 +2044,19 @@ components:
description: The service that owns the token (undefined of owned by a user)
roles:
type: array
description:
Deprecated in JupyterHub 3, always an empty list. Tokens have
description: Deprecated in JupyterHub 3, always an empty list. Tokens have
'scopes' starting from JupyterHub 3.
items:
type: string
scopes:
type: array
description:
List of scopes this token has been assigned. New in JupyterHub
description: List of scopes this token has been assigned. New in JupyterHub
3. In JupyterHub 2.x, tokens were assigned 'roles' instead of scopes.
items:
type: string
note:
type: string
description:
A note about the token, typically describing what it was created
description: A note about the token, typically describing what it was created
for.
created:
type: string
@@ -2128,27 +2094,21 @@ components:
tokenUrl: /hub/api/oauth2/token
scopes:
(no_scope): Identify the owner of the requesting entity.
self:
The user’s own resources _(metascope for users, resolves to (no_scope)
self: The user’s own resources _(metascope for users, resolves to (no_scope)
for services)_
inherit:
Everything that the token-owning entity can access _(metascope
inherit: Everything that the token-owning entity can access _(metascope
for tokens)_
admin-ui:
Access the admin page. Permission to take actions via the admin
admin-ui: Access the admin page. Permission to take actions via the admin
page granted separately.
admin:users:
Read, modify, create, and delete users and their authentication
admin:users: Read, modify, create, and delete users and their authentication
state, not including their servers or tokens. This is an extremely privileged
scope and should be considered tantamount to superuser.
admin:auth_state: Read a user’s authentication state.
users:
Read and write permissions to user models (excluding servers, tokens
users: Read and write permissions to user models (excluding servers, tokens
and authentication state).
delete:users: Delete users.
list:users: List users, including at least their names.
read:users:
Read user models (including servers, tokens and authentication
read:users: Read user models (including servers, tokens and authentication
state).
read:users:name: Read names of users.
read:users:groups: Read users’ group membership.
@@ -2158,27 +2118,23 @@ components:
read:roles:services: Read service role assignments.
read:roles:groups: Read group role assignments.
users:activity: Update time of last user activity.
admin:servers:
Read, start, stop, create and delete user servers and their
admin:servers: Read, start, stop, create and delete user servers and their
state.
admin:server_state: Read and write users’ server state.
servers: Start and stop user servers.
read:servers:
Read users’ names and their server models (excluding the
read:servers: Read users’ names and their server models (excluding the
server state).
delete:servers: Stop and delete users' servers.
tokens: Read, write, create and delete user tokens.
read:tokens: Read user tokens.
admin:groups: Read and write group information, create and delete groups.
groups:
"Read and write group information, including adding/removing any
users to/from groups. Note: adding users to groups may affect permissions."
groups: 'Read and write group information, including adding/removing any
users to/from groups. Note: adding users to groups may affect permissions.'
list:groups: List groups, including at least their names.
read:groups: Read group models.
read:groups:name: Read group names.
delete:groups: Delete groups.
admin:services:
Create, read, update, delete services, not including services
admin:services: Create, read, update, delete services, not including services
defined from config files.
list:services: List services, including at least their names.
read:services: Read service models.
@@ -2192,8 +2148,7 @@ components:
read:groups:shares: Read servers shared with a group.
read:shares: Read information about shared access to servers.
shares: Manage access to shared servers.
proxy:
Read information about the proxy’s routing table, sync the Hub
proxy: Read information about the proxy’s routing table, sync the Hub
with the proxy and notify the Hub about a new proxy.
shutdown: Shutdown the hub.
read:metrics: Read prometheus metrics.

58
docs/source/rbac/scope-table.md
View File

@@ -0,0 +1,58 @@
Table 1. Available scopes and their hierarchy
| Scope | Grants permission to: |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `(no_scope)` | Identify the owner of the requesting entity. |
| `self` | The user’s own resources _(metascope for users, resolves to (no_scope) for services)_ |
| `inherit` | Everything that the token-owning entity can access _(metascope for tokens)_ |
| `admin-ui` | Access the admin page. Permission to take actions via the admin page granted separately. |
| `admin:users` | Read, modify, create, and delete users and their authentication state, not including their servers or tokens. This is an extremely privileged scope and should be considered tantamount to superuser. |
|    `admin:auth_state` | Read a user’s authentication state. |
|    `users` | Read and write permissions to user models (excluding servers, tokens and authentication state). |
|       `read:users` | Read user models (including servers, tokens and authentication state). |
|          `read:users:name` | Read names of users. |
|          `read:users:groups` | Read users’ group membership. |
|          `read:users:activity` | Read time of last user activity. |
|       `list:users` | List users, including at least their names. |
|          `read:users:name` | Read names of users. |
|       `users:activity` | Update time of last user activity. |
|          `read:users:activity` | Read time of last user activity. |
|    `read:roles:users` | Read user role assignments. |
|    `delete:users` | Delete users. |
| `read:roles` | Read role assignments. |
|    `read:roles:users` | Read user role assignments. |
|    `read:roles:services` | Read service role assignments. |
|    `read:roles:groups` | Read group role assignments. |
| `admin:servers` | Read, start, stop, create and delete user servers and their state. |
|    `admin:server_state` | Read and write users’ server state. |
|    `servers` | Start and stop user servers. |
|       `read:servers` | Read users’ names and their server models (excluding the server state). |
|          `read:users:name` | Read names of users. |
|       `delete:servers` | Stop and delete users' servers. |
| `tokens` | Read, write, create and delete user tokens. |
|    `read:tokens` | Read user tokens. |
| `admin:groups` | Read and write group information, create and delete groups. |
|    `groups` | Read and write group information, including adding/removing any users to/from groups. Note: adding users to groups may affect permissions. |
|       `read:groups` | Read group models. |
|          `read:groups:name` | Read group names. |
|       `list:groups` | List groups, including at least their names. |
|          `read:groups:name` | Read group names. |
|    `read:roles:groups` | Read group role assignments. |
|    `delete:groups` | Delete groups. |
| `admin:services` | Create, read, update, delete services, not including services defined from config files. |
|    `list:services` | List services, including at least their names. |
|       `read:services:name` | Read service names. |
|    `read:services` | Read service models. |
|       `read:services:name` | Read service names. |
|    `read:roles:services` | Read service role assignments. |
| `read:hub` | Read detailed information about the Hub. |
| `access:services` | Access services via API or browser. |
| `shares` | Manage access to shared servers. |
|    `access:servers` | Access user servers via API or browser. |
|    `read:shares` | Read information about shared access to servers. |
|    `users:shares` | Read and revoke a user's access to shared servers. |
|       `read:users:shares` | Read servers shared with a user. |
|    `groups:shares` | Read and revoke a group's access to shared servers. |
|       `read:groups:shares` | Read servers shared with a group. |
| `proxy` | Read information about the proxy’s routing table, sync the Hub with the proxy and notify the Hub about a new proxy. |
| `shutdown` | Shutdown the hub. |
| `read:metrics` | Read prometheus metrics. |