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

53
docs/source/authenticators.md
View File

@@ -1,12 +1,14 @@
# Authenticators # Authenticators
## Basics of Authenticators
The [Authenticator][] is the mechanism for authorizing users. The [Authenticator][] is the mechanism for authorizing users.
Basic authenticators use simple username and password authentication. 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. for logging in with local user accounts.
You can use custom Authenticator subclasses to enable authentication via other systems. You can use custom Authenticator subclasses to enable authentication
One such example is using [GitHub OAuth][]. via other mechanisms. One such example is using [GitHub OAuth][].
Because the username is passed from the Authenticator to the Spawner, Because the username is passed from the Authenticator to the Spawner,
a custom Authenticator and Spawner are often used together. 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). 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: A basic Authenticator has one central method:
### Authenticator.authenticate ### Authenticator.authenticate
Authenticator.authenticate(handler, data) Authenticator.authenticate(handler, data)
This method is passed the tornado RequestHandler and the POST data from the login form. This method is passed the Tornado `RequestHandler` and the `POST data`
Unless the login form has been customized, `data` will have two keys: from JupyterHub's login form. Unless the login form has been customized,
`data` will have two keys:
- `username` (self-explanatory) - `username`
- `password` (also self-explanatory) - `password`
`authenticate`'s job is simple: The `authenticate` method's job is simple:
- return a username (non-empty str) - return the username (non-empty str) of the authenticated user if
of the authenticated user if authentication is successful authentication is successful
- return `None` otherwise - return `None` otherwise
Writing an Authenticator that looks up passwords in a dictionary Writing an Authenticator that looks up passwords in a dictionary
@@ -54,14 +55,7 @@ class DictionaryAuthenticator(Authenticator):
return data['username'] return data['username']
``` ```
### Authenticator.whitelist ## Normalize usernames
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
Since the Authenticator and Spawner both use the same username, Since the Authenticator and Spawner both use the same username,
sometimes you want to transform the name coming from the authentication service 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. In most cases, there is a very limited set of acceptable usernames.
Authenticators can define `validate_username(username)`, Authenticators can define `validate_username(username)`,
@@ -93,18 +87,19 @@ To only allow usernames that start with 'w':
c.Authenticator.username_pattern = r'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. Some login mechanisms, such as [OAuth][], don't map onto username and
For these, you can override the login handlers. 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][] You can see an example implementation of an Authenticator that uses
at [OAuthenticator][]. [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 [Authenticator]: https://github.com/jupyterhub/jupyterhub/blob/master/jupyterhub/auth.py
[PAM]: https://en.wikipedia.org/wiki/Pluggable_authentication_module [PAM]: https://en.wikipedia.org/wiki/Pluggable_authentication_module