From f154e0d93674ba3104c94b86ec164da07092f34c Mon Sep 17 00:00:00 2001 From: yuvipanda Date: Thu, 2 Aug 2018 12:25:03 -0700 Subject: [PATCH] Clarify generic authenticator setup documentation --- docs/topic/authenticator-configuration.rst | 64 +++++++++++++--------- 1 file changed, 38 insertions(+), 26 deletions(-) diff --git a/docs/topic/authenticator-configuration.rst b/docs/topic/authenticator-configuration.rst index 7c9d96f..af50c0a 100644 --- a/docs/topic/authenticator-configuration.rst +++ b/docs/topic/authenticator-configuration.rst @@ -18,28 +18,32 @@ can be used with TLJH. A number of them ship by default with TLJH: their password when they log in for the first time. Default authenticator used in TLJH. We try to have specific how-to guides & tutorials for common authenticators. Since we can not cover -everything, this guide shows you how to use any authenticator you want by using LDAPAuthenticator as an -example. +everything, this guide shows you how to use any authenticator you want with JupyterHub by following +the authenticator's documentation. -Configuring the authenticator -============================= +Setting authenticator properties +================================ -Some authenticators have unique configuration options. This section covers a -few common ones. +JupyterHub authenticators are customized by setting *traitlet properties*. In the authenticator's +documentation, you will find these are usually represented as: -LDAPAuthenticator -^^^^^^^^^^^^^^^^^ +.. code-block:: -LDAPAuthenticator's `documentation `_ -lists the various configuration options you can set for LDAPAuthenticator. You can set them -in TLJH with the following pattern: + c.. = + +You can set these with ``tljh-config`` with: .. code-block:: bash - sudo -E tljh-config set auth.. + sudo -E tljh-config set auth.. -When the documentation asks you to set ``LDAPAuthenticator.server_address`` to some -value, you can do that with the following command: +Example +------- + +LDAPAuthenticator's `documentation `_ +lists the various configuration options you can set for LDAPAuthenticator. +When the documentation asks you to set ``LDAPAuthenticator.server_address`` +to some value, you can do that with the following command: .. code-block:: bash @@ -52,23 +56,19 @@ Enabling the authenticator ========================== Once you have configured the authenticator as you want, you should then -enable it. We'll use the LDAPAuthenticator as an example, though the process -is similar for the other authenticators. +enable it. Usually, the documentation for the authenticator would ask you to add +something like the following to your ``jupyterhub_config.py`` to enable it: + +.. code-block:: python + + c.JupyterHub.authenticator_class = 'fully-qualified-authenticator-name' + +You can accomplish the same with ``tljh-config``: .. code-block:: bash sudo -E tljh-config set auth.type -For LDAPAuthenticator, the fully qualified name is ``ldapauthenticator.LDAPAuthenticator``. -This is the same name that the documentation `asks `_ -you to set ``c.JupyterHub.authenticator_class`` to. - -For LDAPAuthenticator, this would be: - -.. code-block:: bash - - sudo -E tljh-config set auth.type ldapauthenticator.LDAPAuthenticator - Once enabled, you need to reload JupyterHub for the config to take effect. .. code-block:: bash @@ -78,3 +78,15 @@ Once enabled, you need to reload JupyterHub for the config to take effect. Try logging in a separate incognito window to check if your configuration works. This lets you preserve your terminal in case there were errors. If there are errors, :ref:`troubleshooting/logs` should help you debug them. + +Example +------- + +From the `documentation `_ for +LDAPAuthenticator, we see that the fully qualified name is ``ldapauthenticator.LDAPAuthenticator``. +Assuming you have already configured it, the following commands enable LDAPAuthenticator. + +.. code-block:: bash + + sudo -E tljh-config set auth.type ldapauthenticator.LDAPAuthenticator + sudo -E tljh-config reload