Download the PHP package impression/laravel-google-passport-oauth without Composer

Laravel Google Passport OAuth

Exchange Google OAuth access tokens for Laravel Passport personal access tokens. Enables seamless authentication from external applications (like better-chatbot) to your Laravel MCP server.

Features

• ✅ Validate Google OAuth tokens
• ✅ Refresh expired tokens server-side
• ✅ Find existing users by email (pre-provisioning required)
• ✅ Issue Passport personal access tokens
• ✅ OAuth 2.1 MCP HTTP Registry Integration — Register organization OAuth metadata for Alexis discovery
• ✅ Fallback Authentication — Seamlessly fallback to parent app authentication when Google token unavailable
• ✅ Confirmation Workflow — Simple confirmation page for org OAuth connection registration
• ✅ Configurable per-app (column mapping, domain whitelist)
• ✅ No auto-user-creation (prevents account enumeration)
• ✅ Rate limiting built-in (60 requests/minute)
• ✅ Comprehensive error handling with specific status codes
• ✅ Full test coverage (18 passing tests)

Installation

Step 1: Install via Composer

Step 2: Publish Configuration

This creates config/google-oauth.php with sensible defaults.

Step 3: Set Environment Variables

Add to .env:

Step 4: Ensure Users Table Has Required Columns

If you need to store Google user IDs, add a migration:

Run migrations:

MCP OAuth 2.1 Registry Setup

This package supports OAuth 2.1 MCP HTTP Registry integration, allowing organizations to register protected resource metadata (PRM), authorization servers, and callback URLs for Alexis discovery. End users still sign in separately via their MCP connections (PKCE); org-level metadata is static and managed server-side.

Step 1: Publish MCP Migrations

Step 2: Set MCP Environment Variables

Add to .env:

Step 3: Run Migrations

This creates the mcp_oauth_connections table for storing org-level OAuth metadata.

Step 4: Register MCP Routes (Optional)

If you want to expose MCP endpoints in your parent app, update routes/api.php or routes/web.php:

Configuration

The package exposes configuration in config/google-oauth.php:

Column Mapping

If your users table uses different column names:

Domain Whitelist

Restrict authentication to specific email domains:

Only users with email addresses ending in these domains can authenticate. Leave empty/null to allow all domains.

Usage

Google OAuth Token Exchange (Existing Flow)

Authentication Flow

1. External app (e.g., chatbot) obtains Google OAuth token from user
2. External app sends token to your Laravel endpoint: POST /oauth/google-token
3. Your package validates token with Google, finds user by email
4. Your package issues Passport personal access token
5. External app uses Passport token for subsequent API calls

HTTP Endpoint

POST /oauth/google-token

Request

Parameters:

• access_token (required): Google OAuth access token
• refresh_token (optional): Google OAuth refresh token (used if access token is expired)

Success Response (200 OK)

Use the access_token as a Bearer token in subsequent API requests:

Error Responses

400 Bad Request — Validation failed

401 Unauthorized — Token invalid, expired, or user not found

Other 401 errors:

• token_expired: Token is expired (no refresh token provided)
• user_not_found: User email not in database
• domain_not_allowed: User email domain not whitelisted

503 Service Unavailable — Google API error

MCP OAuth 2.1 Registry Flow (New)

The MCP OAuth 2.1 flow allows organizations to register OAuth metadata for protected resource discovery. Organizations authenticate via either Google OAuth or fallback to parent app authentication, then register their OAuth 2.1 server details.

Authentication Flow

1. Organization user is already authenticated in parent app (Laravel session)
2. Organization user calls MCP endpoints without Google token (fallback to parent auth)
3. Package middleware checks parent app session via configured guard
4. Package issues Passport token for the authenticated user
5. Organization visits confirmation page to review and register OAuth metadata
6. Organization submits OAuth 2.1 metadata (PRM, authorization server URL, callback URL)
7. Package stores metadata in mcp_oauth_connections table
8. Alexis queries discovery endpoint to find registered OAuth configurations

MCP Token Exchange Endpoint

POST /oauth/mcp/token

This endpoint accepts both Google tokens and relies on parent app authentication.

Request (with Google token):

Request (fallback to parent app auth):

Success Response (200 OK)

MCP Confirmation Endpoint

GET /oauth/mcp/confirm

Shows existing MCP OAuth connections and prompts for new metadata.

Request

Success Response (200 OK)

MCP Connection Registration Endpoint

