README

composer require socialiteproviders/microsoft

Installation & Basic Usage

Please see the Base Installation Guide, then follow the provider specific instructions below.

Add configuration to config/services.php

'microsoft' => [    
  'client_id' => env('MICROSOFT_CLIENT_ID'),  
  'client_secret' => env('MICROSOFT_CLIENT_SECRET'),  
  'redirect' => env('MICROSOFT_REDIRECT_URI'),
  'proxy' => env('PROXY')  // Optional, will be used for all requests
],

Add provider event listener

Laravel 11+

In Laravel 11, the default EventServiceProvider provider was removed. Instead, add the listener using the listen method on the Event facade, in your AppServiceProvider boot method.

• Note: You do not need to add anything for the built-in socialite providers unless you override them with your own providers.

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

protected $listen = [
    \SocialiteProviders\Manager\SocialiteWasCalled::class => [
        // ... other providers
        \SocialiteProviders\Microsoft\MicrosoftExtendSocialite::class.'@handle',
    ],
];

Usage

You should now be able to use the provider like you would regularly use Socialite (assuming you have the facade installed):

return Socialite::driver('microsoft')->redirect();

Extended features

ID token validation and key rollover

When using the openid scope, Microsoft returns an id_token JWT. This provider validates the id_token signature and claims.

Microsoft (Entra ID / Azure AD) periodically rotates signing keys. During rollover there can be a short window where a token is signed with a new key that is not yet available from the published JWKS endpoints. To reduce intermittent login failures, the provider caches JWKS briefly and will refresh the JWKS and retry validation once when it encounters an unknown kid.

Roles

Socialite::driver('microsoft')->user()->getRoles() returns an array of strings containing the names of the Microsoft 365/Azure AD groups the authenticated user belongs to. You can use this information to assign users to application roles at login.

• ref. Emit groups as role claims in Entra ID

Tenant Details

You can also retrieve Tenant information at the same time as you retrieve users, this can be useful if you need to allow only your tenant/s or filter certain tenants.

To do this you first need to edit your config/services.php file and within your microsoft settings array include 'include_tenant_info' like the following:

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

NOTE: if you use 'tenant' => env('MICROSOFT_TENANT_ID') then you should ensure that your .env file still uses 'common' as the tenant ID.

The default tenant fields returned are:

• ID
• displayName
• city
• country
• countryLetterCode
• state
• street
• verifiedDomains

Refresh token

By default Microsoft doesn't return a refresh token. But if you do need a refresh token you need to add the offline_access scope. Adding the scope is done on the redirect method as is described in the Laravel docs.

Tenant types

The supported values (defined by MS Identity Platform) for 'tenant' are listed below and can be used to control who can sign into the application.

• common - for both Microsoft accounts and work or school accounts (most permissive),
• organizations - for work or school accounts only,
• consumers - for Microsoft accounts only (only services like Xbox, Teams for Life, or Outlook),
• tenant identifiers - such as the tenant ID or domain name (most restrictive).

Note: when configuring the services.php microsoft entry with

• tenant => 'common'
• include_tenant_info => true

and attempting to login with a 'consumer' account, the user's tenant value will be null

e.g.

$user = Socialite::driver('microsoft')->user();
if ($user->tenant === null) {

    // do some consumer/public specific workflow
    
} else {

    // do your work / school tenant workflow
    Log::info(sprintf("Tenant found - %s", $user->tenant->displayName));
     
}

Additional tenant fields tenant_fields

Any additional fields can be returned with the attribute names detailed here.

e.g. 'tenantType', 'technicalNotificationMails' can be requested as such

    'microsoft' => [
        'client_id' => env('MICROSOFT_CLIENT_ID'), 
        'client_secret' => env('MICROSOFT_CLIENT_SECRET'),
        'redirect' => env('MICROSOFT_REDIRECT_URI'), 
        'tenant' => env('MICROSOFT_TENANT_ID', 'common'), 
        'include_tenant_info' => true,
        'tenant_fields' => [ 'tenantType', 'technicalNotificationMails' ],
        'include_avatar' => true,
        'include_avatar_size' => '648x648',
    ],