Debian Codegraph @

examples/service-whoami/README.md

raw
1 # Authenticating a service with JupyterHub
2
3 Uses `jupyterhub.services.HubAuthenticated` to authenticate requests with the Hub.
4
5 There is an implementation each of api-token-based `HubAuthenticated` and OAuth-based `HubOAuthenticated`.
6
7 ## Run
8
9 1. Launch JupyterHub and the `whoami` services with
10
11 jupyterhub
12
13 2. Visit http://127.0.0.1:8000/services/whoami-oauth
14
15 After logging in with any username and password, you should see a JSON dump of your user info:
16
17 ```json
18 {
19 "admin": false,
20 "groups": [],
21 "kind": "user",
22 "name": "queequeg",
23 "scopes": ["access:services!service=whoami-oauth"],
24 "session_id": "5a2164273a7346728873bcc2e3c26415"
25 }
26 ```
27
28 What is contained in the model will depend on the permissions
29 requested in the `oauth_client_allowed_scopes` configuration of the service `whoami-oauth` service.
30 The default is the minimum required for identification and access to the service,
31 which will provide the username and current scopes.
32
33 The `whoami-api` service powered by the base `HubAuthenticated` class only supports token-authenticated API requests,
34 not browser visits, because it does not implement OAuth. Visit it by requesting an api token from the tokens page (`/hub/token`),
35 and making a direct request:
36
37 ```bash
38 token="d584cbc5bba2430fb153aadb305029b4"
39 curl -H "Authorization: token $token" http://127.0.0.1:8000/services/whoami-api/ | jq .
40 ```
41
42 ```json
43 {
44 "admin": false,
45 "created": "2021-12-20T09:49:37.258427Z",
46 "groups": [],
47 "kind": "user",
48 "last_activity": "2021-12-20T10:07:31.298056Z",
49 "name": "queequeg",
50 "pending": null,
51 "roles": ["user"],
52 "scopes": [
53 "access:servers!user=queequeg",
54 "access:services",
55 "delete:servers!user=queequeg",
56 "read:servers!user=queequeg",
57 "read:tokens!user=queequeg",
58 "read:users!user=queequeg",
59 "read:users:activity!user=queequeg",
60 "read:users:groups!user=queequeg",
61 "read:users:name!user=queequeg",
62 "servers!user=queequeg",
63 "tokens!user=queequeg",
64 "users:activity!user=queequeg"
65 ],
66 "server": null,
67 "servers": {},
68 "session_id": null
69 }
70 ```
71
72 The above is a more complete user model than the `whoami-oauth` example, because
73 the token was issued with the default `token` role,
74 which has the `inherit` metascope,
75 meaning the token has access to everything the tokens owner has access to.
76
77 This relies on the Hub starting the whoami services, via config (see [jupyterhub_config.py](./jupyterhub_config.py)).
78
79 To govern access to the services, create **roles** with the scope `access:services!service=$service-name`,
80 and assign users to the scope.
81
82 The jupyterhub_config.py grants access for all users to all services via the default 'user' role, with:
83
84 ```python
85 c.JupyterHub.load_roles = [
86 {
87 "name": "user",
88 # grant all users access to all services
89 "scopes": ["access:services", "self"],
90 }
91 ]
92 ```
93
94 A similar service could be run externally, by setting the JupyterHub service environment variables:
95
96 JUPYTERHUB_API_TOKEN
97 JUPYTERHUB_SERVICE_PREFIX
98 JUPYTERHUB_OAUTH_SCOPES
99 JUPYTERHUB_CLIENT_ID # for whoami-oauth only
100
101 or instantiating and configuring a HubAuth object yourself, and attaching it as `self.hub_auth` in your HubAuthenticated handlers.