Add google service-accounts user guidance on credential page

adaptors/googledrive.md

@@ -4,38 +4,96 @@ title: Google Drive Adaptor
 
 ## About Google Drive
 
-[Google Drive](https://www.google.com/drive/) is Google's cloud-based file storage and synchronization service that allows users to store files online and access them from any computer or mobile device. Google Drive provides secure cloud storage, real-time collaboration capabilities, and seamless integration with Google Workspace applications including Docs, Sheets, and Slides.
+[Google Drive](https://www.google.com/drive/) is Google's cloud-based file
+storage and synchronization service that allows users to store files online and
+access them from any computer or mobile device. Google Drive provides secure
+cloud storage, real-time collaboration capabilities, and seamless integration
+with Google Workspace applications including Docs, Sheets, and Slides.
 
 ## Integration Options
 
-**REST API**: Google Drive provides comprehensive REST APIs through the Google Drive API, enabling developers to create, read, update, and manage files and folders programmatically. The API supports OAuth 2.0 authentication and provides access to metadata, content manipulation, and sharing permissions management.
+**REST API**: Google Drive provides comprehensive REST APIs through the Google
+Drive API, enabling developers to create, read, update, and manage files and
+folders programmatically. The API supports OAuth 2.0 authentication and provides
+access to metadata, content manipulation, and sharing permissions management.
 
 ## Authentication
 
-Google Drive uses OAuth 2.0 access tokens for API authentication:
+Google Drive authentication requires an access token, which can be obtained in
+two ways: via a [Google Service Account](#google-service-account-recommended)
+(recommended) or via [OAuth2](#oauth2) using a personal Google account.
+
+### Google Service Account (Recommended)
+
+We strongly recommend using a
+[Google Service Account](https://cloud.google.com/iam/docs/service-accounts-create)
+for production workflows. A service account is a dedicated, non-personal Google
+identity designed for machine-to-machine access — similar to an API-only user in
+Salesforce. It does not require anyone to log in with their personal Gmail
+account, and it won't break if someone changes their password or loses access.
+
+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).
+
+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.
+
+### OAuth2
+
+OpenFn has a built-in **GoogleDrive** OAuth credential type that handles the
+OAuth 2.0 flow for you. This works with any Google user account — personal Gmail
+or Google Workspace — but keep in mind the integration is tied to whichever
+account completes the authorization. If that person's access is revoked or they
+leave the organization, the integration will break.
+
+To authorize Google Drive using OAuth2, read our documentation on
+[using OAuth credentials](/documentation/build/credentials#use-oauth2-credentials).
+
+![Google Drive OAuth credential](/img/googledrive-oauth2.webp)
+
+### Access Token (Local Testing Only)
+
+For local development and testing, you can generate a short-lived access token
+(valid for 1 hour) using the `gcloud` CLI and provide it directly:
+
+```bash
+gcloud auth print-access-token
+```
+
+Then set it as your credential:
 
 ```json
 {
   "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjlGWERwYmZNRlQyU3ZRdVhoODQ2WVR3RUlCdyIsI"
 }
 ```
 
-**Authentication Components:**
-- **access_token**: OAuth 2.0 access token obtained through Google's authentication flow
-
-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.
-
+![Google Drive access token credential](/img/googledrive-access-token.webp)
 
+This approach is not suitable for production as the token expires quickly and
+must be manually refreshed.
 
 ## Helpful Links
 
-
 - [Google Drive API Documentation](https://developers.google.com/drive/api)
 - [OpenFn Google Drive Adaptor Configuration](https://docs.openfn.org/adaptors/packages/googledrive-configuration-schema)
 - [OpenFn Google Drive Adaptor Docs](https://docs.openfn.org/adaptors/packages/googledrive-docs)
 
 ### I've noticed a problem with this Adaptor, or something is out of date, what can I do?
 
-Thanks for asking! We are a fully Open Source Digital Public Good, and we welcome contributions from our community. Check out our [Adaptors Wiki](https://github.com/OpenFn/adaptors/blob/main/wiki/index.md) for more information on how you can update Adaptors!
+Thanks for asking! We are a fully Open Source Digital Public Good, and we
+welcome contributions from our community. Check out our
+[Adaptors Wiki](https://github.com/OpenFn/adaptors/blob/main/wiki/index.md) for
+more information on how you can update Adaptors!
 
-Or, you can always reach out to the Community through our [Community Forum here](https://community.openfn.org/).
+Or, you can always reach out to the Community through our
+[Community Forum here](https://community.openfn.org/).

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
+
+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
+
+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