mirror of
https://github.com/jupyterhub/jupyterhub.git
synced 2025-10-14 13:33:00 +00:00
102 lines
3.2 KiB
Markdown
102 lines
3.2 KiB
Markdown
# Authenticating a service with JupyterHub
|
|
|
|
Uses `jupyterhub.services.HubAuthenticated` to authenticate requests with the Hub.
|
|
|
|
There is an implementation each of api-token-based `HubAuthenticated` and OAuth-based `HubOAuthenticated`.
|
|
|
|
## Run
|
|
|
|
1. Launch JupyterHub and the `whoami` services with
|
|
|
|
jupyterhub
|
|
|
|
2. Visit http://127.0.0.1:8000/services/whoami-oauth
|
|
|
|
After logging in with any username and password, you should see a JSON dump of your user info:
|
|
|
|
```json
|
|
{
|
|
"admin": false,
|
|
"groups": [],
|
|
"kind": "user",
|
|
"name": "queequeg",
|
|
"scopes": ["access:services!service=whoami-oauth"],
|
|
"session_id": "5a2164273a7346728873bcc2e3c26415"
|
|
}
|
|
```
|
|
|
|
What is contained in the model will depend on the permissions
|
|
requested in the `oauth_client_allowed_scopes` configuration of the service `whoami-oauth` service.
|
|
The default is the minimum required for identification and access to the service,
|
|
which will provide the username and current scopes.
|
|
|
|
The `whoami-api` service powered by the base `HubAuthenticated` class only supports token-authenticated API requests,
|
|
not browser visits, because it does not implement OAuth. Visit it by requesting an api token from the tokens page (`/hub/token`),
|
|
and making a direct request:
|
|
|
|
```bash
|
|
token="d584cbc5bba2430fb153aadb305029b4"
|
|
curl -H "Authorization: token $token" http://127.0.0.1:8000/services/whoami-api/ | jq .
|
|
```
|
|
|
|
```json
|
|
{
|
|
"admin": false,
|
|
"created": "2021-12-20T09:49:37.258427Z",
|
|
"groups": [],
|
|
"kind": "user",
|
|
"last_activity": "2021-12-20T10:07:31.298056Z",
|
|
"name": "queequeg",
|
|
"pending": null,
|
|
"roles": ["user"],
|
|
"scopes": [
|
|
"access:servers!user=queequeg",
|
|
"access:services",
|
|
"delete:servers!user=queequeg",
|
|
"read:servers!user=queequeg",
|
|
"read:tokens!user=queequeg",
|
|
"read:users!user=queequeg",
|
|
"read:users:activity!user=queequeg",
|
|
"read:users:groups!user=queequeg",
|
|
"read:users:name!user=queequeg",
|
|
"servers!user=queequeg",
|
|
"tokens!user=queequeg",
|
|
"users:activity!user=queequeg"
|
|
],
|
|
"server": null,
|
|
"servers": {},
|
|
"session_id": null
|
|
}
|
|
```
|
|
|
|
The above is a more complete user model than the `whoami-oauth` example, because
|
|
the token was issued with the default `token` role,
|
|
which has the `inherit` metascope,
|
|
meaning the token has access to everything the tokens owner has access to.
|
|
|
|
This relies on the Hub starting the whoami services, via config (see [jupyterhub_config.py](./jupyterhub_config.py)).
|
|
|
|
To govern access to the services, create **roles** with the scope `access:services!service=$service-name`,
|
|
and assign users to the scope.
|
|
|
|
The jupyterhub_config.py grants access for all users to all services via the default 'user' role, with:
|
|
|
|
```python
|
|
c.JupyterHub.load_roles = [
|
|
{
|
|
"name": "user",
|
|
# grant all users access to all services
|
|
"scopes": ["access:services", "self"],
|
|
}
|
|
]
|
|
```
|
|
|
|
A similar service could be run externally, by setting the JupyterHub service environment variables:
|
|
|
|
JUPYTERHUB_API_TOKEN
|
|
JUPYTERHUB_SERVICE_PREFIX
|
|
JUPYTERHUB_OAUTH_SCOPES
|
|
JUPYTERHUB_CLIENT_ID # for whoami-oauth only
|
|
|
|
or instantiating and configuring a HubAuth object yourself, and attaching it as `self.hub_auth` in your HubAuthenticated handlers.
|