sls/plan.md

Role-Based Login & Microsoft SSO System Plan

We will build a two-role authentication system (Admin & User) in Laravel, integrating Microsoft OAuth (via Laravel Socialite) for users, and dual authentication (Microsoft + email/password) for admins.

---

1. Authentication Flows & Security

graph TD
    A[Visitor] --> B{Choose Path}
    B -->|User| C[Login via Microsoft]
    B -->|Admin| D[Login via Microsoft OR Email/Password]
    C --> E[Redirect to Microsoft Azure AD]
    E --> F[Microsoft Callback]
    F -->|Success| G{Is User Registered?}
    G -->|No| H[Create User Record with 'user' role]
    G -->|Yes| I[Log User In]
    I --> J[Redirect to Dashboard]
    
    D -->|Microsoft| E
    D -->|Email/Password| K[Laravel Auth Attempt]
    K -->|Success| L[Verify Role is 'admin']
    L -->|Yes| M[Redirect to Admin Dashboard]
    L -->|No| N[Redirect Back with Error]

Roles Defined:

1. User: Authenticatable ONLY via Microsoft. Accesses /dashboard, sees service icons (Keka, Teams, Outlook) which log them in silently.
2. Admin: Authenticatable via BOTH Microsoft and standard Email/Password credentials. Accesses /admin/dashboard (and can also access the user dashboard if needed).

---

2. Technical Roadmap

Step 1: Install Dependencies

We will install Laravel Socialite and the Microsoft Graph Socialite provider:

composer require laravel/socialite
composer require socialiteproviders/microsoft

Step 2: Configure Service Provider & Credentials

1. Register the Socialite listener in AppServiceProvider.php:

   use SocialiteProviders\Manager\SocialiteWasCalled;
   use SocialiteProviders\Microsoft\MicrosoftExtendSocialite;
   
   Event::listen(function (SocialiteWasCalled $event) {
       $event->extendSocialite('microsoft', MicrosoftExtendSocialite::class);
   });
   

2. Configure config/services.php to include:

   'microsoft' => [
       'client_id' => env('MICROSOFT_CLIENT_ID'),
       'client_secret' => env('MICROSOFT_CLIENT_SECRET'),
       'redirect' => env('MICROSOFT_REDIRECT_URI'),
       'tenant' => env('MICROSOFT_TENANT_ID', 'common'),
   ],
   

3. Set the variables in .env:
   • MICROSOFT_CLIENT_ID
   • MICROSOFT_CLIENT_SECRET
   • MICROSOFT_REDIRECT_URI=http://localhost:8000/auth/microsoft/callback
   • MICROSOFT_TENANT_ID=common

Step 3: Database & Migration Updates

Modify database/migrations/0001_01_01_000000_create_users_table.php to include:

• role (string, defaults to 'user')
• microsoft_id (string, nullable)
• microsoft_token (text, nullable)
• microsoft_refresh_token (text, nullable)
• avatar (string, nullable)
• Allow password to be nullable (since Users log in strictly via Microsoft and won't have a local password).

We will write a DatabaseSeeder to generate:

• A default Administrator account (e.g., admin@company.com / Admin@123) to test email/password login.

Step 4: Middleware & Gates

Create middleware files:

1. EnsureAdmin - Redirects non-admins away from /admin/*.
2. EnsureUser - Redirects non-users (or unauthenticated users) away from /dashboard.

Register them in bootstrap/app.php (under $middleware->alias(...) or use route groups).

Step 5: Routes & Controllers

We will define the following routes in web.php:

Route	Method	Controller Action	Description
/	GET	LoginController@index	Auto-redirects logged-in users, or renders Login page
/login	GET	LoginController@showLoginForm	Beautiful interactive login page
/login/admin	POST	LoginController@adminLogin	Handle admin email/password login
/auth/microsoft/redirect	GET	LoginController@redirectToMicrosoft	Redirects to Microsoft OAuth
/auth/microsoft/callback	GET	LoginController@handleMicrosoftCallback	Processes OAuth callback & logs in user
/dashboard	GET	DashboardController@index	User Dashboard with Services (Keka, Outlook, Teams)
/admin/dashboard	GET	AdminController@index	Admin Control Panel
/logout	POST	LoginController@logout	Standard Logout

Step 6: Silent SSO / Services Integration

• Mechanism: When users log in via Microsoft, Microsoft creates authentication cookies in the browser session.
• Flow:
  • The Dashboard features cards for:
    • Outlook: links to https://outlook.office.com/mail/
    • Teams: links to https://teams.microsoft.com/v2/
    • Keka: links to https://my.keka.com/ (or a configured company portal)
  • Clicking these cards opens them in a new tab (target="_blank").
  • Since the active browser session contains Microsoft's authentication cookies from our login flow, Microsoft SSO automatically authenticates the user into these applications. They bypass login prompts and access their accounts directly (silently).
  • We will provide mock buttons in local testing mode to simulate the SSO authentication if required, or simply redirect to the live services.

Step 7: UI/UX & Design System (Aesthetics)

We will build a high-fidelity visual experience:

• Typography: Outfit or Inter font, clean structure.
• Login Screen: Glassmorphism dashboard card, subtle background gradients, hover glow effects, micro-animations on input focuses, and a dual toggle between "User Portal" (Microsoft SSO only) and "Admin Portal" (Credentials + Microsoft SSO).
• Dashboard: A premium modern portal featuring grid cards representing each service with clean hover animations, active session banners, profile widgets showing Microsoft avatars, and interactive logs.

---

3. Review Questions & Feedback

Please review this plan and let me know:

1. Database Type: Should we use SQLite (database.sqlite) for easier local development/testing of this feature, or is your local MySQL server ready to connect as specified in .env?
2. Microsoft App Credentials: Do you have a Microsoft Azure AD app registration ready? If not, I can provide instructions on how to create one in the Azure Portal (registers client ID, secret, and redirect URI).
3. App Selection: Are Keka, Outlook, and Teams the exact external links you want, or would you like to configure custom enterprise dashboard URLs?

Let me know if you approve this plan or if you want to modify any details, and we'll begin implementation!