Connect-MgGraph
Microsoft Graph PowerShell supports two types of authentication: delegated and 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.
Syntax
Connect-MgGraph
[[-Scopes] <String[]>]
[[-ClientId] <String>]
[-TenantId <String>]
[-ContextScope <ContextScope>]
[-Environment <String>]
[-UseDeviceCode]
[-ClientTimeout <Double>]
[-NoWelcome]
[-ProgressAction <ActionPreference>]
[<CommonParameters>]
Connect-MgGraph
[-ClientId] <String>
[[-CertificateSubjectName] <String>]
[[-CertificateThumbprint] <String>]
[-SendCertificateChain <Boolean>]
[-Certificate <X509Certificate2>]
[-TenantId <String>]
[-ContextScope <ContextScope>]
[-Environment <String>]
[-ClientTimeout <Double>]
[-NoWelcome]
[-ProgressAction <ActionPreference>]
[<CommonParameters>]
Connect-MgGraph
[[-ClientId] <String>]
[-ContextScope <ContextScope>]
[-Environment <String>]
[-ClientTimeout <Double>]
[-Identity]
[-NoWelcome]
[-ProgressAction <ActionPreference>]
[<CommonParameters>]
Connect-MgGraph
[-ClientSecretCredential <PSCredential>]
[-TenantId <String>]
[-ContextScope <ContextScope>]
[-Environment <String>]
[-ClientTimeout <Double>]
[-NoWelcome]
[-ProgressAction <ActionPreference>]
[<CommonParameters>]
Connect-MgGraph
[-AccessToken] <SecureString>
[-Environment <String>]
[-ClientTimeout <Double>]
[-NoWelcome]
[-ProgressAction <ActionPreference>]
[<CommonParameters>]
Connect-MgGraph
[-ContextScope <ContextScope>]
[-Environment <String>]
[-ClientTimeout <Double>]
[-EnvironmentVariable]
[-NoWelcome]
[-ProgressAction <ActionPreference>]
[<CommonParameters>]
Description
You must invoke Connect-MgGraph before any commands that access Microsoft Graph. This cmdlet gets the access token using the Microsoft Authentication Library
Examples
Example 1: Delegated access: Using interactive authentication, where you provide the scopes that you require during your session
PS C:\> Connect-MgGraph -Scopes "User.Read.All", "Group.ReadWrite.All"
This example shows how to authenticate to graph with scopes.
Example 2: Delegated access: Using device code flow
PS C:\> Connect-MgGraph -Scopes "User.Read.All", "Group.ReadWrite.All" -UseDeviceAuthentication
This example shows how to authenticate to graph with scopes and device.
Example 3: Delegated access: Using your own access token
PS C:\> Connect-MgGraph -AccessToken $AccessToken
This example shows how to authenticate to graph using an access token.
Example 4: Delegated access: custom application for Microsoft Graph PowerShell
PS C:\> Connect-MgGraph -ClientId <YOUR_NEW_APP_ID> -TenantId <YOUR_TENANT_ID>
Follow this link (https://learn.microsoft.com/en-us/powershell/microsoftgraph/authentication-commands?view=graph-powershell-1.0#using-connect-mggraph)for more information on the steps for creating custom applications.
Example 5: App-only access: Using client credential with a certificate - Certificate Thumbprint
PS C:\> Connect-MgGraph -ClientId "YOUR_APP_ID" -TenantId "YOUR_TENANT_ID" -CertificateThumbprint "YOUR_CERT_THUMBPRINT"
Follow this link (https://learn.microsoft.com/en-us/powershell/microsoftgraph/authentication-commands?view=graph-powershell-1.0#using-connect-mggraph)for more information on how to load the certificate.
Example 6: App-only access: Using client credential with a certificate - Certificate name
PS C:\> Connect-MgGraph -ClientId "YOUR_APP_ID" -TenantId "YOUR_TENANT_ID" -CertificateName "YOUR_CERT_SUBJECT"
Follow this link (https://learn.microsoft.com/en-us/powershell/microsoftgraph/authentication-commands?view=graph-powershell-1.0#using-connect-mggraph)for more information on how to load the certificate.
Example 7: App-only access: Using client credential with a certificate - Certificate
PS C:\> $Cert = Get-ChildItem Cert:\LocalMachine\My\$CertThumbprint
PS C:\> Connect-MgGraph -ClientId "YOUR_APP_ID" -TenantId "YOUR_TENANT_ID" -Certificate $Cert
Follow this link (https://learn.microsoft.com/en-us/powershell/microsoftgraph/authentication-commands?view=graph-powershell-1.0#using-connect-mggraph)for more information on how to load the certificate.
Example 8: Using client secret credentials
PS C:\> $ClientSecretCredential = Get-Credential -Credential "Client_Id"
# Enter client_secret in the password prompt.
PS C:\> Connect-MgGraph -TenantId "Tenant_Id" -ClientSecretCredential $ClientSecretCredential
This authentication method is ideal for background interactions. It does not require a user to physically sign in.
Example 9: Using managed identity: System-assigned managed identity
PS C:\> Connect-MgGraph -Identity
Uses an automatically managed identity on a service instance. The identity is tied to the lifecycle of a service instance.
Example 10: Using managed identity: User-assigned managed identity
PS C:\> Connect-MgGraph -Identity -ClientId "User_Assigned_Managed_identity_Client_Id"
Uses a user created managed identity as a standalone Azure resource.
Example 11: Connecting to an environment or cloud
PS C:\> Get-MgEnvironment
Name 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-in
PS C:\> Connect-MgGraph -Environment USGov
When you use Connect-MgGraph, you can choose to target other environments. By default, Connect-MgGraph targets the global public cloud.
Example 12: Connecting to an environment as a different identity
PS C:\> Connect-MgGraph -ContextScope Process
To connect as a different identity other than CurrentUser, specify the -ContextScope parameter with the value Process.
Parameters
-AccessToken
Specifies a bearer token for Microsoft Graph service. Access tokens do timeout and you'll have to handle their refresh.
Type: | SecureString |
Position: | 1 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Certificate
An X.509 certificate supplied during invocation.
Type: | X509Certificate2 |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-CertificateSubjectName
The subject distinguished name of a certificate. The Certificate will be retrieved from the current user's certificate store.
Type: | String |
Aliases: | CertificateSubject, CertificateName |
Position: | 2 |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-CertificateThumbprint
The thumbprint of your certificate. The Certificate will be retrieved from the current user's certificate store.
Type: | String |
Position: | 3 |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ClientId
The client id of your application.
Type: | String |
Aliases: | AppId, ApplicationId |
Position: | 1 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ClientSecretCredential
The PSCredential object provides the application ID and client secret for service principal credentials. For more information about the PSCredential object, type Get-Help Get-Credential.
Type: | PSCredential |
Aliases: | SecretCredential, Credential |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ClientTimeout
Sets the HTTP client timeout in seconds.
Type: | Double |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ContextScope
Determines the scope of authentication context. This accepts `Process` for the current process, or `CurrentUser` for all sessions started by user.
Type: | ContextScope |
Accepted values: | Process, CurrentUser |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Environment
The name of the national cloud environment to connect to. By default global cloud is used.
Type: | String |
Aliases: | EnvironmentName, NationalCloud |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-EnvironmentVariable
Allows for authentication using environment variables configured on the host machine. See https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/identity/Azure.Identity#environment-variables.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Identity
Login using a Managed Identity.
Type: | SwitchParameter |
Aliases: | ManagedIdentity, ManagedServiceIdentity, MSI |
Position: | 1 |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-NoWelcome
Hides the welcome message.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ProgressAction
{{ Fill ProgressAction Description }}
Type: | ActionPreference |
Aliases: | proga |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Scopes
An array of delegated permissions to consent to.
Type: | String[] |
Position: | 1 |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SendCertificateChain
Include x5c header in client claims when acquiring a token to enable subject name / issuer based authentication using given certificate.
Type: | Boolean |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-TenantId
The id of the tenant to connect to. You can also use this parameter to specify your sign-in audience. i.e., common, organizations, or consumers. See https://docs.microsoft.com/en-us/azure/active-directory/develop/msal-client-application-configuration#authority.
Type: | String |
Aliases: | Audience, Tenant |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-UseDeviceCode
Use device code authentication instead of a browser control.
Type: | SwitchParameter |
Aliases: | UseDeviceAuthentication, DeviceCode, DeviceAuth, Device |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Inputs
None
Outputs
System.Object