Table of Contents
Microsoft Graph PowerShell supports two types of authentications:
- Delegated access
- App-only access
There are a number of cmdlets that can be used to manage the different parameters required during authentication, for example, environment, application ID, and certificate. In this article, we’ll look at the different cmdlets that are associated with authentication.
You must invoke Connect-MgGraph before any commands that access Microsoft Graph. This cmdlet gets the access token using the Microsoft Authentication Library.
Delegated access
There are three ways to allow delegated access using Connect-MgGraph:
1️⃣ Using interactive authentication, where you provide the scopes that you require during your session:
Connect-MgGraph -Scopes "User.Read.All", "Group.ReadWrite.All"PS C:\> Get-MgContext
ClientId : 14d82eec-204b-4c2f-b7e8-296a70dab67e
TenantId : c032627b-6715-4e39-9990-bcf48ee5e0c5
Scopes : {Group.ReadWrite.All, openid, profile, User.Read.All...}
AuthType : Delegated
TokenCredentialType : InteractiveBrowser
CertificateThumbprint :
CertificateSubjectName :
Account : [email protected]
AppName : Microsoft Graph Command Line Tools
...2️⃣ Using device code flow:
Connect-MgGraph -Scopes "User.Read.All", "Group.ReadWrite.All" -UseDeviceAuthenticationPS C:\> Get-MgContext
ClientId : 14d82eec-204b-4c2f-b7e8-296a70dab67e
TenantId : c032627b-6715-4e39-9990-bcf48ee5e0c5
Scopes : {Group.ReadWrite.All, openid, profile, User.Read.All...}
AuthType : Delegated
TokenCredentialType : DeviceCode
CertificateThumbprint :
CertificateSubjectName :
Account : [email protected]
AppName : Microsoft Graph Command Line Tools
ContextScope : CurrentUser3️⃣ Using your own access token:
Connect-MgGraph -AccessToken $AccessToken4️⃣ Use delegated access with a custom application for Microsoft Graph PowerShell.
Follow the steps below to create custom applications that you can use to connect to Microsoft Graph PowerShell. Use this approach if you need to isolate and limit the consent permissions granted for Microsoft Graph PowerShell usage.
- Go to the Azure portal – App registrations > New Registration.
- Enter a Name for your application, for example Microsoft Graph PowerShell – High Privilege admin use only.
- For Supported account types, select Accounts in this organization directory.
- For Redirect URI: Select Public client/native from the drop down, URI value: http://localhost
- Select Register.
- Go to Enterprise applications and select the application you just created.
- Under Manage, select Properties and set Assignment required? to Yes.
- Select Save.
- Under Manage, select Users and groups.
- Select Add user/group and add the users and groups permitted to use this application.
- Once you’ve added all the users and groups, select Assign.
You can now use this app instead of the default one by connecting with:
Connect-MgGraph -ClientId <YOUR_NEW_APP_ID> -TenantId <YOUR_TENANT_ID>App-only access
Using client credential with a certificate
To use app-only access, you can load the certificate from either Cert:\CurrentUser\My\ or Cert:\LocalMachine\My\, when -CertificateThumbprint or -CertificateName is specified. Make sure that the certificate you’re using is present in either certificate store before calling Connect-MgGraph. For more info, see Use app-only authentication with the Microsoft Graph PowerShell SDK.
1️⃣ Using Certificate Thumbprint:
Connect-MgGraph `
-ClientId "YOUR_APP_ID" `
-TenantId "YOUR_TENANT_ID" `
-CertificateThumbprint "YOUR_CERT_THUMBPRINT"PS C:\> Get-MgContext
ClientId : 2ebd9b71-68b6-4846-b212-2ada0efe13a9
TenantId : c032627b-6715-4e39-9990-bcf48ee5e0c5
Scopes : {User.Read.All}
AuthType : AppOnly
TokenCredentialType : ClientCertificate
CertificateThumbprint : 1AD1AABC23D85B07EE04991889803CD2A85C6619
CertificateSubjectName :
Account :
AppName : testapp1
ContextScope : Process
Certificate :
PSHostVersion : 5.1.22621.17782️⃣ Using Certificate name:
Connect-MgGraph `
-ClientId "YOUR_APP_ID" `
-TenantId "YOUR_TENANT_ID" `
-CertificateName "YOUR_CERT_SUBJECT"3️⃣ Using a certificate:
$Cert = Get-ChildItem Cert:\LocalMachine\My\$CertThumbprint
Connect-MgGraph -ClientId "YOUR_APP_ID" -TenantId "YOUR_TENANT_ID" -Certificate $CertTo use a certificate stored in your machine’s certificate store or another location when connecting to Microsoft Graph, specify the certificate’s location.
Using client secret credentials
If you need interactions in the background, without a user to sign in, this type of grant will help you. Support for client secret credentials was added by adding -ClientSecretCredential parameter to Connect-MgGraph. See Get-Credential on how to get or create credentials.
$ClientSecretCredential = Get-Credential -Credential "Client_Id"
# Enter client_secret in the password prompt.
Connect-MgGraph -TenantId "Tenant_Id" -ClientSecretCredential $ClientSecretCredentialPS C:\> Get-MgContext
ClientId : 2ebd9b71-68b6-4846-b212-2ada0efe13a9
TenantId : c032627b-6715-4e39-9990-bcf48ee5e0c5
Scopes : {User.Read.All}
AuthType : AppOnly
TokenCredentialType : ClientSecret
CertificateThumbprint :
CertificateSubjectName :
Account :
AppName : testapp1
ContextScope : Process
Certificate :
PSHostVersion : 5.1.22621.1778Connecting to an environment as a different identity
To connect as a different identity other than CurrentUser, specify the -ContextScope parameter with the value Process.
Connect-MgGraph -ContextScope ProcessUsing Disconnect-MgGraph
Once you’re signed in, you’ll remain signed in until you invoke Disconnect-MgGraph. Microsoft Graph PowerShell automatically refreshes the access token for you and sign-in persists across PowerShell sessions because Microsoft Graph PowerShell securely caches the token.
Use Disconnect-MgGraph to sign out.
Disconnect-MgGraphUsing Get-MgEnvironment
When you use Connect-MgGraph, you can choose to target other environments. By default, Connect-MgGraph targets the global public cloud.
To get a list of all clouds that you can choose from, run:
Get-MgEnvironmentName AzureADEndpoint GraphEndpoint Type
---- --------------- ------------- ----
China https://login.chinacloudapi.cn https://microsoftgraph.chinacloudapi.cn Built-in
Global https://login.microsoftonline.com https://graph.microsoft.com Built-in
USGov https://login.microsoftonline.us https://graph.microsoft.us Built-in
USGovDoD https://login.microsoftonline.us https://dod-graph.microsoft.us Built-inTo explicitly target other clouds, for example, US Government and Azure China, use the -Environment parameter.
Connect-MgGraph -Environment USGovUsing Get-MgContext
Get-MgContext is used to retrieve the details about your current session, which include:
Get-MgContextClientId : 615e6e7c-aa11-4402-91a1-6234967405d5
TenantId : 9f32a42e-6782-4b96-a4d3-e0828a292569
CertificateThumbprint :
Scopes : {AppRoleAssignment.ReadWrite.All, Directory.AccessAsUser.All, Directory.ReadWrite.All, EntitlementManagement.ReadWrite.All...}
AuthType : Delegated
AuthProviderType : InteractiveAuthenticationProvider
CertificateName :
Account : [email protected]
AppName : Microsoft Graph PowerShell
ContextScope : CurrentUser
Certificate :
PSHostVersion : 5.1.17763.1
ClientTimeout : 00:05:00To retrieve all the scopes that you’ve consented to, expand the Scopes property using the -ExpandProperty parameter.
(Get-MgContext).ScopesAppRoleAssignment.ReadWrite.All
Directory.AccessAsUser.All
Directory.ReadWrite.All
EntitlementManagement.ReadWrite.All
Group.ReadWrite.All
openid
Organization.Read.All
profile
RoleManagement.ReadWrite.Directory
User.Read
User.ReadWrite.AllUsing Invoke-MgGraphRequest
Invoke-MgGraphRequest issues REST API requests to the Graph API. It works for any Graph API if you know the REST URI, method, and optional body parameter. This command is especially useful for accessing APIs for which there isn’t an equivalent cmdlet yet.
To retrieve the details of the signed-in user, run:
Invoke-MgGraphRequest -Method GET https://graph.microsoft.com/v1.0/meName Value
---- -----
userPrincipalName [email protected]
preferredLanguage en-US
mobilePhone 425-555-0101
displayName MOD Administrator
givenName MOD
mail [email protected]
@odata.context https://graph.microsoft.com/v1.0/$metadata#users/$entity
id 694bab60-392a-4f64-9430-c1dea2951f50
jobTitle
officeLocation
businessPhones {425-555-0100}
surname AdministratorNext steps
For more information about navigating Microsoft Graph PowerShell, see:
Not a reader? Watch this related video tutorial:
