diff --git a/doc/authentication.rst b/doc/authentication.rst new file mode 100644 index 000000000..577d0d54a --- /dev/null +++ b/doc/authentication.rst @@ -0,0 +1,74 @@ +Enabling Authentication +======================= + +By default BinderHub runs without authentication and +for each launch it creates a temporary user and starts a server for that user. + +In order to enable authentication for BinderHub by using JupyterHub as an oauth provider, +you need to add the following into ``config.yaml``: + +.. code:: yaml + + config: + BinderHub: + auth_enabled: true + + jupyterhub: + cull: + # don't cull authenticated users + users: False + + hub: + services: + binder: + oauth_redirect_uri: "/oauth_callback" + oauth_client_id: "binder-oauth-client-test" + extraConfig: + binder: | + from kubespawner import KubeSpawner + + class BinderSpawner(KubeSpawner): + def start(self): + if 'image' in self.user_options: + # binder service sets the image spec via user options + self.image_spec = self.user_options['image'] + return super().start() + c.JupyterHub.spawner_class = BinderSpawner + + singleuser: + # to make notebook servers aware of hub + cmd: jupyterhub-singleuser + + auth: {} + +.. note:: + For `jupyterhub.auth` you should use config of your authenticator. + For more information you can check + `the Authentication guide + `_. + +.. warning:: + `jupyterhub-singleuser` requires `JupyterHub` to be installed in user server images. + Therefore ensure that you use at least `jupyter/repo2docker:ccce3fe` image + to build user images. Because `repo2docker` installs `JupyterHub` by default after that. + +Authentication with named servers +--------------------------------- + +With above configuration Binderhub limits each authenticated user to start one server at a time. +When a user already has a running server, BinderHub displays an error message. + +If you want to have users be able to launch multiple servers at the same time, +you have to enable named servers on JupyterHub: + +.. code:: yaml + + config: + BinderHub: + use_named_servers: true + jupyterhub: + hub: + allowNamedServers: true + +.. note:: + BinderHub assigns a unique name to each server with max 40 characters. diff --git a/doc/index.rst b/doc/index.rst index 10dc55139..42ecc68e3 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -63,6 +63,7 @@ in the community have done. debug customizing + authentication known-deployments BinderHub Developer and Architecture Documentation