Connect to Microsoft 365 with PowerShell

This article applies to both Microsoft 365 Enterprise and Office 365 Enterprise.

PowerShell for Microsoft 365 enables you to manage your Microsoft 365 settings from the command line. To connect to PowerShell, just install the required software and then connect to your Microsoft 365 organization.

There are two versions of the PowerShell module that you can use to connect to Microsoft 365 and administer user accounts, groups, and licenses:

  • Azure Active Directory PowerShell for Graph, whose cmdlets include AzureAD in their name
  • Microsoft Azure Active Directory Module for Windows PowerShell, whose cmdlets include Msol in their name

Currently, the Azure Active Directory PowerShell for Graph module doesn't completely replace the functionality of the Microsoft Azure Active Directory Module for Windows PowerShell module for user, group, and license administration. In some cases, you need to use both versions. You can safely install both versions on the same computer.

What do you need to know before you begin?

Operating system

You must use a 64-bit version of Windows. Support for the 32-bit version of the Microsoft Azure Active Directory Module for Windows PowerShell ended in 2014.

You can use the following versions of Windows:

  • Windows 10, Windows 8.1, Windows 8, or Windows 7 Service Pack 1 (SP1)

  • Windows Server 2019, Windows Server 2016, Windows Server 2012 R2, Windows Server 2012, or Windows Server 2008 R2 SP1

Note

For Windows 8.1, Windows 8, Windows 7 Service Pack 1 (SP1), Windows Server 2012 R2, Windows Server 2012, and Windows Server 2008 R2 SP1, download and install the Windows Management Framework 5.1.

PowerShell

  • For the Azure Active Directory PowerShell for Graph module, you must use PowerShell version 5.1 or later.

  • For the Microsoft Azure Active Directory Module for Windows PowerShell module, you must use PowerShell version 5.1 or later, up to PowerShell version 6. You can't use PowerShell version 7.

Note

These procedures are intended for users who are members of a Microsoft 365 admin role. For more information, see About admin roles.

Connect with the Azure Active Directory PowerShell for Graph module

Commands in the Azure Active Directory PowerShell for Graph module have AzureAD in their cmdlet name. You can install the Azure Active Directory PowerShell for Graph module or Azure PowerShell.

For procedures that require the new cmdlets in the Azure Active Directory PowerShell for Graph module, follow these steps to install the module and connect to your Microsoft 365 subscription.

Note

For information about support for different versions of Windows, see Azure Active Directory PowerShell for Graph module .

Step 1: Install the required software

These steps are required only one time on your computer. But you'll likely need to update the software periodically.

  1. Open an elevated Windows PowerShell Command Prompt window (run Windows PowerShell as an administrator).

  2. Run this command:

    Install-Module -Name AzureAD
    

By default, the PowerShell Gallery (PSGallery) isn't configured as a trusted repository for PowerShellGet. The first time you use the PSGallery, you'll see the following message:

Untrusted repository

You are installing the modules from an untrusted repository. If you trust this repository, change
its InstallationPolicy value by running the `Set-PSRepository` cmdlet.

Are you sure you want to install the modules from 'PSGallery'?
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "N"):

Answer Yes or Yes to All to continue with the installation.

Step 2: Connect to Azure AD for your Microsoft 365 subscription

