[Documentation] Recommend OAuth instead of PAT (#4787)

## Changes
- Recommend OAuth instead of PAT

## Tests
<!-- 
How is this tested? Please see the checklist below and also describe any
other relevant tests
-->

- [x] relevant change in `docs/` folder

---------

Co-authored-by: Alex Ott <[email protected]>

Author: nkvuong

NEXT_CHANGELOG.md

@@ -14,6 +14,8 @@
 * auto `zone_id` can only be used for fleet node types in `databricks_instance_pool` resource ([#4782](https://github.com/databricks/terraform-provider-databricks/pull/4782)).
 * Document `tags` attribute in `databricks_pipeline` resource ([#4783](https://github.com/databricks/terraform-provider-databricks/pull/4783)).
 
+* Recommend OAuth instead of PAT in guides ([#4787](https://github.com/databricks/terraform-provider-databricks/pull/4787))
+
 ### Exporter
 
 ### Internal Changes

docs/guides/aws-workspace.md

@@ -278,20 +278,11 @@ resource "databricks_mws_workspaces" "this" {
   credentials_id           = databricks_mws_credentials.this.credentials_id
   storage_configuration_id = databricks_mws_storage_configurations.this.storage_configuration_id
   network_id               = databricks_mws_networks.this.network_id
-
-  token {
-    comment = "Terraform"
-  }
 }
 
 output "databricks_host" {
   value = databricks_mws_workspaces.this.workspace_url
 }
-
-output "databricks_token" {
-  value     = databricks_mws_workspaces.this.token[0].token_value
-  sensitive = true
-}
 ```
 
 ### Data resources and Authentication is not configured errors
@@ -310,12 +301,13 @@ In [the next step](workspace-management.md), please use the following configurat
 
 ```hcl
 provider "databricks" {
-  host  = module.e2.workspace_url
-  token = module.e2.token_value
+  host          = module.e2.workspace_url
+  client_id     = var.client_id
+  client_secret = var.client_secret
 }
 ```
 
-We assume that you have a terraform module in your project that creates a workspace (using [Databricks Workspace](#databricks-workspace) section) and you named it as `e2` while calling it in the **main.tf** file of your terraform project. And `workspace_url` and `token_value` are the output attributes of that module. This provider configuration will allow you to use the generated token to authenticate to the created workspace during workspace creation.
+We assume that you have a terraform module in your project that creates a workspace (using [Databricks Workspace](#databricks-workspace) section) and you named it as `e2` while calling it in the **main.tf** file of your terraform project and `workspace_url` is the output attribute of that module. This provider configuration will allow you to authenticate to the created workspace after workspace creation.
 
 ### Credentials validation checks errors
 

docs/guides/gcp-private-service-connect-workspace.md

@@ -125,23 +125,13 @@ resource "databricks_mws_workspaces" "this" {
     connectivity_type = "PRIVATE_NODE_PUBLIC_MASTER"
     master_ip_range   = "10.3.0.0/28"
   }
-
-  token {
-    comment = "Terraform"
-  }
-
   # this makes sure that the NAT is created for outbound traffic before creating the workspace
   depends_on = [google_compute_router_nat.nat]
 }
 
 output "databricks_host" {
   value = databricks_mws_workspaces.this.workspace_url
 }
-
-output "databricks_token" {
-  value     = databricks_mws_workspaces.this.token[0].token_value
-  sensitive = true
-}
 ```
 
 ### Data resources and Authentication is not configured errors

docs/guides/gcp-workspace.md

@@ -225,22 +225,13 @@ resource "databricks_mws_workspaces" "this" {
 
   network_id = databricks_mws_networks.this.network_id
 
-  token {
-    comment = "Terraform"
-  }
-
   # this makes sure that the NAT is created for outbound traffic before creating the workspace
   depends_on = [google_compute_router_nat.nat]
 }
 
 output "databricks_host" {
   value = databricks_mws_workspaces.this.workspace_url
 }
-
-output "databricks_token" {
-  value     = databricks_mws_workspaces.this.token[0].token_value
-  sensitive = true
-}
 ```
 
 -> The `gke_config` argument and the `gke_cluster_service_ip_range` and `gke_pod_service_ip_range` arguments in `gcp_managed_network_config` are now deprecated and no longer supported. Omit these when creating workspaces in the future. If you have already created a workspace using these fields, it is safe to remove them from your Terraform template.
@@ -261,12 +252,13 @@ In [the next step](workspace-management.md), please use the following configurat
 
 ```hcl
 provider "databricks" {
-  host  = module.dbx_gcp.workspace_url
-  token = module.dbx_gcp.token_value
+  host          = module.dbx_gcp.workspace_url
+  client_id     = var.client_id
+  client_secret = var.client_secret
 }
 ```
 
-We assume that you have a terraform module in your project that creates a workspace (using [Databricks Workspace](#creating-a-databricks-workspace) section), and you named it as `dbx_gcp` while calling it in the **main.tf** file of your terraform project. And `workspace_url` and `token_value` are the output attributes of that module. This provider configuration will allow you to use the generated token to authenticate to the created workspace during workspace creation.
+We assume that you have a terraform module in your project that creates a workspace (using [Databricks Workspace](#creating-a-databricks-workspace) section), and you named it as `dbx_gcp` while calling it in the **main.tf** file of your terraform project and `workspace_url` is the output attribute of that module. This provider configuration will allow you to authenticate to the created workspace after workspace creation.
 
 ### More than one authorization method configured error
 

docs/index.md

@@ -262,6 +262,8 @@ resource "databricks_group" "cluster_admin" {
 
 ### Authenticating with hostname and token
 
+~> Databricks strongly recommends using OAuth instead of PATs for user account client authentication and authorization due to the improved security OAuth has
+
 You can use `host` and `token` parameters to supply credentials to the workspace. When environment variables are preferred, then you can specify `DATABRICKS_HOST` and `DATABRICKS_TOKEN` instead. Environment variables are the second most recommended way of configuring this provider.
 
 ``` hcl

docs/resources/mws_workspaces.md

@@ -85,13 +85,6 @@ resource "databricks_mws_workspaces" "this" {
   credentials_id           = databricks_mws_credentials.this.credentials_id
   storage_configuration_id = databricks_mws_storage_configurations.this.storage_configuration_id
   network_id               = databricks_mws_networks.this.network_id
-
-  token {}
-}
-
-output "databricks_token" {
-  value     = databricks_mws_workspaces.this.token[0].token_value
-  sensitive = true
 }
 ```
 
@@ -201,20 +194,13 @@ resource "databricks_mws_workspaces" "this" {
   credentials_id           = databricks_mws_credentials.this.credentials_id
   storage_configuration_id = databricks_mws_storage_configurations.this.storage_configuration_id
 
-  token {}
-
   # Optional Custom Tags
   custom_tags = {
 
     "SoldToCode" = "1234"
 
   }
 }
-
-output "databricks_token" {
-  value     = databricks_mws_workspaces.this.token[0].token_value
-  sensitive = true
-}
 ```
 
 In order to create a [Databricks Workspace that leverages AWS PrivateLink](https://docs.databricks.com/administration-guide/cloud-configurations/aws/privatelink.html) please ensure that you have read and understood the [Enable Private Link](https://docs.databricks.com/administration-guide/cloud-configurations/aws/privatelink.html) documentation and then customise the example above with the relevant examples from [mws_vpc_endpoint](mws_vpc_endpoint.md), [mws_private_access_settings](mws_private_access_settings.md) and [mws_networks](mws_networks.md).
@@ -264,13 +250,6 @@ resource "databricks_mws_workspaces" "this" {
   }
 
   network_id = databricks_mws_networks.this.network_id
-
-  token {}
-}
-
-output "databricks_token" {
-  value     = databricks_mws_workspaces.this.token[0].token_value
-  sensitive = true
 }
 ```
 
@@ -304,13 +283,6 @@ resource "databricks_mws_workspaces" "this" {
       project_id = data.google_client_config.current.project
     }
   }
-
-  token {}
-}
-
-output "databricks_token" {
-  value     = databricks_mws_workspaces.this.token[0].token_value
-  sensitive = true
 }
 ```
 
@@ -338,9 +310,11 @@ The following arguments are available:
 * `pricing_tier` - (Optional) - The pricing tier of the workspace.
 * `compute_mode` - (Optional) - The compute mode for the workspace. When unset, a classic workspace is created, and both `credentials_id` and `storage_configuration_id` must be specified. When set to `SERVERLESS`, the resulting workspace is a serverless workspace, and `credentials_id` and `storage_configuration_id` must not be set. The only allowed value for this is `SERVERLESS`. Changing this field requires recreation of the workspace.
 
-### token block
+~> Databricks strongly recommends using OAuth instead of PATs for user account client authentication and authorization due to the improved security
+
+### token block (legacy)
 
-You can specify a `token` block in the body of the workspace resource, so that Terraform manages the refresh of the PAT token for the deployment user. The other option is to create [databricks_obo_token](obo_token.md), though it requires Premium or Enterprise plan enabled as well as more complex setup. Token block exposes `token_value`, that holds sensitive PAT token and optionally it can accept two arguments:
+You can specify a `token` block in the body of the workspace resource, so that Terraform manages the refresh of the PAT token for the deployment user. Token block exposes `token_value`, that holds sensitive PAT token and optionally it can accept two arguments:
 
 -> Tokens managed by `token {}` block are recreated when expired.