Merge pull request #470 from clkao/auth-oidc

Add keycloak odic auth config example.

doc/source/authentication.rst

@@ -83,6 +83,38 @@ tape archive, public cloud, or your own laptop. Start a Globus app
           callbackUrl: "https://<your_jupyterhub_host>/hub/oauth_callback"
           identityProvider: "youruniversity.edu"
 
+OpenID Connect
+^^^^^^^^^^^^^^
+
+`OpenID Connect <https://openid.net/connect>`_ is an identity layer on top of the
+OAuth 2.0 protocol, implemented by
+`various servers and services <https://openid.net/developers/certified/#OPServices>`_.
+While OpenID Connect endpoint discovery is not supported by oauthentiator,
+you can still configure JupyterHub to authenticate with OpenID Connect providers
+by specifying all endpoints in GenericOAuthenticator.
+
+Here's an example for authenticating against `keycloak <http://www.keycloak.org/docs/3.4/securing_apps/index.html#endpoints>`_,
+after you `configure an OIDC Client <http://www.keycloak.org/docs/3.4/server_admin/index.html#oidc-clients>`_
+and obtain the confidential client credentials.
+
+.. code-block:: yaml
+
+      hub:
+        extraEnv:
+          OAUTH2_AUTHORIZE_URL: https://${host}/auth/realms/${realm}/protocol/openid-connect/auth
+          OAUTH2_TOKEN_URL: https://${host}/auth/realms/${realm}/protocol/openid-connect/token
+      auth:
+        type: custom
+        custom:
+          className: oauthenticator.generic.GenericOAuthenticator
+          config:
+            client_id: "y0urc1logonc1ient1d"
+            client_secret: "an0ther1ongs3cretstr1ng"
+            token_url: https://${host}/auth/realms/${realm}/protocol/openid-connect/token
+            userdata_url: https://${host}/auth/realms/${realm}/protocol/openid-connect/userinfo
+            userdata_method: GET
+            userdata_params: {'state': 'state'}
+            username_key: preferred_username
 
 Full Example of Google OAuth2
 -----------------------------