To connect to Azure Active Directory (Azure AD) for your Microsoft 365 subscription with an account name and password or with multi-factor authentication, run one of these commands from a Windows PowerShell command prompt. (It doesn't have to be elevated.)

Office 365 cloud Command
Office 365 Worldwide (+GCC) Connect-AzureAD
Office 365 operated by 21 Vianet Connect-AzureAD -AzureEnvironmentName AzureChinaCloud
Office 365 Germany Connect-AzureAD -AzureEnvironmentName AzureGermanyCloud
Office 365 U.S. Government DoD and Office 365 U.S. Government GCC High Connect-AzureAD -AzureEnvironmentName AzureUSGovernment

In the Sign into your account dialog box, type your Microsoft 365 work or school account user name and password, and then select OK.

If you're using multi-factor authentication, follow the instructions to provide additional authentication information, such as a verification code.

After you connect, you can use the cmdlets for the Azure Active Directory PowerShell for Graph module.

Connect with the Microsoft Azure Active Directory Module for Windows PowerShell

Note

Cmdlets in the Microsoft Azure Active Directory Module for Windows PowerShell have Msol in their name.

PowerShell version 7 and later don't support the Microsoft Azure Active Directory Module for Windows PowerShell module and cmdlets with Msol in their name. For PowerShell version 7 and later, you must use the Azure Active Directory PowerShell for Graph module or Azure PowerShell.

PowerShell Core doesn't support the Microsoft Azure Active Directory Module for Windows PowerShell module and cmdlets with Msol in their name. Run these cmdlets from Windows PowerShell.

Step 1: Install the required software

These steps are required only one time on your computer. But you'll likely need to update the software periodically.

  1. If you're not running Windows 10, install the 64-bit version of the Microsoft Online Services Sign-in Assistant: Microsoft Online Services Sign-in Assistant for IT Professionals RTW.

  2. Follow these steps to install the Microsoft Azure Active Directory Module for Windows PowerShell:

    1. Open an elevated Windows PowerShell command prompt (run Windows PowerShell as an administrator).
    2. Run the Install-Module MSOnline command.
    3. If you're prompted to install the NuGet provider, type Y and press Enter.
    4. If you're prompted to install the module from PSGallery, type Y and press Enter.

Step 2: Connect to Azure AD for your Microsoft 365 subscription

To connect to Azure AD for your Microsoft 365 subscription with an account name and password or with multi-factor authentication, run one of these commands from a Windows PowerShell command prompt. (It doesn't have to be elevated.)

Office 365 cloud Command
Office 365 Worldwide (+GCC) Connect-MsolService
Office 365 operated by 21 Vianet Connect-MsolService -AzureEnvironment AzureChinaCloud
Office 365 Germany Connect-MsolService -AzureEnvironment AzureGermanyCloud
Office 365 U.S. Government DoD and Office 365 U.S. Government GCC High Connect-MsolService -AzureEnvironment USGovernment

In the Sign into your account dialog box, type your Microsoft 365 work or school account user name and password, and then select OK.

If you're using multi-factor authentication, follow the instructions to provide additional authentication information, such as a verification code.

How do you know it worked?

If you don't get an error message, you connected successfully. For quick test, run a Microsoft 365 cmdlet, such as Get-MsolUser, and see the results.

If you get an error message, check the following issues:

  • A common problem is an incorrect password. Run Step 2 again, and pay close attention to the user name and password that you enter.

  • The Microsoft Azure Active Directory Module for Windows PowerShell requires that Microsoft .NET Framework 3.5.x is enabled on your computer. It's likely that your computer has a newer version installed (for example, 4 or 4.5.x). But backward compatibility with older versions of the .NET Framework can be enabled or disabled. For more information, see the following articles:

  • Your version of the Microsoft Azure Active Directory Module for Windows PowerShell might be out of date. To check, run the following command in PowerShell for Microsoft 365 or the Microsoft Azure Active Directory Module for Windows PowerShell:

    (Get-Item C:\Windows\System32\WindowsPowerShell\v1.0\Modules\MSOnline\Microsoft.Online.Administration.Automation.PSModule.dll).VersionInfo.FileVersion
    

    If the version number returned is lower than 1.0.8070.2, uninstall the Microsoft Azure Active Directory Module for Windows PowerShell and install from Step 1, above.

  • If you get a connection error message, see "Connect-MsolService: Exception of type was thrown" error.

  • If you get a "Get-Item: Cannot find path" error message, run this command:

       (dir "C:\Program Files\WindowsPowerShell\Modules\MSOnline").Name
    

See also