Docs(tcloud): Update scheduler facade docs for OAuth (#3992)

Author: erindru

docs/cloud/features/scheduler/airflow.md

@@ -52,6 +52,10 @@ $ pip install tobiko-cloud-scheduler-facade[airflow]
 
 ### Connect Airflow to Tobiko Cloud
 
+First, provision an OAuth Client for Airflow to use by following the guide on how to [provision client credentials](../single_sign_on.md#provisioning-client-credentials).
+
+After provisioning the credentials, you can obtain the `Client ID` and `Client Secret` values for Airflow to use to connect to Tobiko Cloud.
+
 Next, add an Airflow [connection](https://airflow.apache.org/docs/apache-airflow/stable/howto/connection.html#creating-a-connection-with-the-ui) containing your Tobiko Cloud credentials.
 
 Specify these fields when adding the connection:
@@ -60,9 +64,8 @@ Specify these fields when adding the connection:
     - May not contain spaces, single quotes `'`, or double quotes `"`
 - **Connection Type**: always HTTP
 - **Host**: URL for your Tobiko Cloud project
-- **Password**: your Tobiko Cloud API token
-
-The host URL and password values will be provided to you during your Tobiko Cloud onboarding.
+- **Login**: OAuth `Client ID` for Airflow
+- **Password**: OAuth `Client Secret` for Airflow
 
 It is convenient to specify the connection in the Airflow UI, as in this example with the name `tobiko_cloud`:
 

docs/cloud/features/scheduler/airflow/add_connection.png

@@ -57,15 +57,18 @@ Dagster recommends [injecting secret values using Environment Variables](https:/
 
 On this page, we demonstrate the secrets method Dagster recommends for **local development**.
 
-In your Dagster project, create an `.env` file if it does not already exist. Next, specify environment variables containing the Tobiko Cloud URL and token secrets:
+First, provision an OAuth Client for Dagster to use by following the guide on how to [provision client credentials](../single_sign_on.md#provisioning-client-credentials).
+
+After provisioning the credentials, you can obtain the `Client ID` and `Client Secret` values for Dagster to use to connect to Tobiko Cloud.
+
+In your Dagster project, create an `.env` file if it does not already exist. Next, specify environment variables containing the Tobiko Cloud URL and OAuth secrets:
 
 ```sh title=".env"
-TOBIKO_CLOUD_BASE_URL=<URL for your Tobiko Cloud project> # ex: https://cloud.tobikodata.com/sqlmesh/tobiko/public-demo/
-TOBIKO_CLOUD_TOKEN=<your Tobiko Cloud API token> # ex: 'ioawjioefja1'
+TCLOUD_BASE_URL=<URL for your Tobiko Cloud project> # ex: https://cloud.tobikodata.com/sqlmesh/tobiko/public-demo/
+TCLOUD_CLIENT_ID=<your OAuth Client ID for Dagster> # ex: '5ad2938d-e607-489a-8bec-bdfb5924b79b'
+TCLOUD_CLIENT_SECRET=<your OAuth Client Secret for Dagster> # ex: 'psohFoOcgweYnbx-bmYn3XXRDSNIP'
 ```
 
-Your Solutions Architect will provide the base URL and token values during your Tobiko Cloud onboarding.
-
 ### Create Dagster objects
 
 You are now ready to create Dagster objects connected to Tobiko Cloud.
@@ -84,8 +87,9 @@ from dagster import EnvVar # for accessing variables in .env file
 
 # create and configure SQLMeshEnterpriseDagster instance named `sqlmesh`
 sqlmesh = SQLMeshEnterpriseDagster(
-    url=EnvVar("TOBIKO_CLOUD_BASE_URL").get_value(), # environment variable from .env file
-    token=EnvVar("TOBIKO_CLOUD_TOKEN").get_value(), # environment variable from .env file
+    url=EnvVar("TCLOUD_BASE_URL").get_value(), # environment variable from .env file
+    oauth_client_id=EnvVar("TCLOUD_CLIENT_ID").get_value(), # environment variable from .env file
+    oauth_client_secret=EnvVar("TCLOUD_CLIENT_SECRET").get_value(), # environment variable from .env file
 )
 
 # create Definitions object with `sqlmesh` object's `create_definitions()` method
@@ -186,8 +190,8 @@ Specifically, we must use Dagster's GraphQL API, which is not enabled by default
 
 ```python title="definitions.py" linenums="1" hl_lines="4 5"
 sqlmesh = SQLMeshEnterpriseDagster(
-    url=EnvVar("TOBIKO_CLOUD_BASE_URL").get_value(),
-    token=EnvVar("TOBIKO_CLOUD_TOKEN").get_value(),
+    url=EnvVar("TCLOUD_BASE_URL").get_value(),
+    #...SNIP...,
     dagster_graphql_host="localhost", # Example GraphQL host (could be passed in an environment variable instead)
     dagster_graphql_port=3000 # Example GraphQL port (could be passed in an environment variable instead)
 )
@@ -370,7 +374,8 @@ customer_revenue_by_day = AssetKey(["postgres", "sushi", "customer_revenue_by_da
 | Option                     | Description                                                                                                                                                                            | Type | Required |
 |----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----:|:--------:|
 | `url`                      | The Base URL to your Tobiko Cloud instance                                                                                                                                             | str  | Y        |
-| `token`                    | Your Tobiko Cloud API Token                                                                                                                                                            | str  | N        |
+| `oauth_client_id`          | OAuth Client ID of the credentials you [provisioned](../single_sign_on.md#provisioning-client-credentials) for Dagster                                                                 | str  | N        |
+| `oauth_client_secret`      | OAuth Client Secret of the credentials you [provisioned](../single_sign_on.md#provisioning-client-credentials) for Dagster                                                             | str  | N        |
 | `dagster_graphql_host`     | Hostname of the Dagster Webserver GraphQL endpoint                                                                                                                                     | str  | N        |
 | `dagster_graphql_port`     | Port of the Dagster Webserver GraphQL endpoint                                                                                                                                         | int  | N        |
 | `dagster_graphql_kwargs`   | Extra args to pass to the [DagsterGraphQLClient](https://docs.dagster.io/api/python-api/libraries/dagster-graphql#dagster_graphql.DagsterGraphQLClient) class when it is instantiated  | dict | N        |

docs/cloud/features/scheduler/dagster.md

@@ -153,7 +153,7 @@ $ tcloud auth status
 
 ### Login
 
-To initiliaze the login process you can run the `login` command:
+Run the `login` command to begin the login process:
 
 ``` bash
 $ tcloud auth login
@@ -193,3 +193,28 @@ Not currently authenticated
 ![tcloud_logout](./single_sign_on/tcloud_logout.png)
 
 Otherwise, you will be logged out automatically when the SSO session expires (every 24 hours). 
+
+## OAuth Clients
+
+Sometimes, you want to grant an external service access to your Tobiko Cloud project. For example, the external service could be the [CICD bot](../../integrations/github.md) or a [scheduler integration](./scheduler/airflow.md).
+
+These services take `Client ID` and `Client Secret` credentials.
+
+!!! Info "One set of credentials per service"
+    It's best practice to provision a separate set of credentials for each service that you wish to connect to Tobiko Cloud. This gives you the flexibility to revoke credentials for a specific service without affecting access for other services.
+
+### Provisioning client credentials
+
+To provision OAuth credentials for a new service, browse to `Settings -> OAuth Clients` in the lefthand navigation menu.
+
+In the page's Create new Client section, enter a client name and human readable description:
+
+![Add new OAuth Client](./single_sign_on/oauth_client_1.png)
+
+Once you click `Save`, the client will be added to the list:
+
+![OAuth Client List](./single_sign_on/oauth_client_2.png)
+
+To fetch the Client ID or Client Secret, click `Copy ID` or `Copy Secret`. The values will be copied to the system clipboard.
+
+Paste these values into an external service's authentication configuration so it can connect to your Tobiko Cloud project.