mirror of
https://github.com/jupyterhub/jupyterhub.git
synced 2025-10-10 11:33:01 +00:00
81 lines
2.4 KiB
Markdown
81 lines
2.4 KiB
Markdown
# Writing a custom Authenticator
|
|
|
|
The [Authenticator][] is the mechanism for authorizing users.
|
|
Basic authenticators use simple username and password authentication.
|
|
JupyterHub ships only with a [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][].
|
|
|
|
Because the username is passed from the Authenticator to the Spawner,
|
|
a custom Authenticator and Spawner are often used together.
|
|
|
|
See a list of custom Authenticators [on the wiki](https://github.com/jupyter/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:
|
|
|
|
- `username` (self-explanatory)
|
|
- `password` (also self-explanatory)
|
|
|
|
`authenticate`'s job is simple:
|
|
|
|
- return a 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
|
|
requires only overriding this one method:
|
|
|
|
```python
|
|
from tornado import gen
|
|
from IPython.utils.traitlets import Dict
|
|
from jupyterhub.auth import Authenticator
|
|
|
|
class DictionaryAuthenticator(Authenticator):
|
|
|
|
passwords = Dict(config=True,
|
|
help="""dict of username:password for authentication"""
|
|
)
|
|
|
|
@gen.coroutine
|
|
def authenticate(self, handler, data):
|
|
if self.passwords.get(data['username']) == data['password']:
|
|
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.
|
|
|
|
|
|
## 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.
|
|
|
|
You can see an example implementation of an Authenticator that uses [GitHub OAuth][]
|
|
at [OAuthenticator][].
|
|
|
|
|
|
[Authenticator]: ../jupyterhub/auth.py
|
|
[PAM]: http://en.wikipedia.org/wiki/Pluggable_authentication_module
|
|
[OAuth]: http://en.wikipedia.org/wiki/OAuth
|
|
[GitHub OAuth]: https://developer.github.com/v3/oauth/
|
|
[OAuthenticator]: https://github.com/jupyter/oauthenticator
|
|
|