diff --git a/adaptors/googledrive.md b/adaptors/googledrive.md index 6d17aeba691..78969c7b737 100644 --- a/adaptors/googledrive.md +++ b/adaptors/googledrive.md @@ -12,7 +12,18 @@ 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 { @@ -20,10 +31,32 @@ Google Drive uses OAuth 2.0 access tokens for API authentication: } ``` -**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. diff --git a/adaptors/googlehealthcare.md b/adaptors/googlehealthcare.md index 71723ed044e..d214adbe49b 100644 --- a/adaptors/googlehealthcare.md +++ b/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) diff --git a/adaptors/googlesheets.md b/adaptors/googlesheets.md index 5faf5e7ab7e..5e6caff9967 100644 --- a/adaptors/googlesheets.md +++ b/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 diff --git a/docs/build/credentials.md b/docs/build/credentials.md index 328b37160b2..b631a4eaaa9 100644 --- a/docs/build/credentials.md +++ b/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 diff --git a/static/img/googledrive-access-token.webp b/static/img/googledrive-access-token.webp new file mode 100644 index 00000000000..e994302ef95 Binary files /dev/null and b/static/img/googledrive-access-token.webp differ diff --git a/static/img/googledrive-oauth2.webp b/static/img/googledrive-oauth2.webp new file mode 100644 index 00000000000..bdc0bd73e5d Binary files /dev/null and b/static/img/googledrive-oauth2.webp differ diff --git a/static/img/googlehealthcare-access-token.webp b/static/img/googlehealthcare-access-token.webp new file mode 100644 index 00000000000..a18119d6c29 Binary files /dev/null and b/static/img/googlehealthcare-access-token.webp differ diff --git a/static/img/gsheets-oauth2.webp b/static/img/gsheets-oauth2.webp new file mode 100644 index 00000000000..35b3484dc97 Binary files /dev/null and b/static/img/gsheets-oauth2.webp differ