docs: add local setup, testing mode, scopes and troubleshooting to Google OAuth page#4517
docs: add local setup, testing mode, scopes and troubleshooting to Google OAuth page#4517pir-ahsan-raza wants to merge 9 commits into
Conversation
docs: improve Google OAuth single service page with local setup, scopes, and troubleshooting
✅ Deploy Preview for n8n-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
|
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
No issues found across 1 file
Architecture diagram
sequenceDiagram
participant User as Developer (Browser)
participant n8n as n8n Server
participant GConsole as Google Cloud Console
participant GAuth as Google OAuth Service
Note over User,GConsole: Phase 1: Configuration (NEWly documented)
User->>GConsole: Create Project & OAuth Client
User->>GConsole: NEW: Set Redirect URI (e.g., http://localhost:5678/...)
User->>GConsole: NEW: Configure Testing Mode & add Test Users
GConsole-->>User: Client ID & Client Secret
Note over User,n8n: Phase 2: n8n Credential Setup
User->>n8n: Input Client ID & Secret
User->>n8n: NEW: Define Minimum Required Scopes
n8n->>User: Redirect to Google Authorization URL
Note over User,GAuth: Phase 3: Runtime Authorization Flow
User->>GAuth: Authenticate with Google Account
alt NEW: Troubleshooting - Client Validation
GAuth->>GAuth: Check Client ID/Secret
opt invalid_client
GAuth-->>User: Error: Check for spaces or incorrect credentials
end
end
alt NEW: Troubleshooting - URI Validation
GAuth->>GAuth: Match request redirect_uri vs Registered URIs
opt redirect_uri_mismatch
GAuth-->>User: Error: Ensure n8n URL matches Console exactly
end
end
alt NEW: Troubleshooting - Testing Mode
GAuth->>GAuth: Verify if Account is in "Test Users" list
opt Access Denied / App Not Verified
GAuth-->>User: Error: User must be added to OAuth Consent screen
end
end
GAuth-->>User: Grant Authorization (Specific Scopes)
User->>n8n: Return Authorization Code
n8n->>GAuth: Exchange Code for Access Token
GAuth-->>n8n: Access Token (Scoped)
n8n-->>User: Connection Successful
RoRoJ
left a comment
RoRoJ
left a comment
There was a problem hiding this comment.
Thanks for your contribution! I've suggested moving this information around quite a bit to keep the doc tightly structured, and help users find the relevant information at the relevant step of the flow.
| By default, new Google Cloud projects are in **Testing** mode. In this mode, | ||
| only accounts you manually add as test users can complete the OAuth flow — | ||
| everyone else will see an "app not verified" or access denied screen. | ||
|
|
||
| To add test users: | ||
|
|
||
| 1. Open the [Google Cloud Console](https://console.cloud.google.com/). | ||
| 2. Go to **APIs & Services** > **OAuth consent screen**. | ||
| 3. Scroll down to the **Test users** section. | ||
| 4. Select **Add users** and enter the Gmail address(es) you want to allow. | ||
|
|
||
| Refer to [Google's consent screen guide](https://developers.google.com/workspace/guides/configure-oauth-consent) | ||
| for more detail on test users. |
There was a problem hiding this comment.
I think we can avoid adding this as a whole new section by referencing it in an admonition under step 5 of ## Configure your OAuth consent screen. Then simply link to the existing troubleshooting which we can enrich with some more information. For example:
/// note | Testing mode and test users
If you select External, your app will default to Testing mode. In this mode, only Google accounts you manually add as test users can complete the OAuth flow - everyone else will see an "access denied" screen. See Google hasn't verified this app to learn how to add them.
///
...and modify the second bullet point in the troubleshooting to take into account adding other users who are getting the warning message as testers. Also include the "When to publish" admonition.
| You can find the full list of available scopes for each Google service in the | ||
| [OAuth 2.0 Scopes for Google APIs](https://developers.google.com/identity/protocols/oauth2/scopes) reference. | ||
|
|
||
| ## Troubleshooting |
There was a problem hiding this comment.
This whole section should be merged into the existing Troubleshooting section.
| Testing mode is usually fine. | ||
| /// | ||
|
|
||
| ## OAuth scopes |
There was a problem hiding this comment.
I'm not sure this is relevant here in the single service credential page, as the user never sees or configures the scopes, n8n just requests what it needs for that specific service. It could go here as an admonition/warning.
Incidentally, I think the info about test users and the redirect URL for self hosters should be added in the oauth generic doc too, to keep them both up to date and symmetrical.
|
Hi @pir-ahsan-raza, did you get a chance to look at my suggestions? |
RoRoJ
added
author:community
Sorry for the delay, applying your suggestions now. |
Applied all your suggestions. restructured the admonitions, merged the troubleshooting sections, and removed the standalone local dev and scopes sections. Let me know if anything needs adjusting. |
3 participants
Closes #3235
The Google OAuth single service page didn't cover a few things that
commonly confuse new users, so I added some missing sections.
What I added:
Links to the relevant Google docs are included throughout. Let me know if
anything needs changing.
Summary by cubic
Expanded and restructured the Google OAuth single‑service docs to make local setup and debugging easier. Adds localhost redirect URI setup (no domain/SSL needed), testing mode with test users and when to publish, minimal scope guidance, and troubleshooting for redirect_uri_mismatch, app not verified/access denied, and invalid_client.
Written for commit 5332d6e. Summary will update on new commits. Review in cubic