Install the module, connect with the permissions you need, and check what you got:
Install-Module Microsoft.Graph -Scope CurrentUser -Repository PSGallery -Force
Connect-MgGraph -Scopes "User.Read.All"
Get-MgContext
Sign in when prompted and accept the permissions. You don't need a client ID, a tenant ID or an Exchange Online connection for this. Get-MgContext shows the account, the tenant and the scopes of your session, and an empty result means you aren't connected.
Try a request to see it work:
Invoke-MgGraphRequest -Method GET -Uri https://graph.microsoft.com/v1.0/me
Before you install
Microsoft recommends PowerShell 7 or later. Windows PowerShell 5.1 also works, with .NET Framework 4.7.2 or later, an updated PowerShellGet, and this execution policy:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Installing in one version of PowerShell doesn't install it for the other, so run the install in the shell you plan to use.
Microsoft.Graph pulls in more than 40 submodules. Connect-MgGraph itself lives in Microsoft.Graph.Authentication, so a script that only needs a few areas can install that module plus the ones it uses. Find-Module Microsoft.Graph* lists them.
To check your version and update:
Get-InstalledModule Microsoft.Graph
Update-Module Microsoft.Graph
Ways to sign in
The first two rows sign in as you, with your permissions. The next three suit scripts that run with nobody at the keyboard, and they use permissions set on an app registration. An access token carries whatever permissions it was issued with.
| You are | Use |
|---|---|
| At your own computer | -Scopes |
| On a machine with no browser | -Scopes with -UseDeviceAuthentication |
| Running a script with a certificate | -ClientId, -TenantId, -CertificateThumbprint |
| Running a script with a client secret | -TenantId, -ClientSecretCredential |
| Running in Azure | -Identity |
| Holding an access token from elsewhere | -AccessToken |
Microsoft's authentication reference lists every parameter.
Delegated sign-in
Connect-MgGraph -Scopes "User.Read.All", "Group.ReadWrite.All"
Add -UseDeviceAuthentication to get a code you can enter on another device:
Connect-MgGraph -Scopes "User.Read.All" -UseDeviceAuthentication
Certificate
The certificate must be in Cert:\CurrentUser\My\ or Cert:\LocalMachine\My\. Point to it by thumbprint or by subject name:
Connect-MgGraph -ClientId "YOUR_APP_ID" -TenantId "YOUR_TENANT_ID" -CertificateThumbprint "YOUR_CERT_THUMBPRINT"
Connect-MgGraph -ClientId "YOUR_APP_ID" -TenantId "YOUR_TENANT_ID" -CertificateName "YOUR_CERT_SUBJECT"
You can also pass a certificate object:
$Cert = Get-ChildItem Cert:\LocalMachine\My\$CertThumbprint
Connect-MgGraph -ClientId "YOUR_APP_ID" -TenantId "YOUR_TENANT_ID" -Certificate $Cert
Client secret
Microsoft recommends PowerShell 7 or later for this one. Keep the secret out of the script itself.
$SecureClientSecret = ConvertTo-SecureString -String $ApplicationClientSecret -AsPlainText -Force
$ClientSecretCredential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $ApplicationClientId, $SecureClientSecret
Connect-MgGraph -TenantId $TenantId -ClientSecretCredential $ClientSecretCredential
Managed identity
With a managed identity, Azure handles the credential, so there's no secret or certificate to rotate. The first line uses a system-assigned identity and the second a user-assigned one:
Connect-MgGraph -Identity
Connect-MgGraph -Identity -ClientId "USER_ASSIGNED_MANAGED_IDENTITY_CLIENT_ID"
Access token
If you got a token some other way, pass it in:
Connect-MgGraph -AccessToken $AccessToken
For a national cloud, add -Environment, for example -Environment USGov. Get-MgEnvironment lists the options.
Which scopes do I need?
Ask PowerShell. Find-MgGraphCommand lists the permissions behind any Graph cmdlet:
Find-MgGraphCommand -Command New-MgServicePrincipal | Select -First 1 -ExpandProperty Permissions
That one returns Application.ReadWrite.All, so reconnect with it:
Connect-MgGraph -Scopes Application.ReadWrite.All
This shows what your current session holds:
Get-MgContext | Select -ExpandProperty Scopes
-Scopes only applies to delegated sign-in. For certificates, secrets and managed identities, the permissions are set on the app in advance and need admin consent.
Fixing common errors
"Connect-MgGraph is not recognized." PowerShell can't find the module in this shell. Check for it:
Get-Module Microsoft.Graph.Authentication -ListAvailable
If that returns nothing, install the module in this shell, since each version of PowerShell has its own install. If it lists the module, load it by hand:
Import-Module Microsoft.Graph.Authentication
A 403 error. Most authorization errors come from missing permissions, according to Microsoft's troubleshooting guide. Run Find-MgGraphCommand as above, reconnect with that scope, and try the command again.
The sign-in window hangs. Microsoft documents this for sovereign clouds, where the fix is to turn off Web Account Manager sign-in. That change stays in place until you reverse it.
Set-MgGraphOption -DisableLoginByWAM $true
You still can't see why it fails. Add -Debug to the command. The output shows the authentication type, the scopes and the request ID, which you'll need if you raise it with Microsoft. For a whole session, set $DebugPreference = 'Continue'.
Connecting through your own app
By default you sign in through Microsoft's own Graph PowerShell app. Your own app registration lets you control who can use it and what it can do.
- In the Microsoft Entra admin center, open App registrations and choose New registration.
- Enter a name, such as "Microsoft Graph PowerShell - High Privilege admin use only".
- For supported account types, choose accounts in this organizational directory only.
- Under Authentication, add the Mobile and desktop applications platform with two redirect URIs:
http://localhostandms-appx-web://Microsoft.AAD.BrokerPlugin/YOUR_APP_CLIENT_ID. Microsoft's steps add the second one for Windows sign-in. - In Enterprise applications, open the app, choose Properties, set Assignment required? to Yes, and save.
- Under Users and groups, add the people allowed to use it.
Then connect with the app's IDs:
Connect-MgGraph -ClientId "YOUR_APP_CLIENT_ID" -TenantId "YOUR_TENANT_ID"
Signing out
Your sign-in persists after you close the window. Disconnect-MgGraph ends it and clears the cached token:
Disconnect-MgGraph
To keep a sign-in to the current session only, connect with -ContextScope Process.
Graph is a separate connection from Exchange Online. For cmdlets like Get-Mailbox, install the Exchange Online PowerShell module and run Connect-ExchangeOnline as well.
