Install & Connect to Microsoft Graph

This guide walks you through installing the Microsoft Graph PowerShell SDK and connecting to Microsoft Graph so you can automate tasks across Microsoft 365, Entra ID (Azure AD), and other Microsoft services. You’ll learn how to set up the module, authenticate, and verify your connection. Before starting, ensure you have PowerShell 5.1 or later (or PowerShell 7+), and the appropriate admin permissions for the scopes you need.

What You’ll Need

Windows, macOS, or Linux with PowerShell 5.1+ (Windows) or PowerShell 7+ (cross-platform)
An account in Microsoft 365 or Azure with permissions to consent to the scopes you’ll request (typically a global admin or application administrator for delegated permissions)
Internet access to the Microsoft Graph endpoints
If using a script or automation, an Azure AD app registration (optional for interactive use)

Step-by-Step

Open PowerShell as an administrator (Windows) or in a terminal (macOS/Linux). For Windows, right-click PowerShell and select “Run as administrator” to avoid permission issues during module installation.
Install the Microsoft Graph PowerShell SDK by running:
```
Install-Module Microsoft.Graph -Scope CurrentUser
```
If you’re using PowerShell 5.1, you may need to first install the NuGet provider and the PowerShellGet module. If prompted, accept the NuGet provider installation and the “Untrusted repository” warning by typing Y.
Verify the installation by checking the module version:
```
Get-Module Microsoft.Graph -ListAvailable | Select-Object Name, Version
```
You should see a version like 2.x.x. If you see nothing, try restarting PowerShell or running Import-Module Microsoft.Graph.
Connect to Microsoft Graph with delegated permissions (as a user) using:
```
Connect-MgGraph -Scopes "User.Read", "Mail.Read"
```
Replace the scopes with the ones you need (e.g., Group.Read.All, Directory.Read.All). This opens a browser window for you to sign in with your Microsoft account.
Authenticate in the browser. Enter your credentials and consent to the permissions if prompted. If you’re using a device that doesn’t support a browser, use -UseDeviceAuthentication to get a code to enter at microsoft.com/devicelogin.
Verify the connection by running a simple query:
```
Get-MgUser -Top 1 | Select-Object DisplayName, UserPrincipalName
```
If this returns a user, you’re connected. If not, check your scopes and permissions.
For app-only (non-interactive) authentication, you’ll need an Azure AD app registration with a client secret or certificate. Then use:
```
Connect-MgGraph -ClientId "your-client-id" -TenantId "your-tenant-id" -CertificateThumbprint "your-thumbprint"
```
Or for a client secret (less secure, use only in dev):
```
Connect-MgGraph -ClientId "your-client-id" -TenantId "your-tenant-id" -ClientSecret "your-secret"
```
Ensure the app has the necessary API permissions (e.g., User.Read.All as Application permissions) and admin consent granted.
Disconnect when done to avoid leaving an active session:
```
Disconnect-MgGraph
```

Common Mistakes

Not running PowerShell as admin when installing the module – can cause permission errors. Use -Scope CurrentUser to avoid admin rights if needed.
Using the wrong scopes – if your query needs Group.Read.All but you only requested User.Read, you’ll get an authorization error. Always request the minimum scopes required, but make sure they cover your operations.
Forgetting to consent – delegated permissions require user consent, and app-only permissions require admin consent. If you get an “Access denied” error, check consent.
Mixing up delegated and application permissions – using Connect-MgGraph with a client secret is for app-only, but the scopes you specify must be application permissions, not delegated. If you use delegated scopes, it won’t work.
Not updating the module – old versions may have bugs or lack new cmdlets. Update with Update-Module Microsoft.Graph.

Tips

Use the -Scopes parameter to request only the permissions you need – this is a security best practice and reduces consent friction.
For scripts, consider using Connect-MgGraph -NoWelcome to suppress the welcome message and speed up execution.
Use Select-MgProfile -Name "v1.0" or "beta" to switch between API versions. Beta is for preview features, but may change.
If you need to run many commands, keep the session open across multiple scripts by using Disconnect-MgGraph only when done, or use -Context to save a context and reuse it.
To see all available cmdlets, run Get-Command -Module Microsoft.Graph.

Troubleshooting

Module not found after install – restart PowerShell, or run Import-Module Microsoft.Graph. If still not found, check if the module installed to a different PSModulePath. Use Get-Module -ListAvailable Microsoft.Graph to see paths.
Authentication fails with error AADSTS50011 – this usually means the redirect URI doesn’t match. For interactive auth, ensure you’re using the default public client redirect (e.g., https://login.microsoftonline.com/common/oauth2/nativeclient). For app-only, check the app registration’s redirect URIs.
Authorization error (403) when calling a cmdlet – your token lacks the required scope. Either request more scopes in Connect-MgGraph or use a different authentication method. Also check if admin consent is needed for the permission.
Connection drops or times out – check your internet connection and firewall. Try using -UseDeviceAuthentication if browser issues occur. Also, ensure your clock is synced – a skewed clock can break token validation.
PowerShell 5.1 errors with TLS – run [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 before installing.
Cmdlet not recognized – e.g., Get-MgUser not found – make sure you imported the module or that you have the latest version. Some cmdlets are in submodules; run Import-Module Microsoft.Graph.Users if needed.

Frequently Asked Questions

Can I use Microsoft Graph without installing the SDK? Yes, you can call the REST API directly with Invoke-RestMethod, but the SDK simplifies authentication and provides typed cmdlets.
What’s the difference between delegated and application permissions? Delegated permissions act on behalf of a signed-in user, while application permissions act as the app itself without a user. Use application permissions for background services.
How do I find the right scope for a specific operation? Check the Microsoft Graph documentation for the API endpoint you’re using – it lists required permissions. For example, GET /users requires User.Read.All (delegated or application).
Can I connect to multiple tenants at once? Yes, you can run multiple Connect-MgGraph sessions in separate PowerShell processes, or use -Context to switch between saved contexts.
Why do I get a prompt to install NuGet provider? The first time you install a module, PowerShell needs the NuGet provider to download it. Accept the prompt – it’s safe.
Is the Microsoft.Graph module available for PowerShell Core (7)? Yes, the module is cross-platform and works on PowerShell 7+ on Windows, macOS, and Linux.

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →