Download the PHP package emmanuel-saleem/social-auth without Composer

Emmanuel Saleem Social Auth Package

A comprehensive Laravel package for OAuth social authentication with Google and Microsoft, supporting both traditional web applications and modern SPA/API-based frontends.

📚 Table of Contents

• Features
• Requirements
• Installation
• Quick Start - Add Login to Your App ⭐
• Configuration
• Usage (Web & API)
• Customization
• Troubleshooting
• Documentation

✨ Features

• 🔐 Google OAuth authentication (Web & API)
• 🔐 Microsoft OAuth authentication (Web & API)
• 🌐 Dual Mode Support: Traditional web and SPA/API applications
• 🎨 Pre-built Login UI with beautiful, modern design
• 📱 Mobile-friendly responsive design
• 🔄 Auto-migration for adding social auth fields to users table
• 🛡️ Flexible Authentication: Support for both Laravel Sanctum and Laravel Passport
• 🔑 Token Management: Automatic token generation with expiration support
• 📦 Easy Installation with Laravel auto-discovery
• ⚙️ Highly Configurable: routes, middleware, redirects, button labels, and more
• 🚀 Production Ready with comprehensive error handling
• 📊 Standardized API Responses with consistent JSON format

📋 Requirements

• PHP 8.0 or higher
• Laravel 8.x, 9.x, 10.x or 11.x
• Laravel Socialite 4.x (for Laravel 8) or 5.x (for Laravel 9+)
• Laravel Sanctum (for API authentication - default) OR Laravel Passport (optional)

📦 Installation

Step 1: Install via Composer

For Development (Current Available Version):

Alternative Installation Methods:

📝 Note: The package is currently in development. Stable versions will be available after publishing to Packagist. Use dev-master for now.

Step 2: Install Authentication System (for API routes)

Option A: Laravel Sanctum (Recommended - Default)

Option B: Laravel Passport (For OAuth2 Server)

📖 See PASSPORT_SETUP.md for detailed Passport configuration

Step 3: Add HasApiTokens to User Model

For Sanctum (Default):

For Passport:

Then configure the driver in .env:

Step 4: Publish Package Assets

⚙️ Configuration

Environment Variables

Add these to your .env file:

Update config/services.php

Add OAuth provider configurations:

OAuth Provider Setup

Google Cloud Console

Follow these steps to create OAuth credentials:

Step 1: Go to Google Cloud Console

Step 2: Create a new project or select an existing one

Step 3: Navigate to "APIs & Services" → "Credentials"

Step 4: Click "CREATE CREDENTIALS" → Select "OAuth client ID"

Step 5: Configure the OAuth consent screen (if first time)

Step 6: Select "Web application" as the application type

Step 7: Add your application name and authorized redirect URIs:

Authorized redirect URIs:

• For Web: http://localhost:8000/emmanuel-saleem/social-auth/google/callback
• For API/SPA: http://localhost:3000/auth/google/callback
• For Production: https://yourdomain.com/emmanuel-saleem/social-auth/google/callback

Step 8: Click "CREATE" and you'll receive your credentials

Step 9: Copy the Client ID and Client Secret to your .env file

Step 10: Enable required APIs (Google+ API or People API)

✅ Configuration Complete! Now add the credentials to your .env file:

Microsoft Azure Portal

Follow these detailed steps to set up Microsoft OAuth authentication:

Step 1: Access Azure Portal

1. Go to Azure Portal
2. Sign in with your Microsoft account

Step 2: Navigate to App Registrations

1. In the Azure portal, search for "App registrations" in the search bar
2. Click on "App registrations" from the search results

Step 3: Create New App Registration

1. Click "New registration" button
2. Fill in the application details:
   • Name: Enter your application name (e.g., "Laravel Social Auth")
   • Supported account types: Choose based on your needs:
     • "Personal Microsoft accounts only" - for consumer apps
     • "Accounts in any organizational directory and personal Microsoft accounts" - for broader access
   • Redirect URI: Add your callback URL:
     • Web: http://localhost:8000/emmanuel-saleem/social-auth/microsoft/callback
     • API: http://localhost:3000/auth/microsoft/callback

Step 4: Configure Authentication

1. After creating the app, go to "Authentication" in the left menu
2. Add your redirect URIs:
   • http://localhost:8000/emmanuel-saleem/social-auth/microsoft/callback
   • https://yourdomain.com/emmanuel-saleem/social-auth/microsoft/callback (for production)

Step 5: Create Client Secret