POST /oauth/mcp/connections

Register a new OAuth 2.1 connection for the organization.

Request

Parameters:

• connection_name (required): Friendly name for this OAuth connection
• authorization_server_url (required): URL of the OAuth 2.1 authorization server
• callback_url (required): Redirect URI for OAuth callback
• protected_resource_metadata (optional): JSON with scopes, endpoints, etc.
• oauth_client_id (optional): Static OAuth 2.1 client ID
• oauth_client_secret (optional): Static OAuth 2.1 client secret (encrypted server-side)

Success Response (201 Created)

Error Responses

401 Unauthorized

422 Unprocessable Entity — Validation failed

Integrating with Parent Laravel Application

To integrate this package as a sub-package in a larger Laravel application:

1. Install and Configure

2. Set Environment Variables

3. Register Routes in Parent App

In your parent app's routes/api.php:

4. Access MCP Models in Your App

5. Share User Model Configuration

Ensure your parent app's User model is properly configured:

6. Trusted Proxies (If Behind Load Balancer)

If your parent app is behind a load balancer, configure config/trustedproxy.php to properly detect authenticated sessions.

User Provisioning

Users must exist in your database before authenticating. The package does not auto-create users to prevent account enumeration attacks.

Provisioning Workflow

1. Add user to database (via admin panel, bulk import, or migration):

2. User authenticates via POST /oauth/google-token
3. Package validates email matches (finds user)
4. Package issues Passport token

Pre-provisioning at Scale

For bulk onboarding:

Security Considerations

Production Checklist

• ✅ Use HTTPS only (enforce via middleware or load balancer)
• ✅ Store credentials in .env (never commit to version control)
• ✅ Pre-provision users carefully (audit logging recommended)
• ✅ Monitor rate limiting (/oauth/google-token max 60 requests/minute per IP)
• ✅ Use domain whitelist in production
• ✅ Rotate Google OAuth credentials regularly

How It Works

1. No token storage — Tokens validated in-memory, never persisted
2. Server-side refresh — If token expired but refresh token provided, package refreshes silently
3. Email-based lookup — User identity determined by email (not Google ID)
4. Pre-provisioning only — Prevents account enumeration
5. Signed Passport tokens — Subsequent API calls verified with Passport

Configuration Per Application

Each Laravel app using this package can customize the configuration independently:

MCP Server (config/google-oauth.php):

Internal App (config/google-oauth.php):

Partner Portal (config/google-oauth.php):

Testing

Running Tests

Test Coverage

• 18 tests passing (9 skipped for Passport integration)
• Unit tests for token validation and user resolution
• Feature tests for controller behavior
• Integration tests for end-to-end flow
• HTTP mocking for Google API (no external dependencies)

Writing Integration Tests

In your app, add integration tests:

Quality Checks

The package includes code quality tools:

All quality gates pass:

• ✅ Pint (0 style issues)
• ✅ PHPStan (0 errors)
• ✅ PHPUnit (18 passing tests)

Troubleshooting

"User not found" (401)

• Verify user exists: User::where('email', '[email protected]')->first()
• Check column mapping: GOOGLE_OAUTH_EMAIL_COLUMN
• Verify email matches exactly (case-sensitive)

"Domain not allowed" (401)

• Check whitelist: config('google-oauth.domain_whitelist')
• Verify user's email domain is whitelisted
• To disable: GOOGLE_OAUTH_DOMAIN_WHITELIST= (empty value)

"Token expired" (401)

• Provide refresh_token in request body
• Ensure Google OAuth credentials are correct
• Verify token is actually expired (check expires_in)

"Service unavailable" (503)

• Check Google API status: https://status.cloud.google.com
• Verify GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET
• Check network connectivity to https://www.googleapis.com

Tests Failing

• Ensure Composer dev dependencies installed: composer install
• Run with clean cache: vendor/bin/phpunit --no-coverage
• Check for mocking issues: Review Http::fake() setup in test

API Reference

GoogleTokenValidator

Validates Google OAuth tokens and handles refresh logic.

UserSyncResolver

Finds users by email with domain whitelist enforcement.

Exceptions

All exceptions extend GoogleOAuthException:

License

MIT

Contributing

Contributions welcome! Please ensure:

• Tests pass: vendor/bin/phpunit
• Code style passes: vendor/bin/pint src tests
• Static analysis passes: vendor/bin/phpstan analyse src

Support

For issues and questions, please open an issue on GitHub or contact the Impression team.