mirror of
https://github.com/jupyterhub/jupyterhub.git
synced 2025-10-07 18:14:10 +00:00
825e8aacea
These were removed in https://github.com/jupyterhub/oauthenticator/pull/691, and now the link checker is not happy.
133 lines
5.7 KiB
Markdown
133 lines
5.7 KiB
Markdown
(authenticators)=
|
|
|
|
# Authentication and User Basics
|
|
|
|
The default Authenticator uses [PAM][] (Pluggable Authentication Module) to authenticate system users with
|
|
their usernames and passwords. With the default Authenticator, any user
|
|
with an account and password on the system will be allowed to login.
|
|
|
|
## Create a set of allowed users (`allowed_users`)
|
|
|
|
You can restrict which users are allowed to login with a set,
|
|
`Authenticator.allowed_users`:
|
|
|
|
```python
|
|
c.Authenticator.allowed_users = {'mal', 'zoe', 'inara', 'kaylee'}
|
|
```
|
|
|
|
Users in the `allowed_users` set are added to the Hub database when the Hub is
|
|
started.
|
|
|
|
```{warning}
|
|
If this configuration value is not set, then **all authenticated users will be allowed into your hub**.
|
|
```
|
|
|
|
## Configure admins (`admin_users`)
|
|
|
|
```{note}
|
|
As of JupyterHub 2.0, the full permissions of `admin_users`
|
|
should not be required.
|
|
Instead, you can assign [roles](define-role-target) to users or groups
|
|
with only the scopes they require.
|
|
```
|
|
|
|
Admin users of JupyterHub, `admin_users`, can add and remove users from
|
|
the user `allowed_users` set. `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 be configured as follows:
|
|
|
|
```python
|
|
c.Authenticator.admin_users = {'mal', 'zoe'}
|
|
```
|
|
|
|
Users in the admin set are automatically added to the user `allowed_users` set,
|
|
if they are not already present.
|
|
|
|
Each Authenticator may have different ways of determining whether a user is an
|
|
administrator. By default, JupyterHub uses the PAMAuthenticator which provides the
|
|
`admin_groups` option and can set administrator status based on a user
|
|
group. For example, we can let any user in the `wheel` group be an admin:
|
|
|
|
```python
|
|
c.PAMAuthenticator.admin_groups = {'wheel'}
|
|
```
|
|
|
|
## Give admin access to other users' notebook servers (`admin_access`)
|
|
|
|
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.**
|
|
|
|
## Add or remove users from the Hub
|
|
|
|
Users can be added to and removed from the Hub via the admin
|
|
panel or the REST API. When a user is **added**, the user will be
|
|
automatically added to the `allowed_users` set and database. Restarting the Hub
|
|
will not require manually updating the `allowed_users` set 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 allowed users set 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.
|
|
|
|
## Use LocalAuthenticator to create system users
|
|
|
|
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 ability to add users to the system. The setting in the config
|
|
file is:
|
|
|
|
```python
|
|
c.LocalAuthenticator.create_system_users = True
|
|
```
|
|
|
|
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.
|
|
|
|
## Use OAuthenticator to support OAuth with popular service providers
|
|
|
|
JupyterHub's [OAuthenticator][] currently supports the following
|
|
popular services:
|
|
|
|
- [Auth0](https://oauthenticator.readthedocs.io/en/latest/reference/api/gen/oauthenticator.auth0.html)
|
|
- [Azure AD](https://oauthenticator.readthedocs.io/en/latest/reference/api/gen/oauthenticator.azuread.html)
|
|
- [Bitbucket](https://oauthenticator.readthedocs.io/en/latest/reference/api/gen/oauthenticator.bitbucket.html)
|
|
- [CILogon](https://oauthenticator.readthedocs.io/en/latest/reference/api/gen/oauthenticator.cilogon.html)
|
|
- [GitHub](https://oauthenticator.readthedocs.io/en/latest/reference/api/gen/oauthenticator.github.html)
|
|
- [GitLab](https://oauthenticator.readthedocs.io/en/latest/reference/api/gen/oauthenticator.gitlab.html)
|
|
- [Globus](https://oauthenticator.readthedocs.io/en/latest/reference/api/gen/oauthenticator.globus.html)
|
|
- [Google](https://oauthenticator.readthedocs.io/en/latest/reference/api/gen/oauthenticator.google.html)
|
|
- [MediaWiki](https://oauthenticator.readthedocs.io/en/latest/reference/api/gen/oauthenticator.mediawiki.html)
|
|
- [OpenShift](https://oauthenticator.readthedocs.io/en/latest/reference/api/gen/oauthenticator.openshift.html)
|
|
|
|
A [generic implementation](https://oauthenticator.readthedocs.io/en/latest/reference/api/gen/oauthenticator.generic.html), which you can use for OAuth authentication
|
|
with any provider, is also available.
|
|
|
|
## Use DummyAuthenticator for testing
|
|
|
|
The `DummyAuthenticator` is a simple Authenticator that
|
|
allows for any username or password unless a global password has been set. If
|
|
set, it will allow for any username as long as the correct password is provided.
|
|
To set a global password, add this to the config file:
|
|
|
|
```python
|
|
c.DummyAuthenticator.password = "some_password"
|
|
```
|
|
|
|
[pam]: https://en.wikipedia.org/wiki/Pluggable_authentication_module
|
|
[oauthenticator]: https://github.com/jupyterhub/oauthenticator
|