Google OAuth¶

This guide covers setting up Google OAuth2 authentication with OpenID Connect support.

Creating a Google OAuth Application¶

Go to the Google Cloud Console
Create a new project or select an existing one
Navigate to APIs & Services → OAuth consent screen
Configure the consent screen:
- Choose External for public apps or Internal for Google Workspace
- Fill in the required fields (App name, User support email, Developer contact)
- Add scopes: openid, email, profile
Navigate to APIs & Services → Credentials
Click Create Credentials → OAuth client ID
Select Web application as the application type
Add your redirect URI:
- For development: http://localhost:8000/auth/google/callback
- For production: https://yourdomain.com/auth/google/callback
Copy your Client ID and Client Secret

Available Scopes¶

Scope	Description
`openid`	Required for OpenID Connect authentication
`email`	Access to user’s email address
`profile`	Access to basic profile information (name, picture)
`https://www.googleapis.com/auth/calendar.readonly`	Read-only access to Google Calendar
`https://www.googleapis.com/auth/drive.readonly`	Read-only access to Google Drive

Usage Example¶

from litestar import Litestar
from litestar_oauth.contrib.litestar import OAuthPlugin, OAuthConfig

app = Litestar(
    plugins=[
        OAuthPlugin(
            config=OAuthConfig(
                redirect_base_url="https://example.com",
                google_client_id="your-client-id.apps.googleusercontent.com",
                google_client_secret="your-client-secret",
                google_scope="openid email profile",
            )
        )
    ],
)

from litestar_oauth.providers import GoogleOAuthProvider

provider = GoogleOAuthProvider(
    client_id="your-client-id.apps.googleusercontent.com",
    client_secret="your-client-secret",
    scope=["openid", "email", "profile"],
)

# Generate authorization URL
auth_url = provider.get_authorization_url(
    redirect_uri="https://example.com/auth/google/callback",
    state="random-state-token",
)

# After callback, exchange code for token
token = await provider.exchange_code(
    code="authorization-code",
    redirect_uri="https://example.com/auth/google/callback",
)

# Get user info
user_info = await provider.get_user_info(token.access_token)

User Info Response¶

The OAuthUserInfo object returned by Google contains:

OAuthUserInfo(
    provider="google",
    oauth_id="123456789012345678901",  # Google's unique user ID
    email="user@gmail.com",
    email_verified=True,
    username=None,  # Google doesn't provide username
    first_name="John",
    last_name="Doe",
    avatar_url="https://lh3.googleusercontent.com/a/...",
    profile_url=None,
    raw_data={...},  # Complete response from Google
)

OpenID Connect (OIDC)¶

Google fully supports OpenID Connect. When using the openid scope, the token response includes an id_token containing verified claims:

token = await provider.exchange_code(code, redirect_uri)
print(token.id_token)  # JWT containing user claims

Google Workspace Integration¶

For Google Workspace (formerly G Suite) users, you can restrict authentication to your organization’s domain:

auth_url = provider.get_authorization_url(
    redirect_uri="https://example.com/auth/google/callback",
    state="random-state-token",
    extra_params={"hd": "yourdomain.com"},
)

Troubleshooting¶

Error: redirect_uri_mismatch: The redirect URI in your request doesn’t match one of the authorized URIs in the Google Cloud Console. Make sure the URI matches exactly, including the protocol (http vs https) and trailing slashes.
Error: access_denied: The user denied the authorization request, or the app is not verified. For testing, add yourself as a test user in the OAuth consent screen.
Error: invalid_grant: The authorization code has expired or has already been used. Codes are single-use and expire after a few minutes.