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

Edit auth docs

Browse Source
This commit is contained in:
Carol Willing
2017-07-27 02:15:31 -07:00
parent cc24f36e80
commit 9847408d77
2 changed files with 67 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

82
docs/source/authenticators-users-basics.md
View File

@@ -1,28 +1,27 @@
# Authentication and Users
The default Authenticator uses [PAM][] to authenticate system users with
their username and password. The default behavior of this Authenticator
is to allow any user with an account and password on the system to login.
their username and password. With the default Authenticator, any user
with an account and password on the system will be allowed to login.
## Creating a whitelist of users
## Create a whitelist of users
You can restrict which users are allowed to login with `Authenticator.whitelist`:
You can restrict which users are allowed to login with a whitelist,
`Authenticator.whitelist`:
```python
c.Authenticator.whitelist = {'mal', 'zoe', 'inara', 'kaylee'}
```
Users listed in the whitelist are added to the Hub database when the Hub is
Users in the whitelist are added to the Hub database when the Hub is
started.
## Managing Hub administrators
## Configure admins (`admin_users`)
### Configuring admins (`admin_users`)
Admin users of JupyterHub, `admin_users`, have the ability to add and remove
users from the user `whitelist` or to take actions on the users' behalf,
such as stopping and restarting their servers.
Admin users of JupyterHub, `admin_users`, can add and remove users from
the user `whitelist`. `admin_users` can take actions on other users'
behalf, such as stopping and restarting their servers.
A set of initial admin users, `admin_users` can configured be as follows:
@@ -32,44 +31,49 @@ c.Authenticator.admin_users = {'mal', 'zoe'}
Users in the admin list are automatically added to the user `whitelist`,
if they are not already present.
### Admin access to other users' notebook servers (`admin_access`)
## Give admin access to other users' notebook servers (`admin_access`)
By default the admin users do not have permission to log in *as other users*
since the default `JupyterHub.admin_access` setting is False.
If `JupyterHub.admin_access` is set to True, then admin users have permission
to log in *as other users* on their respective machines, for debugging.
**You should make sure your users know if admin_access is enabled.**
Since the default `JupyterHub.admin_access` setting is False, the admins
do not have permission to log in to the single user notebook servers
owned by *other users*. If `JupyterHub.admin_access` is set to True,
then admins have permission to log in *as other users* on their
respective machines, for debugging. **As a courtesy, you should make
sure your users know if admin_access is enabled.**
Note: additional configuration examples are provided in this guide's
[Configuration Examples section](./config-examples.html).
## Add or remove users from the Hub
### Add or remove users from the Hub
Users can be added to and removed from the Hub via either the admin
panel or the REST API. When a user is **added**, the user will be
automatically added to the whitelist and database. Restarting the Hub
will not require manually updating the whitelist in your config file,
as the users will be loaded from the database.
Users can be added to and removed from the Hub via either the admin panel or
REST API.
After starting the Hub once, it is not sufficient to **remove** a user
from the whitelist in your config file. You must also remove the user
from the Hub's database, either by deleting the user from JupyterHub's
admin page, or you can clear the `jupyterhub.sqlite` database and start
fresh.
If a user is **added**, the user will be automatically added to the whitelist
and database. Restarting the Hub will not require manually updating the
whitelist in your config file, as the users will be loaded from the database.
## Use LocalAuthenticator to create systems users
After starting the Hub once, it is not sufficient to **remove** a user from
the whitelist in your config file. You must also remove the user from the Hub's
database, either by deleting the user from the admin page, or you can clear
the `jupyterhub.sqlite` database and start fresh.
The default `PAMAuthenticator` is one case of a special kind of authenticator, called a
`LocalAuthenticator`, indicating that it manages users on the local system. When you add a user to
the Hub, a `LocalAuthenticator` checks if that user already exists. Normally, there will be an
error telling you that the user doesn't exist. If you set the configuration value
The `LocalAuthenticator` is a special kind of authenticator that has
the ability to manage users on the local system. When you try to add a
new user to the Hub, a `LocalAuthenticator` will check if the user
already exists. If you set the configuration value, `create_system_users`,
to `True` in the configuration file, the `LocalAuthenticator` has
the privileges to add users to the system. The setting in the config
file is:
```python
c.LocalAuthenticator.create_system_users = True
```
however, adding a user to the Hub that doesn't already exist on the system will result in the Hub
creating that user via the system `adduser` command line tool. This option is typically used on
hosted deployments of JupyterHub, to avoid the need to manually create all your users before
launching the service. It is not recommended when running JupyterHub in situations where
JupyterHub users maps directly onto UNIX users.
Adding a user to the Hub that doesn't already exist on the system will
result in the Hub creating that user via the system `adduser` command
line tool. This option is typically used on hosted deployments of
JupyterHub, to avoid the need to manually create all your users before
launching the service. This approach is not recommended when running
JupyterHub in situations where JupyterHub users map directly onto the
system's UNIX users.
[PAM]: https://en.wikipedia.org/wiki/Pluggable_authentication_module

