From 83d36b60ebce1273ab0afaa229b582477b6026c8 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Wed, 21 Feb 2018 19:33:13 -0800 Subject: [PATCH 1/4] small updates to auth --- doc/source/authentication.rst | 52 ++++++++++++++++++++++++----------- 1 file changed, 36 insertions(+), 16 deletions(-) diff --git a/doc/source/authentication.rst b/doc/source/authentication.rst index fcd875ddcc..b6b35344ca 100644 --- a/doc/source/authentication.rst +++ b/doc/source/authentication.rst @@ -21,28 +21,22 @@ declare the values in the helm chart (``config.yaml``). Here are example configurations for common authentication services. Note that in each case, you need to get the authentication credential information -before you can configure the helmchart for authentication. +before you can configure the helm chart for authentication. -Google +GitHub ^^^^^^ -For more information see the full example of Google OAuth2 in the next section. +GitHub is the largest hub for git repositories. It is free to create an account +at GitHub, and relatively straightforward to set up OAuth credentials so that +users can authenticate with their GitHUb username/password. -.. code-block:: yaml +To create OAuth credentials on GitHub, follow these steps: - auth: - type: google - google: - clientId: "yourlongclientidstring.apps.googleusercontent.com" - clientSecret: "adifferentlongstring" - callbackUrl: "http:///hub/oauth_callback" - hostedDomain: "youruniversity.edu" - loginService: "Your University" - -GitHub -^^^^^^ +* Click your profile picture -> settings -> developer settings +* Make sure you're on the "OAuth Apps" tab, then click "New OAuth App" +* Fill out the forms (you'll need your hub address) and generate your ID/Secret. -The org_whitelist is optional and will require the use to accept the read:org github oath scope when logging in. +Below is the structure to use in order to authenticate with GitHub. .. code-block:: yaml @@ -55,6 +49,30 @@ The org_whitelist is optional and will require the use to accept the read:org gi org_whitelist: - "SomeOrgName" + +.. note:: + + The org_whitelist is optional and will require users to accept the read:org github oath scope when logging in. + +Google +^^^^^^ + +Google authentication is used by many universities (it is part of the "G Suite"). +Note that using Google authentication requires your Hub to have a domain name +(it cannot **only** be accessible via an IP address). +For more information on authenticating with Google oauth, see the :ref:`google_oauth`. + +.. code-block:: yaml + + auth: + type: google + google: + clientId: "yourlongclientidstring.apps.googleusercontent.com" + clientSecret: "adifferentlongstring" + callbackUrl: "http:///hub/oauth_callback" + hostedDomain: "youruniversity.edu" + loginService: "Your University" + CILogon ^^^^^^^ @@ -120,6 +138,8 @@ and obtain the confidential client credentials. userdata_params: {'state': 'state'} username_key: preferred_username +.. _google_oauth: + Full Example of Google OAuth2 ----------------------------- From 9a946df98a34378fb3c884f8a1def15dd1e3db69 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Thu, 22 Feb 2018 09:39:31 -0800 Subject: [PATCH 2/4] fixing typo --- doc/source/authentication.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/source/authentication.rst b/doc/source/authentication.rst index b6b35344ca..ceb159c372 100644 --- a/doc/source/authentication.rst +++ b/doc/source/authentication.rst @@ -52,7 +52,8 @@ Below is the structure to use in order to authenticate with GitHub. .. note:: - The org_whitelist is optional and will require users to accept the read:org github oath scope when logging in. + The org_whitelist is optional and will require users to accept the read:org github OAuth scope when + logging in. Google ^^^^^^ From 52e732d92b005bb9fb45d384a03aee52c13eedc2 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Thu, 22 Feb 2018 10:16:54 -0800 Subject: [PATCH 3/4] improving language around github orgs in auth --- doc/source/authentication.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/source/authentication.rst b/doc/source/authentication.rst index ceb159c372..7c8f1942f6 100644 --- a/doc/source/authentication.rst +++ b/doc/source/authentication.rst @@ -52,8 +52,9 @@ Below is the structure to use in order to authenticate with GitHub. .. note:: - The org_whitelist is optional and will require users to accept the read:org github OAuth scope when - logging in. + The ``org_whitelist`` section is optional, it lets you only allow users from particular GitHub + organizations that you list. Enabling it will require users to accept the read:org github OAuth scope when + logging in. If it is *not* included, then all GitHub users will be allowed to access your JupyterHub. Google ^^^^^^ From 818b6884e1a6e873af50534a09cadeb95570ca86 Mon Sep 17 00:00:00 2001 From: Simon Li Date: Mon, 26 Feb 2018 16:57:20 +0000 Subject: [PATCH 4/4] Explain auth.github.org_whitelist --- doc/source/authentication.rst | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/doc/source/authentication.rst b/doc/source/authentication.rst index 7c8f1942f6..10055b110f 100644 --- a/doc/source/authentication.rst +++ b/doc/source/authentication.rst @@ -46,15 +46,30 @@ Below is the structure to use in order to authenticate with GitHub. clientId: "y0urg1thubc1ient1d" clientSecret: "an0ther1ongs3cretstr1ng" callbackUrl: "http:///hub/oauth_callback" + + +By default this will allow *any* GitHub user to access your JupyterHub. +You can restrict access to members of one or more GitHub organisations. + +.. code-block:: yaml + + auth: + type: github + github: + ... org_whitelist: - "SomeOrgName" + scopes: + - "read:org" .. note:: - The ``org_whitelist`` section is optional, it lets you only allow users from particular GitHub - organizations that you list. Enabling it will require users to accept the read:org github OAuth scope when - logging in. If it is *not* included, then all GitHub users will be allowed to access your JupyterHub. + ``auth.scopes`` is optional. + Without this members of an organisation must `set their membership to Public `_ to login. + If this is set to ``read:org`` private members can login, but users must grant JupyterHub `additional privileges `_ to read some private information. + Changing ``auth.scopes`` will not change the scope for existing OAuth tokens, you must invalidate them. + Google ^^^^^^