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

Merge pull request #3169 from IvanaH8/yaml-adding-scopes

Browse Source 
First step for implementing oauth scopes - update to rest-api.yml
This commit is contained in:
Min RK
2020-11-20 08:59:48 +01:00
committed by GitHub
parent e019a33509 18ed1b58cc
commit 31a99b5b2c
1 changed files with 160 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

161
docs/rest-api.yml
View File

@@ -13,8 +13,40 @@ securityDefinitions:
type: apiKey
name: Authorization
in: header
security:
oauth2:
type: oauth2
flow: accessCode
authorizationUrl: '/hub/api/oauth2/authorize' # what are the absolute URIs here? is oauth2 correct here or shall we use just authorizations?
tokenUrl: '/hub/api/oauth2/token'
scopes:
all: Everything a user can do
read:all: Read-only access to everything a user can read (also whoami handler)
users: Grants access to managing users including reading users’ model, posting activity and starting/stoping users servers
read:users: Read-only access to the above
read:users!user=username: Read-only access to a single user's model
read:users:names: Read-only access to users' names
read:users:groups: Read-only access to users' groups
read:users:activity: Read-only access to users' activity
read:users:activity!group=groupname: Read-only access to specific group's users' activity
read:users:servers: Read-only access to users' servers
users:activity!user=username: Update a user's activity
users:servers: Grants access to start/stop any server
users:servers!server=servername: Limits the above to a specific server
users:tokens: Grants access to users' token (includes create/revoke a token)
read:users:tokens: Identify a user from a token
admin:users: Grants access to creating/removing users
admin:users:servers: Grants access to create/remove users' servers
groups: Add/remove users from any group
groups!group=groupname: Add/remove users from a specific group only
read:groups: Read-only access to groups
admin:groups: Grants access to create/delete groups
read:services: Read-only access to services
proxy: Grants access to proxy's routing table, syncing and notifying about a new proxy
shutdown: Grants access to shutdown the Hub
security: # global security, do we want to keep only the apiKey (token: []), change to only oauth2 (with scope all) or have both (either can be used)?
- token: []
- oauth2:
- all
basePath: /hub/api
produces:
- application/json
@@ -79,6 +111,10 @@ paths:
/users:
get:
summary: List users
security:
- oauth2:
- users
- read:users
responses:
'200':
description: The Hub's user list
@@ -88,6 +124,9 @@ paths:
$ref: '#/definitions/User'
post:
summary: Create multiple users
security:
- oauth2:
- admin:users
parameters:
- name: body
in: body
@@ -114,6 +153,11 @@ paths:
/users/{name}:
get:
summary: Get a user by name
security:
- oauth2:
- users
- read:users
- read:users!user=username
parameters:
- name: name
description: username
@@ -127,6 +171,9 @@ paths:
$ref: '#/definitions/User'
post:
summary: Create a single user
security:
- oauth2:
- admin:users
parameters:
- name: name
description: username
@@ -141,6 +188,9 @@ paths:
patch:
summary: Modify a user
description: Change a user's name or admin status
security:
- oauth2:
- users
parameters:
- name: name
description: username
@@ -167,6 +217,9 @@ paths:
$ref: '#/definitions/User'
delete:
summary: Delete a user
security:
- oauth2:
- admin:users
parameters:
- name: name
description: username
@@ -184,6 +237,10 @@ paths:
Notify the Hub of activity by the user,
e.g. accessing a service or (more likely)
actively using a server.
security:
- oauth2:
- users
- users:activity!user=username
parameters:
- name: name
description: username
@@ -236,6 +293,10 @@ paths:
/users/{name}/server:
post:
summary: Start a user's single-user notebook server
security:
- oauth2:
- users
- users:servers
parameters:
- name: name
description: username
@@ -262,6 +323,10 @@ paths:
description: The user's notebook server has not yet started, but has been requested
delete:
summary: Stop a user's server
security:
- oauth2:
- users
- users:servers
parameters:
- name: name
description: username
@@ -276,6 +341,11 @@ paths:
/users/{name}/servers/{server_name}:
post:
summary: Start a user's single-user named-server notebook server
security:
- oauth2:
- users
- users:servers
- users:servers!server=servername
parameters:
- name: name
description: username
@@ -307,6 +377,11 @@ paths:
description: The user's notebook named-server has not yet started, but has been requested
delete:
summary: Stop a user's named-server
security:
- oauth2:
- users
- users:servers
- users:servers!server=servername
parameters:
- name: name
description: username
@@ -344,6 +419,9 @@ paths:
type: string
get:
summary: List tokens for the user
security:
- oauth2:
- users:tokens
responses:
'200':
description: The list of tokens
@@ -357,6 +435,9 @@ paths:
description: No such user
post:
summary: Create a new token for the user
security:
- oauth2:
- users:tokens
parameters:
- name: token_params
in: body
@@ -370,6 +451,9 @@ paths:
note:
type: string
description: A note attached to the token for future bookkeeping
roles:
type: list
description: A list of role names that the token should have
responses:
'201':
description: The newly created token
@@ -377,6 +461,8 @@ paths:
$ref: '#/definitions/Token'
'400':
description: Body must be a JSON dict or empty
'403':
description: Requested role does not exist
/users/{name}/tokens/{token_id}:
parameters:
- name: name
@@ -390,6 +476,9 @@ paths:
type: string
get:
summary: Get the model for a token by id
security:
- oauth2:
- users:tokens
responses:
'200':
description: The info for the new token
@@ -397,12 +486,19 @@ paths:
$ref: '#/definitions/Token'
delete:
summary: Delete (revoke) a token by id
security:
- oauth2:
- users:tokens
responses:
'204':
description: The token has been deleted
/user:
get:
summary: Return authenticated user's model
security:
- oauth2:
- all
- read:all
responses:
'200':
description: The authenticated user's model is returned.
@@ -411,6 +507,10 @@ paths:
/groups:
get:
summary: List groups
security:
- oauth2:
- groups
- read:groups
responses:
'200':
description: The list of groups
@@ -421,6 +521,11 @@ paths:
/groups/{name}:
get:
summary: Get a group by name
security:
- oauth2:
- groups
- groups!group=groupname
- read:groups
parameters:
- name: name
description: group name
@@ -434,6 +539,9 @@ paths:
$ref: '#/definitions/Group'
post:
summary: Create a group
security:
- oauth2:
- admin:groups
parameters:
- name: name
description: group name
@@ -447,6 +555,9 @@ paths:
$ref: '#/definitions/Group'
delete:
summary: Delete a group
security:
- oauth2:
- admin:groups
parameters:
- name: name
description: group name
@@ -459,6 +570,10 @@ paths:
/groups/{name}/users:
post:
summary: Add users to a group
security:
- oauth2:
- groups
- groups!group=groupname
parameters:
- name: name
description: group name
@@ -484,6 +599,10 @@ paths:
$ref: '#/definitions/Group'
delete:
summary: Remove users from a group
security:
- oauth2:
- groups
- groups!group=groupname
parameters:
- name: name
description: group name
@@ -508,6 +627,9 @@ paths:
/services:
get:
summary: List services
security:
- oauth2:
- read:services
responses:
'200':
description: The service list
@@ -518,6 +640,9 @@ paths:
/services/{name}:
get:
summary: Get a service by name
security:
- oauth2:
- read:services
parameters:
- name: name
description: service name
@@ -533,6 +658,9 @@ paths:
get:
summary: Get the proxy's routing table
description: A convenience alias for getting the routing table directly from the proxy
security:
- oauth2:
- proxy
responses:
'200':
description: Routing table
@@ -541,12 +669,18 @@ paths:
description: configurable-http-proxy routing table (see configurable-http-proxy docs for details)
post:
summary: Force the Hub to sync with the proxy
security:
- oauth2:
- proxy
responses:
'200':
description: Success
patch:
summary: Notify the Hub about a new proxy
description: Notifies the Hub of a new proxy to use.
security:
- oauth2:
- proxy
parameters:
- name: body
in: body
@@ -579,6 +713,9 @@ paths:
in the JSON request body.
Logging in via this method is only available when the active Authenticator
accepts passwords (e.g. not OAuth).
security:
- oauth2:
- users:tokens # minrk: this is a deprecated alias to POST /users/{name}/tokens, either remove it or use the same scope
parameters:
- name: credentials
in: body
@@ -603,6 +740,9 @@ paths:
/authorizations/token/{token}:
get:
summary: Identify a user or service from an API token
security:
- oauth2:
- read:users:tokens # minrk: is it really necessary to have a scope for this, or use self handler for token whoami?
parameters:
- name: token
in: path
@@ -633,6 +773,7 @@ paths:
$ref: '#/definitions/User'
'404':
description: A user is not found.
deprecated: true # minrk: let’s not add a scope for this, let’s remove it
/oauth2/authorize:
get:
summary: 'OAuth 2.0 authorize endpoint'
@@ -714,6 +855,9 @@ paths:
/shutdown:
post:
summary: Shutdown the Hub
security:
- oauth2:
- shutdown
parameters:
- name: body
in: body
@@ -747,6 +891,11 @@ definitions:
admin:
type: boolean
description: Whether the user is an admin
roles:
type: array
description: The names of roles this user has
items:
type: string
groups:
type: array
description: The names of groups where this user is a member
@@ -828,6 +977,11 @@ definitions:
admin:
type: boolean
description: Whether the service is an admin
roles:
type: array
description: The names of roles this service has
items:
type: string
url:
type: string
description: The internal url where the service is running
@@ -862,6 +1016,11 @@ definitions:
service:
type: string
description: The service that owns the token (undefined of owned by a user)
roles:
type: array
description: The names of roles this token has
items:
type: string
note:
type: string
description: A note about the token, typically describing what it was created for.