| 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. |