1. Go to "Certificates & secrets" in the left menu
2. Click "New client secret"
3. Add a description and choose expiration period
4. Important: Copy the secret value immediately (it won't be shown again)

Step 6: Configure API Permissions

1. Go to "API permissions" in the left menu
2. Click "Add a permission"
3. Select "Microsoft Graph"
4. Choose "Delegated permissions"
5. Add these permissions:
   • openid
   • profile
   • email
   • User.Read
   • offline_access

Step 7: Grant Admin Consent

1. Click "Grant admin consent" button
2. Confirm the permissions

Step 8: Get Your Credentials

1. Go to "Overview" in the left menu
2. Copy the following values:
   • Application (client) ID
   • Directory (tenant) ID (if using specific tenant)

Step 9: Update Your .env File Add the Microsoft credentials to your .env file:

Important Notes:

• For Personal Microsoft accounts only, use MICROSOFT_TENANT_ID=consumers
• For All account types, you can use MICROSOFT_TENANT_ID=common or leave it empty
• Make sure your redirect URI matches exactly what you configured in Azure
• The client secret expires based on your chosen expiration period

🚀 Quick Start - Add Login to Your App

How to Add Google & Microsoft Login

After installation, you have 3 easy ways to add social login to your application:

Method 1: Use the Pre-built Login Page (Easiest)

Simply redirect users to the package's built-in login page:

Visit: http://localhost:8000/emmanuel-saleem/social-auth/login

The page will show beautiful Google and Microsoft login buttons automatically! ✨

Method 2: Include the Component in Your Own Page

Add the social auth buttons to any existing page:

That's it! Both Google and Microsoft buttons will appear with icons and proper styling.

Method 3: Create Your Own Custom Buttons

Use the package routes directly for full customization:

Logout Button

Add a logout button anywhere in your app:

🎯 What Happens After Login?

1. User clicks "Sign in with Google" or "Sign in with Microsoft"
2. Redirects to Google/Microsoft for authentication
3. User approves the login request
4. Redirects back to your app with user data
5. Package automatically:
   • Creates a new user (if doesn't exist)
   • Updates existing user info
   • Logs them in
   • Redirects to dashboard (configurable)

User is now logged in! 🎉

Access logged-in user anywhere:

🌐 Complete Web Integration Guide

Step-by-Step: Add Social Login to Your Laravel Web App

Step 1: Create Your Login Page

Create or update your login blade file at resources/views/auth/login.blade.php:

Step 2: Create a Route for Login Page

Add to routes/web.php:

Step 3: Update Your Welcome Page (Optional)

Add a login button to resources/views/welcome.blade.php:

Step 4: Create a Dashboard Page

Create resources/views/dashboard.blade.php:

Step 5: Add Dashboard Route

Add to routes/web.php:

🧪 Testing Your Social Login

Test 1: Visit Login Page

Expected Result:

• ✅ See a beautiful login page
• ✅ Two buttons: "Continue with Google" and "Continue with Microsoft"
• ✅ Buttons have official brand colors and icons

Test 2: Click "Continue with Google"

What Happens:

1. Redirects to Google login page
2. Google asks for permission
3. You approve
4. Redirects back to your app
5. Package creates/updates user
6. Logs you in automatically
7. Redirects to /dashboard (configurable)

Check Database:

Test 3: Check User Data in Dashboard

Visit: http://localhost:8000/dashboard

Expected Result:

• ✅ See welcome message with your name
• ✅ See your Google profile picture
• ✅ See your email
• ✅ See "Google OAuth" as login method
• ✅ See Google ID

Test 4: Test Logout

Click the "Logout" button

Expected Result:

• ✅ Logged out successfully
• ✅ Redirected to home page
• ✅ Can't access /dashboard anymore

Test 5: Test Microsoft Login

Follow same steps but click "Continue with Microsoft"

Expected Result:

• ✅ Redirects to Microsoft login
• ✅ User created with microsoft_id
• ✅ Redirected to dashboard

🔍 Debugging & Verification

Check Routes Are Loaded

Expected Output:

Check Database Table

Should show the social auth migration as completed.

Should show columns:

• google_id
• microsoft_id
• avatar
• google_token
• google_refresh_token
• microsoft_token
• microsoft_refresh_token

Check Logged-in User

In any controller or view:

📸 Quick Test Checklist

• [ ] Login page displays correctly
• [ ] Google button works and redirects
• [ ] Microsoft button works and redirects
• [ ] User is created in database
• [ ] User data (name, email, avatar) is saved
• [ ] User is automatically logged in
• [ ] Dashboard shows user info
• [ ] Logout works correctly
• [ ] Can login again after logout
• [ ] Avatar/profile picture displays

🎨 Customize Redirect After Login

In .env file:

Or in config/emmanuel-saleem-social-auth.php:

🚀 Usage

Option 1: Traditional Web Application

Routes Available

The package automatically registers these web routes:

Implementation

Option A: Use the built-in login page

Simply redirect users to the login page:

Option B: Include the component in your own page

The package provides a reusable Blade component that you can include anywhere:

Option C: Use individual buttons

Logout

Option 2: API / SPA Application (React, Vue, Next.js)

For modern frontend applications, use the API endpoints.

Frontend Login Flow

Step 1: User clicks "Sign in with Google" button

Step 2: Get the OAuth URL from backend:

Step 3: Handle the callback when user returns:

Step 4: Use the token for authenticated requests:

For complete React/Vue examples, see USAGE_EXAMPLES.md

Next.js example pages

Add these pages to your Next.js app for a quick end-to-end test with this package's API endpoints.

app/(public)/auth/google/callback/page.tsx

app/(public)/oauth-test/page.tsx

API Routes Available

Quick Start Example (React)

📖 For complete API integration guide, see OAUTH_API_GUIDE.md

📡 API Response Format

All API endpoints return standardized JSON responses:

Success Response

Error Response

🎨 Customization

Customize Button Labels

You can customize the button text via .env file:

Or in the config file config/emmanuel-saleem-social-auth.php:

Customize Footer

Hide the footer:

Or customize the footer text:

In config file:

Customize Routes Prefix

Edit config/emmanuel-saleem-social-auth.php:

Customize Redirects

Customize Middleware

Customize Views

After publishing views:

Edit the views in resources/views/vendor/emmanuel-saleem-social-auth/

The component includes:

• ✅ Both Google and Microsoft buttons with official icons
• ✅ Responsive design (mobile-friendly)
• ✅ Error/success message display
• ✅ Modern, clean UI
• ✅ Inline CSS (no external dependencies)
• ✅ Customizable labels and footer
• ✅ Can be included in any existing page

🗄️ Database Schema

The package adds these fields to your users table:

The password column is also made nullable to support social-only users.

🔒 Security

• All OAuth tokens are stored securely in the database
• Passwords for OAuth users are randomly generated and hashed
• Email verification is automatically marked as verified for OAuth users
• CSRF protection on all web routes
• Stateless OAuth for API routes

🧪 Testing

Test Web Routes

Test API Routes

🐛 Troubleshooting

Issue: Package installs as dev-master instead of stable version

Problem: When running composer require emmanuel-saleem/social-auth, it installs dev-master instead of a stable version.

Solution:

1. Specify version constraint explicitly:

2. Or install specific version:

3. Check your composer.json minimum-stability:

Issue: Composer cache directory not writable (Docker)

Problem:

Solution: Run composer with proper permissions or disable cache:

Issue: Laravel version conflict

Problem:

Solution: The package supports Laravel 9, 10, and 11. Check your Laravel version:

If you're on Laravel 8 or below, you need to upgrade Laravel or use an older version of Socialite.

Issue: "Class not found" error

Solution: Make sure to run composer dump-autoload

Issue: Microsoft OAuth "invalid_client" error

Problem:

Solution:

1. Check your credentials in .env file:

2. Verify in Azure Portal:

   • Go to your app registration → Overview
   • Copy the exact Application (client) ID
   • Go to Certificates & secrets → Copy the exact client secret
3. Clear config cache:

Issue: Microsoft OAuth "userAudience" configuration error

Problem:

Solution: This happens when your Azure app is configured for "Personal Microsoft accounts only" but the OAuth request uses the /common endpoint.

Option 1: Change Azure App Configuration (Recommended)

1. Go to Azure Portal → Your App Registration → Authentication
2. Change "Supported account types" to "Accounts in any organizational directory and personal Microsoft accounts"
3. This allows the /common endpoint to work

Option 2: Use Consumer Endpoint

1. Keep "Personal Microsoft accounts only" in Azure

2. Set in your .env:

3. Clear config cache:

Issue: Role dropdown not saving selected value

Problem: The role selected from the dropdown is not being saved to the database.

Solution: This was fixed in the latest version. Make sure you're using the updated package and clear caches:

The package now properly merges form data in the correct order: payload → user_defaults → extra (where extra overrides defaults).

Issue: Routes not working

Solution: Clear route cache:

Issue: "redirect_uri_mismatch"

Solution: Ensure your redirect URIs in .env match exactly with those in Google/Microsoft console

Issue: Token creation fails

Solution: Make sure:

1. Laravel Sanctum is installed
2. User model has HasApiTokens trait
3. Migrations have run

Issue: CORS errors in API

Solution: Configure CORS in config/cors.php:

📚 Documentation

• API Integration Guide - Complete guide for SPA/API integration
• Passport Setup Guide - Laravel Passport integration
• Usage Examples - Practical examples for React, Vue, etc.
• Laravel Socialite Docs
• Laravel Sanctum Docs
• Laravel Passport Docs

🛣️ Roadmap

• [x] Google OAuth support
• [x] Microsoft OAuth support
• [x] API endpoints for SPA
• [x] Standardized response format
• [ ] GitHub OAuth support
• [ ] Facebook OAuth support
• [ ] LinkedIn OAuth support
• [ ] Twitter/X OAuth support
• [ ] Two-factor authentication
• [ ] Social account linking
• [ ] Admin panel for managing OAuth apps

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This package is open-sourced software licensed under the MIT license.

👨‍💻 Author

Emmanuel Saleem

• Email: [email protected]
• LinkedIn: linkedin.com/in/es77
• GitHub: @emmanuel-saleem

🙏 Acknowledgments

• Laravel Socialite team
• Laravel Sanctum team
• All contributors

📞 Support

If you encounter any issues or have questions:

1. Check the OAUTH_API_GUIDE.md
2. Review Troubleshooting section
3. Check existing GitHub Issues
4. Create a new issue with detailed information

Made with ❤️ for the Laravel community dodcumeiton link mirsoft https://learn.microsoft.com/en-us/graph/auth-register-app-v2