GSC OAuth Flow in OpenSEO: Required Scopes and Implementation Guide

OpenSEO requires four Google OAuth 2.0 scopes—openid, email, profile, and https://www.googleapis.com/auth/webmasters.readonly—defined in src/shared/gsc.ts as the GSC_OAUTH_SCOPES constant to authenticate users and access Google Search Console data.

OpenSEO leverages Google's OAuth 2.0 protocol to establish secure connections with Google Search Console accounts. The GSC OAuth flow in OpenSEO is architected to request minimal read-only permissions while maintaining consistent configuration across client and server environments.

Required OAuth Scopes for GSC Integration

The application requests four specific scopes during the Google Search Console authorization process. These permissions are consolidated in the GSC_OAUTH_SCOPES array exported from src/shared/gsc.ts【/cache/repos/github.com/every-app/open-seo/main/src/shared/gsc.ts#L6-L11】.

• openid: Enables OpenID Connect authentication to verify the user's identity.
• email: Grants read-only access to the primary email address associated with the Google account.
• profile: Provides read-only access to basic profile information including name and profile picture.
• https://www.googleapis.com/auth/webmasters.readonly: Allows read-only access to Google Search Console data and site verification status.

Identity and Profile Scopes

The first three scopes—openid, email, and profile—establish the user's identity within the OpenSEO platform. These standard OpenID Connect scopes ensure that OpenSEO can associate GSC data with the correct user account while displaying relevant profile information in the dashboard interface.

Data Access Scope

The webmasters.readonly scope is the functional permission that enables OpenSEO to retrieve search performance metrics, indexing status, and site verification information from Google Search Console. This read-only restriction ensures that OpenSEO cannot modify site settings, submit URLs for indexing, or alter any GSC configurations on behalf of users.

Implementation Architecture

The GSC OAuth flow in OpenSEO spans both client and server environments, utilizing centralized constants to maintain configuration consistency.

Centralized Configuration in src/shared/gsc.ts

The source of truth for OAuth configuration resides in src/shared/gsc.ts. According to the OpenSEO source code, this file exports two critical constants:

• GSC_OAUTH_PROVIDER_ID: Set to "google-search-console" (lines 4-5), identifies the provider throughout the authentication pipeline【/cache/repos/github.com/every-app/open-seo/main/src/shared/gsc.ts#L4-L5】.
• GSC_OAUTH_SCOPES: An array containing the four required scope strings (lines 6-11)【/cache/repos/github.com/every-app/open-seo/main/src/shared/gsc.ts#L6-L11】.

Client-Side Flow Initiation

In src/client/features/integrations/startGoogleLink.ts, the client application imports these constants to construct the authorization URL【/cache/repos/github.com/every-app/open-seo/main/src/client/features/integrations/startGoogleLink.ts#L10-L15】. The code joins the GSC_OAUTH_SCOPES array into a space-delimited string as required by Google's OAuth implementation.

Server-Side Provider Registration

The server configuration in src/lib/auth-config.ts imports these same constants to register the Google Search Console provider within the authentication system【/cache/repos/github.com/every-app/open-seo/main/src/lib/auth-config.ts#L6-L8】. This ensures that callback handling and token exchange operations use identical scope definitions as the client-side initiation.

Code Examples

The following examples demonstrate how OpenSEO implements the GSC OAuth flow using the shared constants.

Building the Authorization URL

When initiating the connection from the client side, OpenSEO constructs the OAuth URL using the scopes defined in src/shared/gsc.ts:

import { GSC_OAUTH_PROVIDER_ID, GSC_OAUTH_SCOPES } from '@/shared/gsc';

export function getGoogleOAuthUrl(redirectUri: string): string {
  const base = 'https://accounts.google.com/o/oauth2/v2/auth';
  const params = new URLSearchParams({
    client_id: process.env.GOOGLE_CLIENT_ID!,
    redirect_uri: redirectUri,
    response_type: 'code',
    scope: GSC_OAUTH_SCOPES.join(' '),
    state: JSON.stringify({ providerId: GSC_OAUTH_PROVIDER_ID }),
    access_type: 'offline',
    prompt: 'consent',
  });

  return `${base}?${params.toString()}`;
}

This implementation ensures that the scope parameter contains all four required permissions: openid email profile https://www.googleapis.com/auth/webmasters.readonly.

Server-Side Provider Configuration

The server-side authentication configuration registers the GSC provider using the identical constants:

import { GSC_OAUTH_PROVIDER_ID, GSC_OAUTH_SCOPES } from '@/shared/gsc';
import { ProviderConfig } from '@/lib/auth-config';

export const gscProvider: ProviderConfig = {
  providerId: GSC_OAUTH_PROVIDER_ID,
  clientId: process.env.GOOGLE_CLIENT_ID!,
  clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
  authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
  tokenUrl: 'https://oauth2.googleapis.com/token',
  scopes: GSC_OAUTH_SCOPES,
};

This configuration is consumed by src/server/features/google/selfHostedOAuth.ts for self-hosted deployments and by src/server/lib/gscClient.ts for subsequent API interactions after authentication.

Summary

• OpenSEO requires four OAuth scopes to connect with Google Search Console: openid, email, profile, and webmasters.readonly.
• The GSC_OAUTH_SCOPES constant in src/shared/gsc.ts serves as the single source of truth for permission configuration across the entire application.
• The provider identifier google-search-console (exported as GSC_OAUTH_PROVIDER_ID) links the permission set to the correct authentication provider.
• Both client-side (src/client/features/integrations/startGoogleLink.ts) and server-side (src/lib/auth-config.ts) implementations reference these shared constants to ensure scope consistency.
• The read-only webmasters scope ensures OpenSEO can retrieve search performance data without obtaining write access to site configurations.

Frequently Asked Questions

What permissions does OpenSEO request for Google Search Console access?

OpenSEO requests four OAuth scopes defined in src/shared/gsc.ts: openid for identity verification, email for account identification, profile for basic user information, and https://www.googleapis.com/auth/webmasters.readonly for accessing Search Console data. These are consolidated in the GSC_OAUTH_SCOPES array and requested whenever a user initiates the "Connect Google" flow.

Why does OpenSEO use the webmasters.readonly scope instead of the full webmasters scope?

The webmasters.readonly scope provides read-only access to Google Search Console data, which is sufficient for OpenSEO's functionality of analyzing search performance and indexing status. This restricted scope follows the principle of least privilege, ensuring the application cannot modify site configurations, request indexing, or alter any GSC settings on behalf of users.

Where are the GSC OAuth scopes defined in the OpenSEO codebase?

All Google Search Console OAuth scopes are defined in src/shared/gsc.ts as the exported constant GSC_OAUTH_SCOPES. This centralization ensures that both the client-side integration code in src/client/features/integrations/startGoogleLink.ts and the server-side authentication configuration in src/lib/auth-config.ts use identical permission sets.

How does OpenSEO handle OAuth authentication for self-hosted deployments?

For self-hosted instances, OpenSEO implements the OAuth flow in src/server/features/google/selfHostedOAuth.ts using the same GSC_OAUTH_SCOPES and GSC_OAUTH_PROVIDER_ID constants from src/shared/gsc.ts. The server-side flow handles the authorization code exchange and stores tokens securely, while src/server/lib/gscClient.ts manages API calls using the obtained access tokens scoped exclusively to read-only GSC data.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}