README edits for Authentication

jupyter-on-gke/README.md

@@ -36,13 +36,27 @@ Preinstall the following on your computer:
 
 3. Once the image is built, navigate to `ai-on-gke/jupyter-on-gke/`
 
-4. Edit `variables.tf` with your GCP settings. The `<your user name>` that you specify will become a K8s namespace for your Jupyterhub services.
+4. Edit `variables.tf` with your GCP settings. The `<your user name>` that you specify will become a K8s namespace for your Jupyterhub services. For more information about what the variabls do visit [here](https://github.com/GoogleCloudPlatform/ai-on-gke/blob/main/jupyter-on-gke/variable_definitions.md)
 **Important Note:**
 If using this with the Ray module (`ai-on-gke/ray-on-gke/`), it is recommended to use the same k8s namespace
 for both i.e. set this to the same namespace as `ai-on-gke/ray-on-gke/user/variables.tf`.
 If not, set `enable_create_namespace` to `true` so a new k8s namespace is created for the Jupyter resources.
-**Note:**
-We allow user to set their own domains, in the `variables.tf` file. Since we are also using an Ingress Object, it is required for the Ingress to also have specifiy the name of the global static address.
+
+5. If you have not enabled the IAP API before or created a Brand for your project, you can proceed to the next step. If not, ensure that the following variables within `variables.tf` are set:
+
+    * enable_iap_service - Enables the IAP service API. Leave as false if IAP is enabled before.
+    * brand - creates a brand for the project, only one is currently allowed per project. If there is already a brand, leave the variable empty.
+    * support_email - used by brand, required field.
+
+    **Note:**
+    We allow user to set their own domains, in the `variables.tf` file. Since we are also using an Ingress Object, it is required for the Ingress to also have specifiy the name of the global static address.
+    Visit the [GCloud UI](https://pantheon.corp.google.com/security/iap) to see if it's enabled. If it's enabled, you will be able to see the page and will not prompt you to enable API:
+
+    ![IAP API Screen](./images/iap_enable_api_screenshot.png)
+
+    And the `brand` page, if there is not brand created yet, will have:
+
+    ![IAP API Screen](./images/consent_screen_screenshot.png)
 
 5. Run `terraform init`
 
@@ -70,7 +84,9 @@ We allow user to set their own domains, in the `variables.tf` file. Since we are
 
 9. Run `terraform apply`
 
-## Authentication (Currently Enabled By Default)
+## Securing your Jupyter Endpoint
+
+To secure the Jupyter endpoint, this example enables IAP by default. It is _strongly recommended_ to keep this configuration. If you wish to disable it, do the following: set the `add_auth` flag to false in the `variable.tf` file.
 
 10. After installing Jupyterhub, you will need to retrieve the name of the backend-service from GCP using the following command:
 
@@ -100,9 +116,9 @@ We allow user to set their own domains, in the `variables.tf` file. Since we are
 
 1. Run `kubectl get services -n <namespace>`. The namespace is the user name that you specified above.
 
-2. Copy the external IP for the notebook.
+2. Copy the external IP for the notebook. If there isn't an external IP for `proxy-public`, is it most likely due to authencation being enabled.
 
-Continue to Step 3.
+Continue to Step 3 of [below](#if-auth-is-enabled).
 
 ### If Auth is enabled
 
@@ -116,20 +132,6 @@ Continue to Step 3.
 
 4. Select profile and open a Jupyter Notebook
 
-## Securing Your Cluster Endpoints
-
-If you have Authentication enabled, your endpoint is secured through GCP IAP.
-
-Otherwise:
-
-For demo purposes, this repo creates a public IP for the Jupyter notebook with basic dummy authentication. To secure your cluster, it is _strongly recommended_ to replace
-this with your own secure endpoints.
-
-For more information, please take a look at the following links:
-* https://cloud.google.com/iap/docs/enabling-kubernetes-howto
-* https://cloud.google.com/endpoints/docs/openapi/get-started-kubernetes-engine
-* https://jupyterhub.readthedocs.io/en/stable/tutorial/getting-started/authenticators-users-basics.html
-
 ## Running GPT-J-6B
 
 This example is adapted from Ray AIR's examples [here](https://docs.ray.io/en/master/ray-air/examples/gptj_serving.html).
@@ -152,28 +154,6 @@ This example is adapted from Ray AIR's examples [here](https://docs.ray.io/en/ma
 
 4. This should output a generated text response.
 
-## Logging and Monitoring
-
-This repository comes with out-of-the-box integrations with Google Cloud Logging
-and Managed Prometheus for monitoring. To see your Ray cluster logs:
-
-1. Open Cloud Console and open Logging
-
-2. If using Jupyter notebook for job submission, use the following query parameters:
-
-```unset
-resource.type="k8s_container"
-resource.labels.cluster_name=%CLUSTER_NAME%
-resource.labels.pod_name=%RAY_HEAD_POD_NAME%
-resource.labels.container_name="fluentbit"
-```
-
-To see monitoring metrics:
-
-1. Open Cloud Console and open Metrics Explorer
-2. In "Target", select "Prometheus Target" and then "Ray".
-3. Select the metric you want to view, and then click "Apply".
-
 ## Additional Information
 
 For more information about Jupyterhub profiles and the preset profiles visit [here](https://github.com/GoogleCloudPlatform/ai-on-gke/blob/main/jupyter-on-gke/profiles.md)

jupyter-on-gke/authentication/README.MD

@@ -1,9 +1,15 @@
-# GCP IAP Authenticator
+# GCP IAP Authentication
 
-We combine the Jupyterhub image and our own authenticator. By default, the JupyterHub images already have pre-installed authenticator classes such as GitHub, Auth0, and Globus. In order to specify our own class for JupyterHub, our class must also live in the JupyterHub image.
+- [Creating Image with Authentication for Jupyterhub](#creating-image)
+- [Authentication class and handler](#iapuserloginhandler-and-gcpiapauthenticator-class)
+- [Configuration details for jupyter config yaml](#configuration)
+- [Terraform variables and resources](#terraform-variables-and-resources)
+- [Allowlist for IAP](#allowlist-for-iap)
 
 ## Creating Image
 
+We combine the Jupyterhub image and our own authenticator. By default, the JupyterHub images already have pre-installed authenticator classes such as GitHub, Auth0, and Globus. In order to specify our own class for JupyterHub, our class must also live in the JupyterHub image.
+
 > **_NOTE:_** An Artifact Registry Repo for this docker image is required. Create an AR Repo following [this guide](https://cloud.google.com/artifact-registry/docs/repositories/create-repos)
 
 1. Setup gcloud to point to your project.
@@ -57,3 +63,91 @@ Fortuantely, few of these steps are already done for you if you follow the Jupyt
 There are two classes within `gcpiapjwtauthenticator.py`, IAPUserLoginHandler and GCPIAPAuthenticator.
 IAPUserLoginHandler is the python class that only has the JWT handler. It is used by the GCPIAPAuthenticator and therefore by Jupyterhub.
 GCPIAPAuthenticator contains the `get_handler()` method that Jupyterhub requires for a custom authenticator. When Jupyterhub uses the GCPIAPAuthenticator by calling `get_handler()`, it will receieve the `IAPUserLoginHandler.get()` handler method.
+
+## Terraform Variables and Resources
+
+There are a few variables required when enabling IAP Authentication:
+
+* [`add_auth`](#add_auth)
+* [`enable_iap_service`](#enable_iap_service)
+* [`brand`](#brand-and-support_email)
+* [`support_email`](#brand-and-support_email)
+
+### `add_auth`
+
+The `add_auth` variable enables IAP on the cluster and will trigger the creation of the following resources:
+
+* [Reserved IP address](#reserved-ip-address)
+* [Backend Config](#backend-config)
+* [Managed Certificate](#managed-certificate)
+* [Ingress](#ingress)
+* [Kubernetes Secret](#kubernetes-secret)
+
+#### Reserved IP address
+
+Reserves a Global IP Address for IAP. Used in the Ingress and the domain associated with the IP is used in the managed certificate
+
+#### Backend Config
+
+This deployment associates the IAP with the K8s secret and acts as the trigger that will enable the IAP service on the application.
+[Link to deployment](https://github.com/GoogleCloudPlatform/ai-on-gke/blob/main/jupyter-on-gke/iap_module/deployments/backend-config.yaml)
+
+#### Managed Certificate
+
+Google managed SSL certificate. Associates the IAP service with a doamin.
+[Link to deployment](https://github.com/GoogleCloudPlatform/ai-on-gke/blob/main/jupyter-on-gke/iap_module/deployments/managed-cert.yaml)
+
+#### Ingress
+
+Ingress for the Jupyterhub proxy-public application. Has the annotations:
+
+- kubernetes.io/ingress.global-static-ip-name
+- networking.gke.io/managed-certificates
+
+Both of which associates to the other deployments/resources created
+[Link to deployment](https://github.com/GoogleCloudPlatform/ai-on-gke/blob/main/jupyter-on-gke/iap_module/deployments/static-ingress.yaml)
+
+#### Kubernetes Secret
+
+Contains the OAuth Client information used by the Backend Config.
+
+### `enable_iap_service`
+
+By default, the IAP service is not enabled on the project. If this variable is set to `true` it will enable the IAP Service on the project
+
+### `brand` and `support_email`
+
+To create an OAuth client, a brand is required. The brand is essentially the app show on the [OAuth consent screen](https://pantheon.corp.google.com/apis/credentials/consent). Ex:
+
+![IAP Screen](../images/brand_screenshot.png)
+
+The `support_email` variable will not be used if the `brand` variable is not filled in and is left empty. It is a required field for creating a `brand` and acts as a point of contact for users to contact with questions about consent.
+
+## Allowlist for IAP
+
+There are 2 ways to add users to the IAP allowlist so users can access Jupyterhub.
+
+1. Manually on the GCloud UI
+2. Add users to the allowlist file
+
+### Manually
+
+Navigate to [IAP](https://pantheon.corp.google.com/security/iap) and select the Backend Service associated with Jupyterhub.
+
+Click on `Add Principal`. Add the email of the user/group and select the `IAP-secured Web App User` role to give access to that user/group
+
+![IAP Screen](../images/IAP_screenshot.png)
+
+### With Allowlist file
+
+We use terraform to automatically add principals to IAP. By filling out the `allowlist` file [here](https://github.com/GoogleCloudPlatform/ai-on-gke/blob/main/jupyter-on-gke/allowlist), terraform will give the principals the appropriate roles to access Jupyterhub. The file must follow the format of 1 principal per line.
+
+Example:
+
+```unset
+user:exampleuser@google.com
+user:exampleuser2@google.com
+serviceAccount:serviceaccount-compute@gserviceaccount.com
+group:jupyter-group@google.com
+serviceAccount:serviceaccount1234-compute@gserviceaccount.com
+```