From 26732ecb32b868621c5155d5a039a32f497efb9f Mon Sep 17 00:00:00 2001 From: Kenan Erdogan Date: Fri, 11 Jan 2019 15:20:36 +0100 Subject: [PATCH 1/4] document authentication --- doc/authentication.rst | 74 ++++++++++++++++++++++++++++++++++++++++++ doc/index.rst | 1 + 2 files changed, 75 insertions(+) create mode 100644 doc/authentication.rst 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 From f60cec35db6472646eb6ada2df8f6e050fbabd82 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Thu, 17 Jan 2019 08:40:10 +0100 Subject: [PATCH 2/4] Apply suggestions from code review Co-Authored-By: bitnik --- doc/authentication.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/authentication.rst b/doc/authentication.rst index 577d0d54a..7e8942949 100644 --- a/doc/authentication.rst +++ b/doc/authentication.rst @@ -42,15 +42,15 @@ you need to add the following into ``config.yaml``: auth: {} .. note:: - For `jupyterhub.auth` you should use config of your authenticator. + 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. + ``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 --------------------------------- From e4542a6ed9982494ad3e2387dade4ed969ab39a7 Mon Sep 17 00:00:00 2001 From: Kenan Erdogan Date: Thu, 31 Jan 2019 08:53:10 +0100 Subject: [PATCH 3/4] use image for kubespawner instead of image_spec which is deprecated --- doc/authentication.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/authentication.rst b/doc/authentication.rst index 7e8942949..d151036f5 100644 --- a/doc/authentication.rst +++ b/doc/authentication.rst @@ -31,7 +31,7 @@ you need to add the following into ``config.yaml``: 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'] + self.image = self.user_options['image'] return super().start() c.JupyterHub.spawner_class = BinderSpawner From ce78cbc41fb9fcdf524f00276d5447b9777bdf78 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Fri, 1 Feb 2019 13:22:50 +0100 Subject: [PATCH 4/4] Apply suggestions from code review Co-Authored-By: bitnik --- doc/authentication.rst | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/doc/authentication.rst b/doc/authentication.rst index d151036f5..237c39d2c 100644 --- a/doc/authentication.rst +++ b/doc/authentication.rst @@ -21,9 +21,12 @@ you need to add the following into ``config.yaml``: hub: services: binder: - oauth_redirect_uri: "/oauth_callback" + oauth_redirect_uri: "http:///oauth_callback" oauth_client_id: "binder-oauth-client-test" extraConfig: + hub_extra: | + c.JupyterHub.redirect_to_server = False + binder: | from kubespawner import KubeSpawner @@ -41,6 +44,17 @@ you need to add the following into ``config.yaml``: auth: {} +If the configuration above was entered correctly, once you upgrade your +BinderHub Helm Chart with ``helm upgrade...``, users that arrive at your +BinderHub URL will be directed to a login page. Once they enter their +credentials, they'll be taken to the typical BinderHub landing page. + +.. note:: + + If users *don't* go to a BinderHub landing page after they log-in, + then the configuration above is probably incorrect. Double-check that + the BinderHub configuration (and the JupyterHub authentication configuration) + look good. .. note:: For ``jupyterhub.auth`` you should use config of your authenticator. For more information you can check