@gzl10/nexus-plugin-google-auth

Google authentication plugin for Nexus BaaS. Adds login via Google using OpenID Connect.

Features

• OIDC Authorization Code Flow
• Auto-registration or manual account linking
• Google Workspace domain restriction (hd parameter)
• Email domain allowlist

Requirements

• @gzl10/nexus-backend >= 0.13.0
• @gzl10/nexus-sdk >= 0.13.0
• A Google Cloud project with OAuth 2.0 credentials

Installation

pnpm add @gzl10/nexus-plugin-google-auth

1. Configure Google Cloud

In the Google Auth Platform:

1. Go to Clients > Create Client > OAuth client ID
2. Set Application type: Web application
3. Add Authorized redirect URI: https://your-backend.com/api/v1/google_auth/callback
4. Download or copy the Client ID and Client Secret immediately

Important: Since June 2025, client secrets are masked after creation and cannot be retrieved later. Save them when you create the client.

The redirect URI must point to your Nexus backend's callback endpoint, not the frontend.

2. Configure Nexus

Add environment variables:

GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

Register the plugin in your backend:

import { start } from '@gzl10/nexus-backend'
import { googleAuthPlugin } from '@gzl10/nexus-plugin-google-auth'

await start({ plugins: [googleAuthPlugin] })

On first start, the plugin auto-seeds its configuration from the environment variables.

3. Frontend

The plugin registers an auth provider that nexus-ui picks up automatically. A "Sign in with Google" button appears on the login page.

For custom frontends, redirect users to:

GET /api/v1/google_auth/authorize?redirect_uri=https://your-frontend.com/login

After authentication, the backend redirects back with tokens in the URL fragment:

https://your-frontend.com/login#accessToken=...&refreshToken=...

On error:

https://your-frontend.com/login#error=Your+account+does+not+exist

Configuration

The plugin creates a google_auth_config table on first run. Options:

| Field | Default | Description | |-------|---------|-------------| | enabled | true | Enable/disable Google login | | hosted_domain | null | Restrict to a Google Workspace domain | | default_role | VIEWER | Role assigned to new users | | allowed_domains | null | JSON array of allowed email domains (null = all) | | scopes | openid profile email | OIDC scopes |

API Endpoints

| Method | Endpoint | Auth | Description | |--------|----------|------|-------------| | GET | /api/v1/google_auth/authorize | No | Start OIDC flow | | GET | /api/v1/google_auth/callback | No | Handle OIDC callback | | GET | /api/v1/google_auth/link | Yes | Link existing account | | GET | /api/v1/google_auth/status | Yes | Check if Google is linked |

License

MIT