Skip to content

Commit

Permalink
Merge pull request jupyterhub#515 from choldgraf/auh
Browse files Browse the repository at this point in the history
small updates to auth docs
  • Loading branch information
willingc authored Feb 28, 2018
2 parents 1616599 + 252b671 commit e0c42ef
Showing 1 changed file with 53 additions and 16 deletions.
69 changes: 53 additions & 16 deletions doc/source/authentication.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.

.. code-block:: yaml
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.

auth:
type: google
google:
clientId: "yourlongclientidstring.apps.googleusercontent.com"
clientSecret: "adifferentlongstring"
callbackUrl: "http://<your_jupyterhub_host>/hub/oauth_callback"
hostedDomain: "youruniversity.edu"
loginService: "Your University"
To create OAuth credentials on GitHub, follow these steps:

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
Expand All @@ -52,8 +46,49 @@ The org_whitelist is optional and will require the use to accept the read:org gi
clientId: "y0urg1thubc1ient1d"
clientSecret: "an0ther1ongs3cretstr1ng"
callbackUrl: "http://<your_jupyterhub_host>/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::

``auth.scopes`` is optional.
Without this members of an organisation must `set their membership to Public <https://help.github.com/articles/publicizing-or-hiding-organization-membership/>`_ to login.
If this is set to ``read:org`` private members can login, but users must grant JupyterHub `additional privileges <https://developer.github.com/apps/building-oauth-apps/scopes-for-oauth-apps/>`_ to read some private information.
Changing ``auth.scopes`` will not change the scope for existing OAuth tokens, you must invalidate them.


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://<your_jupyterhub_host>/hub/oauth_callback"
hostedDomain: "youruniversity.edu"
loginService: "Your University"
CILogon
^^^^^^^
Expand Down Expand Up @@ -120,6 +155,8 @@ and obtain the confidential client credentials.
userdata_params: {'state': 'state'}
username_key: preferred_username
.. _google_oauth:

Full Example of Google OAuth2
-----------------------------

Expand Down

0 comments on commit e0c42ef

Please sign in to comment.