53
docs/source/authenticators.md
View File

@@ -1,12 +1,14 @@
# Authenticators
## Basics of Authenticators
The [Authenticator][] is the mechanism for authorizing users.
Basic authenticators use simple username and password authentication.
JupyterHub ships only with a [PAM][]-based Authenticator,
JupyterHub ships only with the default [PAM][]-based Authenticator,
for logging in with local user accounts.
You can use custom Authenticator subclasses to enable authentication via other systems.
One such example is using [GitHub OAuth][].
You can use custom Authenticator subclasses to enable authentication
via other mechanisms. One such example is using [GitHub OAuth][].
Because the username is passed from the Authenticator to the Spawner,
a custom Authenticator and Spawner are often used together.
@@ -14,24 +16,23 @@ a custom Authenticator and Spawner are often used together.
See a list of custom Authenticators [on the wiki](https://github.com/jupyterhub/jupyterhub/wiki/Authenticators).
## Basics of Authenticators
A basic Authenticator has one central method:
### Authenticator.authenticate
Authenticator.authenticate(handler, data)
This method is passed the tornado RequestHandler and the POST data from the login form.
Unless the login form has been customized, `data` will have two keys:
This method is passed the Tornado `RequestHandler` and the `POST data`
from JupyterHub's login form. Unless the login form has been customized,
`data` will have two keys:
- `username` (self-explanatory)
- `password` (also self-explanatory)
- `username`
- `password`
`authenticate`'s job is simple:
The `authenticate` method's job is simple:
- return a username (non-empty str)
of the authenticated user if authentication is successful
- return the username (non-empty str) of the authenticated user if
authentication is successful
- return `None` otherwise
Writing an Authenticator that looks up passwords in a dictionary
@@ -54,14 +55,7 @@ class DictionaryAuthenticator(Authenticator):
return data['username']
```
### Authenticator.whitelist
Authenticators can specify a whitelist of usernames to allow authentication.
For local user authentication (e.g. PAM), this lets you limit which users
can login.
## Normalizing and validating usernames
## Normalize usernames
Since the Authenticator and Spawner both use the same username,
sometimes you want to transform the name coming from the authentication service
@@ -77,7 +71,7 @@ c.Authenticator.username_map = {
}
```
### Validating usernames
## Validate usernames
In most cases, there is a very limited set of acceptable usernames.
Authenticators can define `validate_username(username)`,
@@ -93,18 +87,19 @@ To only allow usernames that start with 'w':
c.Authenticator.username_pattern = r'w.*'
```
## OAuth and other non-password logins
## How to use OAuth and other non-password logins
Some login mechanisms, such as [OAuth][], don't map onto username+password.
For these, you can override the login handlers.
Some login mechanisms, such as [OAuth][], don't map onto username and
password authentication, and instead use tokens. When using these
mechanisms, you can override the login handlers.
You can see an example implementation of an Authenticator that uses [GitHub OAuth][]
at [OAuthenticator][].
You can see an example implementation of an Authenticator that uses
[GitHub OAuth][] at [OAuthenticator][].
## How to write a custom authenticator
## Writing a custom authenticator
If you are interested in writing a custom authenticator, you can read [this tutorial](http://jupyterhub-tutorial.readthedocs.io/en/latest/authenticators.html).
If you are interested in writing a custom authenticator, you can read
[this tutorial](http://jupyterhub-tutorial.readthedocs.io/en/latest/authenticators.html).
[Authenticator]: https://github.com/jupyterhub/jupyterhub/blob/master/jupyterhub/auth.py
[PAM]: https://en.wikipedia.org/wiki/Pluggable_authentication_module