Support native JupyterHub OAuthenticator in 2i2c-managed hubs

config/hubs/schema.yaml

@@ -158,7 +158,7 @@ properties:
               - basehub
               - daskhub
           auth0:
-            additionalProperties: false
+            additionalProperties: true
             type: object
             description: |
               All hubs use Auth0 for authentication, and we dynamically fetch the credentials
@@ -176,6 +176,7 @@ properties:
                   Authentication method users of the hub can use to log in to the hub.
                   We support a subset of the [connectors](https://auth0.com/docs/identityproviders)
                   that auth0 supports
+                required: false
               application_name:
                 type: string
                 description: |

deployer/hub.py

@@ -348,6 +348,7 @@ def get_generated_config(self, auth_provider: KeyProvider, secret_key):
             # FIXME: We're hardcoding Auth0OAuthenticator here
             # We should *not*. We need dictionary merging in code, so
             # these can all exist fine.
+            generated_config['jupyterhub']['hub']['config']['JupyterHub']['authenticator_class'] = 'CustomOAuthenticator'
             generated_config['jupyterhub']['hub']['config']['Auth0OAuthenticator'] = auth_provider.get_client_creds(client, self.spec['auth0']['connection'])
 
         return self.apply_hub_template_fixes(generated_config, secret_key)
@@ -427,13 +428,29 @@ def deploy(self, auth_provider, secret_key, skip_hub_health_test=False):
             subprocess.check_call(["helm", "dep", "up", "daskhub"])
         os.chdir("..")
 
+        # Check if this cluster has any secret config. If yes, read it in.
+        secret_config_path = Path(os.getcwd()) / "secrets/config/hubs" / f'{self.cluster.spec["name"]}.cluster.yaml'
+
+        if os.path.exists(secret_config_path):
+            with decrypt_file(secret_config_path) as decrypted_file_path:
+                with open(decrypted_file_path) as f:
+                    secret_config = yaml.load(f)
+
+            hubs = secret_config["hubs"]
+            secret_hub_config = next((hub for i, hub in enumerate(hubs) if hubs[i]["name"] == self.spec["name"]), {"config": {}})
+            secret_hub_config = secret_hub_config["config"]
+        else:
+            secret_hub_config = {}
+
         generated_values = self.get_generated_config(auth_provider, secret_key)
 
-        with tempfile.NamedTemporaryFile(mode='w') as values_file, tempfile.NamedTemporaryFile(mode='w') as generated_values_file:
+        with tempfile.NamedTemporaryFile(mode='w') as values_file, tempfile.NamedTemporaryFile(mode='w') as generated_values_file, tempfile.NamedTemporaryFile(mode='w') as secret_values_file:
             json.dump(self.spec['config'], values_file)
             json.dump(generated_values, generated_values_file)
+            json.dump(secret_hub_config, secret_values_file)
             values_file.flush()
             generated_values_file.flush()
+            secret_values_file.flush()
 
             cmd = [
                 'helm', 'upgrade', '--install', '--create-namespace', '--wait',
@@ -444,6 +461,7 @@ def deploy(self, auth_provider, secret_key, skip_hub_health_test=False):
                 # we should put the config from config/hubs last.
                 '-f', generated_values_file.name,
                 '-f', values_file.name,
+                '-f', secret_values_file.name,
             ]
 
             print(f"Running {' '.join(cmd)}")

docs/howto/configure/auth-management.md

@@ -1,6 +1,8 @@
 # Manage authentication
 
-[auth0](https://auth0.com) provides authentication for all hubs here. It can
+## Auth0
+
+[auth0](https://auth0.com) provides authentication for the majority of 2i2c hubs. It can
 be configured with many different [connections](https://auth0.com/docs/identityproviders)
 that users can authenticate with - such as Google, GitHub, etc.
 
@@ -38,19 +40,122 @@ So we want to manage authentication by:
    config:
      jupyterhub:
        auth:
-         # will be renamed allowedlist in future JupyterHub
-         whitelist:
-           users:
+         allowed_users:
              # WARNING: THESE USER LISTS MUST MATCH (for now)
              - user1@gmail.com
              - user2@gmail.com
-         admin:
-           users:
+         admin_users:
              # WARNING: THESE USER LISTS MUST MATCH (for now)
              - user1@gmail.com
              - user2@gmail.com
    ```
 
 ```{admonition} Switching auth
-Switching authentication for a pre-existing hub will simply create new usernames. Any pre-existing users will no longer be able to access their accounts (although administrators will be able to do so). If you have pre-existing users and want to switch the hub authentication, rename the users to the new auth pattern (e.g. convert github handles to emails).
-```
+Switching authentication providers (e.g. from GitHub to Google) for a pre-existing hub will simply create new usernames. Any pre-existing users will no longer be able to access their accounts (although administrators will be able to do so). If you have pre-existing users and want to switch the hub authentication, rename the users to the new auth pattern (e.g. convert github handles to emails).
+```
+
+## Native JupyterHub OAuthenticator for GitHub Orgs and Teams
+
+```{note}
+This setup is currently only supported for communities that **require** authentication via a GitHub organisation or team.
+
+We may update this policy in the future.
+```
+
+For communities that require authenticating users against [a GitHub organisation or team](https://docs.github.com/en/organizations), we instead use the [native JupyterHub OAuthenticator](https://github.com/jupyterhub/oauthenticator).
+Presently, this involves a few more manual steps than the `auth0` setup described above.
+
+1. **Create a GitHub OAuth App.**
+   This can be achieved by following [GitHub's documentation](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app).
+   - Use the "Switch account" button at the top of your settings page to make sure you have `2i2c-org` selected.
+     That way, the app will be owned by the `2i2c-org` GitHub org, rather than your personal GitHub account.
+   - When naming the application, please follow the convention `<CLUSTER_NAME>-<HUB_NAME>` for consistency, e.g. `2i2c-staging` is the OAuth app for the staging hub running on the 2i2c cluster.
+   - The Homepage URL should match that in the `domain` field of the appropriate `*.cluster.yaml` file in the `pilot-hubs` repo.
+   - The authorisation callback URL is the homepage url appended with `/hub/oauth_callback`. For example, `staging.pilot.2i2c.cloud/hub/oauth_callback`.
+   - Once you have created the OAuth app, make a new of the client ID, generate a client secret and then hold on to these values for a future step
+
+2. **Create or update the appropriate secret config file under `secrets/config/hubs/*.cluster.yaml`.**
+   You should add the following config to this file, pasting in the client ID and secret you generated in step 1.
+
+    ```yaml
+    hubs:
+    - name: HUB_NAME
+      config:
+        jupyterhub:
+          hub:
+            config:
+              GitHubOAuthenticator:
+                client_id: CLIENT_ID
+                client_secret: CLIENT_SECRET
+    ```
+
+    ````{note}
+    Add the `basehub` key between `config` and `jupyterhub` for `daskhub` deployments.
+    For example:
+
+    ```yaml
+    hubs:
+    - name: HUB_NAME
+      config:
+        basehub:
+          jupyterhub:
+            ...
+    ```
+    ````
+
+    ```{note}
+    Make sure this is encrypted with `sops` before committing it to the repository!
+
+    `sops -i -e secrets/config/hubs/*.cluster.yaml`
+    ```
+
+3. **Edit the non-secret config under `config/hubs`.**
+   You should make sure the matching hub config takes one of the following forms.
+
+   To authenticate against a GitHub organisation:
+
+    ```yaml
+    hubs:
+    - name: HUB_NAME
+      auth0:
+        enabled: false
+      ... # Other config
+      config:
+        jupyterhub:
+          hub:
+            config:
+              JupyterHub:
+                authenticator_class: github
+              GitHubOAuthenticator:
+                oauth_callback_url: https://{{ HUB_DOMAIN }}/hub/oauth_callback
+                allowed_organizations:
+                  - 2i2c-org
+                  - ORG_NAME
+                scope:
+                  - read:user
+    ```
+
+   To authenticate against a GitHub Team:
+
+    ```yaml
+    hubs:
+    - name: HUB_NAME
+      auth0:
+        enabled: false
+      ... # Other config
+      config:
+        jupyterhub:
+          hub:
+            config:
+              JupyterHub:
+                authenticator_class: github
+              GitHubOAuthenticator:
+                oauth_callback_url: https://{{ HUB_DOMAIN }}/hub/oauth_callback
+                allowed_organizations:
+                  - 2i2c-org:tech-team
+                  - ORG_NAME:TEAM_NAME
+                scope:
+                  - read:org
+    ```
+
+4. Run the deployer as normal to apply the config.

hub-templates/basehub/values.yaml

@@ -211,9 +211,6 @@ jupyterhub:
     image:
       name: quay.io/2i2c/pilot-hub
       tag: '0.0.1-n1159.h5b045cd'
-    config:
-      JupyterHub:
-        authenticator_class: oauthenticator.auth0.Auth0OAuthenticator
     nodeSelector:
       hub.jupyter.org/node-purpose: core
     networkPolicy:
@@ -317,8 +314,6 @@ jupyterhub:
               resp['name'] = resp['name'].split('|')[-1]
             return resp
 
-        c.JupyterHub.authenticator_class = CustomOAuthenticator
-
       07-cloud-storage-bucket: |
         from z2jh import get_config
         cloud_resources = get_config('custom.cloudResources')

secrets/config/hubs/schema.yaml

@@ -0,0 +1,24 @@
+$schema: 'http://json-schema.org/draft-07/schema#'
+type: object
+additionalProperties: false
+properties:
+  hubs:
+    type: array
+    description: |
+      Each item here is additional config for a hub deployed to this cluster.
+    required:
+      - name
+      - config
+    items:
+      - type: object
+        additionalProperties: false
+        properties:
+          name:
+            type: string
+            description: |
+              Name of the hub. This will be used to determine
+              the namespace the hub is deployed to
+          config:
+            type: object
+            description: |
+              YAML configuration containing secrets that is passed through to helm.