Weave Code
Microsoft Laravel Package
socialiteproviders/microsoft
Microsoft provider for Laravel Socialite adds Microsoft (Azure AD) OAuth login to your Laravel app. Install via Composer, configure your client ID, secret, and tenant, then use Socialite::driver('microsoft') to authenticate users and retrieve profile data.
Microsoft OAuth2 Provider for Laravel Socialite
Frequently asked questions about Microsoft
- How do I install the Microsoft provider for Laravel Socialite?
- Install it with Composer using composer require socialiteproviders/microsoft. This pulls in the split package plus socialiteproviders/manager, which Socialite uses to register the driver. After installing, you must register the SocialiteWasCalled listener and add a microsoft block to config/services.php before the driver resolves. No service provider is auto-discovered for the provider itself in older setups, so check the README for the current listener step.
- How do I configure the microsoft driver in config/services.php?
- Add a microsoft key with client_id, client_secret, redirect, and tenant values taken from your Entra ID (Azure AD) app registration. The redirect must exactly match one of the redirect URIs registered on the app, including scheme, host, port, and trailing slash. The tenant controls which account types can sign in and shapes the OAuth endpoints the driver calls. Keep the secret out of version control and load it from the environment.
- How do I register the SocialiteWasCalled event listener for Microsoft?
- Listen for SocialiteProviders\Manager\SocialiteWasCalled and append MicrosoftExtendSocialite::class.'@handle' to the listeners array. In older Laravel this lives in app/Providers/EventServiceProvider.php; in Laravel 11 and later you register it in the application bootstrap or an AppServiceProvider. Without this listener, Socialite::driver('microsoft') throws an error because the driver is never registered with the manager. If you use event discovery, verify the listener is actually picked up.
- Which tenant value should I use: common, organizations, consumers, or a tenant ID?
- Use common to allow both work/school and personal Microsoft accounts, organizations for work and school accounts only, and consumers for personal accounts only. Use your specific tenant GUID when you need single-tenant sign-in restricted to your directory. This is an identity architecture decision, not a code tweak, and changing it later affects who can authenticate and how guest users are treated. Decide it before you wire up the callback route.
- What user data does the microsoft Socialite driver return?
- The driver maps the Microsoft Graph me payload into Socialite's standard User object, so you get an id, name, nickname, email, and avatar fields where Microsoft supplies them. The full response is available through getRaw() for claims like tenant ID or user principal name. Do not assume every field is populated: guest accounts, personal accounts, and tenants with restricted claim configuration can omit or vary values such as email. Always store the raw payload alongside the mapped user for debugging.
- Should I use the Microsoft email address as the user's primary identifier?
- No. The email claim from Microsoft is not universally present and is not guaranteed to be stable over time, so using it as a primary key invites account-linking takeover. Link accounts on the Entra object ID (oid) and persist the tenant_id alongside it. Treat email and UPN as mutable profile attributes that get refreshed on each login, not as identity. Getting this mapping right before writing code is the most important decision in the integration.
- Does this package let me call Microsoft Graph for mail, calendar, or files?
- No, it only handles the OAuth2 login flow and profile retrieval. Accessing Graph data requires storing the access and refresh tokens, requesting the right scopes during the redirect, and handling token refresh yourself with the Microsoft Graph SDK. If you need offline or daemon access, that is a separate concern from Socialite login. Plan the token lifecycle and scope selection as distinct work items.
- Which Laravel and Socialite versions does socialiteproviders/microsoft support?
- Releases ride the socialiteproviders/providers monorepo and are aligned to a given laravel/socialite and PHP range, so verify the constraints at install and again at every upgrade. A Socialite major release can leave this split package behind for a period, since the split artifact has relatively little visible downstream validation. Pin versions in composer.json and review the monorepo release notes before bumping Socialite. Keep an exit plan in case the split lags a Laravel or Socialite major.
- What causes Microsoft OAuth login outages in production?
- The two most common causes are an expired client secret and missing admin consent for the requested scopes. Redirect URI mismatches across environments, and conditional access or MFA policies applied to the app, also cause failures that look like driver bugs. The adapter does not mitigate any of these; they are owned by the tenant and your app registration. Set secret rotation reminders and verify consent in a staging tenant before release.
- How does this compare to the microsoft-azure driver or a custom provider?
- Several Microsoft drivers exist, including microsoft and microsoft-azure, plus in-house AbstractProvider subclasses, and they differ in endpoints and claim mapping. Pick one deliberately, because switching later causes churn and inconsistent stored identifiers. This package is a thin adapter over Socialite and is not suitable as a standalone auth layer, for stateless API-only backends without your own state handling, or for native and mobile apps where MSAL is the right tool.
Weaver
How can I help you explore Laravel packages today?