Improve Credentials page with platform-specific integration user guidance

adaptors/googledrive.md

@@ -12,18 +12,51 @@ title: Google Drive Adaptor
 
 ## Authentication
 
-Google Drive uses OAuth 2.0 access tokens for API authentication:
+Google Drive supports two credential types in OpenFn: **OAuth2** and a raw **access token**.
+
+### OAuth2
+
+For interactive workflows where a user authorizes access, you can connect via OAuth2. To authorize Google Drive for your OpenFn workflows, read our documentation on
+[using OAuth credentials](/documentation/build/credentials#use-oauth2-credentials).
+
+![Google Drive OAuth credential](/img/googledrive-oauth2.webp)
+
+### Access Token
+
+For workflows using a pre-generated access token (e.g. from a service account or Google Cloud Console), provide the token directly:
 
 ```json
 {
   "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjlGWERwYmZNRlQyU3ZRdVhoODQ2WVR3RUlCdyIsI"
 }
 ```
 
-**Authentication Components:**
-- **access_token**: OAuth 2.0 access token obtained through Google's authentication flow
+Access tokens provide scoped access to Google Drive resources based on the permissions granted during the OAuth flow.
+
+![Google Drive access token credential](/img/googledrive-access-token.webp)
+
+### Using a Google Service Account
+
+For automated, unattended workflows we recommend using a
+[Google Service Account](https://cloud.google.com/iam/docs/service-accounts-create)
+instead of a personal user OAuth credential. Service accounts are designed for
+machine-to-machine access and do not require a human login or interactive
+consent flow, making them more reliable and auditable for integration workflows.
+
+When setting up a service account for Google Drive:
+
+- Grant only the scopes your workflow requires, following the principle of
+  least privilege. See
+  [Google's documentation on OAuth scopes](https://developers.google.com/identity/protocols/oauth2/scopes#drive)
+  for the available Drive scopes.
+- Share the specific Drive folder(s) or file(s) with the service account's
+  email address (e.g. `my-service-account@my-project.iam.gserviceaccount.com`)
+  at the appropriate permission level (Viewer for read-only, Editor for write
+  access).
 
-Access tokens can be generated through Google Cloud Console and provide scoped access to Google Drive resources based on the permissions granted during the OAuth flow.
+See the [Credentials page](/documentation/build/credentials#creating-a-dedicated-integration-user-for-your-openfn-workflow)
+for broader guidance on why dedicated integration users and service accounts are
+recommended for all OpenFn workflows.
 
 
 

adaptors/googlehealthcare.md

@@ -25,6 +25,30 @@ See platform docs on [managing credentials](/documentation/manage-projects/manag
 }
 ```
 
+![Google Cloud Healthcare access token credential](/img/googlehealthcare-access-token.webp)
+
+### Using a Google Service Account
+
+For automated, unattended workflows we recommend using a
+[Google Service Account](https://cloud.google.com/iam/docs/service-accounts-create)
+to generate the access token rather than using a personal user credential.
+Service accounts are designed for machine-to-machine access, do not require a
+human login, and provide a clear audit trail which is particularly important for
+healthcare data integrations.
+
+When setting up a service account for Google Cloud Healthcare:
+
+- Grant only the IAM roles your workflow requires, following the principle of
+  least privilege. See
+  [Google Cloud IAM roles for Healthcare](https://cloud.google.com/healthcare-api/docs/access-control)
+  for the available roles.
+- Generate a short-lived access token from the service account to use as your
+  OpenFn credential, rather than a long-lived personal token.
+
+See the [Credentials page](/documentation/build/credentials#creating-a-dedicated-integration-user-for-your-openfn-workflow)
+for broader guidance on why dedicated integration users and service accounts are
+recommended for all OpenFn workflows.
+
 ### Helpful Links
 
 1. [Google Cloud Healthcare API Documentation](https://cloud.google.com/healthcare-api)

adaptors/googlesheets.md

@@ -16,6 +16,8 @@ default OpenFn Google OAuth client or choose to
 To authorize Google Sheets for your OpenFn workflows, read our documentation on
 [using OAuth credentials](/documentation/build/credentials#use-oauth2-credentials).
 
+![Google Sheets OAuth credential](/img/gsheets-oauth2.webp)
+
 :::info Google Oauth Client Setup Tips for Super Users
 
 Setting up your own generic OAuth client requires that you have an OAuth
@@ -48,6 +50,28 @@ for the latest information.
   need to use the full URL, e.g.,
   `https://www.googleapis.com/auth/spreadsheets`)
 
+### Using a Google Service Account
+
+For automated, unattended workflows we recommend using a
+[Google Service Account](https://cloud.google.com/iam/docs/service-accounts-create)
+instead of a personal user OAuth credential. Service accounts are designed for
+machine-to-machine access and do not require a human login or interactive
+consent flow, making them more reliable and auditable for integration workflows.
+
+When setting up a service account for Google Sheets:
+
+- Grant only the scopes your workflow requires, following the principle of
+  least privilege. See
+  [Google's documentation on OAuth scopes](https://developers.google.com/identity/protocols/oauth2/scopes#sheets)
+  for the available Sheets scopes.
+- Share the specific Google Sheet(s) with the service account's email address
+  (e.g. `my-service-account@my-project.iam.gserviceaccount.com`) at the
+  appropriate permission level (Viewer for read-only, Editor for write access).
+
+See the [Credentials page](/documentation/build/credentials#creating-a-dedicated-integration-user-for-your-openfn-workflow)
+for broader guidance on why dedicated integration users and service accounts are
+recommended for all OpenFn workflows.
+
 ## Integration Options
 
 There are a couple of primary ways to integrate with this app, each catering to

docs/build/credentials.md

@@ -77,7 +77,7 @@ Users of the hosted OpenFn platform SaaS can post on
 
 Note the credential selects only required scopes for Google Sheets.
 
-![Google OAuth](/img/google-oauth2.webp)
+![Google Sheets OAuth](/img/gsheets-oauth2.webp)
 
 #### e.g., Salesforce OAuth Credential
 
@@ -101,8 +101,11 @@ application.
 You _can_ use your personal user as an OpenFn credential for your
 workflow, but we recommend that you create a dedicated "OpenFn" integration user
 or service account user to access your target applications. For example, in
-Salesforce, you can create an API-only user with a special API-only license type
-to perform automated tasks and integrations without requiring full user access.
+[Salesforce](/adaptors/salesforce#salesforce-credentials), you can create an
+API-only user with a special API-only license type to perform automated tasks
+and integrations without requiring full user access. For Google APIs such as
+[Google Sheets](/adaptors/googlesheets#using-a-google-service-account), a
+Google Service Account is the recommended approach for automated workflows.
 
 API-only users might not be available in every target system, but many do offer the
 creation of user roles that have API-only access permissions, and may allow you