This is PR 2 of 2 split from the Google Workspace auth provider work. It
is stacked on #18160.
## Summary
Adds documentation for the new `@mastra/auth-google` package.
Included in this PR:
- `auth/google/README.md`.
- Server auth guide for Google Workspace authentication.
- API reference page for `MastraAuthGoogle` and `MastraRBACGoogle`.
- Auth overview link and docs/reference sidebar entries.
- Workspace setup, hosted-domain validation, service-account delegation,
Google Groups role mapping, and cross-provider RBAC usage documentation.
## Scope
Intentionally excluded from this PR:
- Package implementation, tests, lockfile, and changeset: handled in
#18160.
- Examples: no example changes are included.
## Verification
Relevant checks for this docs-only PR:
- `NODE_OPTIONS=--max-old-space-size=8192 pnpm --filter ./docs validate`
- `NODE_OPTIONS=--max-old-space-size=8192 pnpm --filter ./docs
lint:remark`
- `./node_modules/.bin/prettier --ignore-path /dev/null --check
docs/src/content/en/reference/auth/google.mdx
docs/src/content/en/docs/server/auth/google.mdx auth/google/README.md`
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This PR adds a new “help page” for signing users in with Google (Google
Workspace) and then controlling what they can do using Google Groups. It
explains how to set up Google, wire it into Mastra, and where to find
the API details.
### Summary
- Added full documentation for the new `@mastra/auth-google` package
(`auth/google/README.md`), including installation, required environment
variables, service-account key/delegation guidance, and exported
symbols.
- Added a new Google auth server guide page
(`docs/src/content/en/docs/server/auth/google.mdx`) covering:
- OAuth 2.0 / OIDC login flow and encrypted cookie-session behavior
- Google ID token verification
- Google Workspace hosted-domain enforcement
- Google Groups → RBAC role/permission mapping via `MastraRBACGoogle`
(including default behavior and wildcard permission patterns)
- Cross-provider RBAC usage with `getUserKey` role mapping
- Required prerequisites/scopes, multiple setup/usage examples,
authenticated request examples (SDK + cURL), a troubleshooting
checklist, and related links
- Client cookie-session/CORS guidance plus an alternative Bearer-token
flow using JWKS
- Added API reference documentation pages for `MastraAuthGoogle` and
`MastraRBACGoogle` (`docs/src/content/en/reference/auth/google.mdx`),
including configuration options, environment variables, method
signatures, and the `GoogleUser` type.
- Updated navigation/sidebar docs to include Google:
- Added “Google” to the server auth overview list
(`docs/src/content/en/docs/server/auth/index.mdx`)
- Inserted Google entry into the `server/auth` sidebar
(`docs/src/content/en/docs/sidebars.js`)
- Inserted Google entry into the Auth reference sidebar
(`docs/src/content/en/reference/sidebars.js`)
### Notes
- Docs-only change: no package implementation, tests, lockfile,
changeset, or examples were included.
- Validation ran on the updated docs (docs validation, remark linting,
and Prettier).
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
This is PR 1 of 2 split from the Google Workspace auth provider work. PR
#18161 contains the documentation changes.
## Summary
Adds the new `@mastra/auth-google` package under `auth/google`.
Included in this PR:
- `MastraAuthGoogle` for Google account authentication, optional SSO
session cookies, Bearer Google ID token verification, and Google
Workspace hosted-domain enforcement using the verified `hd` claim.
- `MastraRBACGoogle` for optional Google Workspace Groups to Mastra
permissions mapping.
- Package scaffold and tooling: `package.json`, `tsup`, `vitest`,
`eslint`, `turbo`, `CHANGELOG`, lockfile updates, and colocated unit
tests.
- Changeset for the initial `@mastra/auth-google` release. The repo is
in prerelease mode, so this will publish on the prerelease tag through
the normal changeset flow.
## Scope
Intentionally excluded from this PR:
- Docs pages and package README: handled in #18161.
- Examples: no example changes are included.
- Shared server auth refresh behavior: no server refresh handler changes
are included.
## Verification
Relevant local checks for this package:
- `NODE_OPTIONS=--max-old-space-size=8192 pnpm --filter ./auth/google
test`
- `NODE_OPTIONS=--max-old-space-size=8192 pnpm --filter ./auth/google
lint`
- `NODE_OPTIONS=--max-old-space-size=8192 pnpm --filter ./auth/google
build`
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This PR adds a new Google login package so apps can let people sign in
with Google accounts and, if needed, use Google Workspace groups to
decide what they’re allowed to do. It also adds the package setup,
tests, and release notes so it can be shipped on its own.
## What changed
- Added `@mastra/auth-google` under `auth/google`
- Introduced `MastraAuthGoogle` for:
- Google ID token auth
- optional SSO session cookies
- hosted-domain enforcement via the `hd` claim
- Introduced `MastraRBACGoogle` for:
- mapping Google Workspace groups to Mastra roles/permissions
- Directory API group lookup
- service-account-based access token flow
- permission caching and helper methods
- Added shared Google auth/RBAC types and a claim-to-user mapper
- Added package scaffolding:
- `package.json`
- `tsconfig*.json`
- `tsup.config.ts`
- `vitest.config.ts`
- `eslint.config.js`
- `lint-staged.config.js`
- `turbo.json`
- `CHANGELOG.md`
- Added tests for auth flow, session handling, hosted-domain checks,
RBAC lookup, caching, and helper methods
- Added a changeset for the initial package release
- Updated auth imports to use `@internal/auth` instead of `@mastra/core`
in this package
- Restored previous behavior for server refresh-miss responses in a
revert commit
## Verification
- `NODE_OPTIONS=--max-old-space-size=8192 pnpm --filter ./auth/google
test`
- `NODE_OPTIONS=--max-old-space-size=8192 pnpm --filter ./auth/google
lint`
- `NODE_OPTIONS=--max-old-space-size=8192 pnpm --filter ./auth/google
build`
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Abhi Aiyer <abhiaiyer91@gmail.com>