Note
Access to this page requires authorization. You can try signing in or .
Access to this page requires authorization. You can try .
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
UserParameterSet (Default)
Connect-MgGraph
[[-Scopes] <string[]>]
[[-TenantId] <string>]
[-ClientId <string>]
[-ContextScope <ContextScope>]
[-Environment <string>]
[-UseDeviceCode]
[-ClientTimeout <double>]
[-NoWelcome]
[-Break]
[<CommonParameters>]
AppCertificateParameterSet
Connect-MgGraph
[-ClientId] <string>
[[-CertificateSubjectName] <string>]
[[-CertificateThumbprint] <string>]
[-SendCertificateChain <bool>]
[-Certificate <X509Certificate2>]
[-TenantId <string>]
[-ContextScope <ContextScope>]
[-Environment <string>]
[-ClientTimeout <double>]
[-NoWelcome]
[-Break]
[<CommonParameters>]
IdentityParameterSet
Connect-MgGraph
[-Identity]
[-ClientId <string>]
[-ContextScope <ContextScope>]
[-Environment <string>]
[-ClientTimeout <double>]
[-NoWelcome]
[-Break]
[<CommonParameters>]
AppSecretCredentialParameterSet
Connect-MgGraph
[-ClientSecretCredential <pscredential>]
[-TenantId <string>]
[-ContextScope <ContextScope>]
[-Environment <string>]
[-ClientTimeout <double>]
[-NoWelcome]
[-Break]
[<CommonParameters>]
AccessTokenParameterSet
Connect-MgGraph
[-AccessToken] <securestring>
[-Environment <string>]
[-ClientTimeout <double>]
[-NoWelcome]
[-Break]
[<CommonParameters>]
EnvironmentVariableParameterSet
Connect-MgGraph
[-ContextScope <ContextScope>]
[-Environment <string>]
[-ClientTimeout <double>]
[-EnvironmentVariable]
[-NoWelcome]
[-Break]
[<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
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.
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.
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.
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.
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.
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.
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.
Using client secret credentials
PS C:> $ClientSecretCredential = Get-Credential -Credential "Client_Id"
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.
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.
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.
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.
Parameter properties
| Type: | System.Security.SecureString |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-Break
Wait for .NET debugger to attach
Parameter properties
| Type: | System.Management.Automation.SwitchParameter |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-Certificate
An X.509 certificate supplied during invocation.
Parameter properties
| Type: | System.Security.Cryptography.X509Certificates.X509Certificate2 |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-CertificateSubjectName
The subject distinguished name of a certificate. The Certificate will be retrieved from the current user's certificate store.
Parameter properties
| Type: | System.String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | CertificateSubject, CertificateName |
Parameter sets
-CertificateThumbprint
The thumbprint of your certificate. The Certificate will be retrieved from the current user's certificate store.
Parameter properties
| Type: | System.String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-ClientId
The client id of your application.
Parameter properties
| Type: | System.String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | AppId, ApplicationId |
Parameter sets
-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.
Parameter properties
| Type: | System.Management.Automation.PSCredential |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | SecretCredential, Credential |
Parameter sets
-ClientTimeout
Sets the HTTP client timeout in seconds.
Parameter properties
| Type: | System.Double |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-ContextScope
Determines the scope of authentication context.
This accepts Process for the current process, or CurrentUser for all sessions started by user.
Parameter properties
| Type: | Microsoft.Graph.PowerShell.Authentication.ContextScope |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-Environment
The name of the national cloud environment to connect to. By default global cloud is used.
Parameter properties
| Type: | System.String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | EnvironmentName, NationalCloud |
Parameter sets
-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.
Parameter properties
| Type: | System.Management.Automation.SwitchParameter |
| Default value: | False |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-Identity
Login using a Managed Identity.
Parameter properties
| Type: | System.Management.Automation.SwitchParameter |
| Default value: | False |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | ManagedIdentity, ManagedServiceIdentity, MSI |
Parameter sets
-NoWelcome
Hides the welcome message.
Parameter properties
| Type: | System.Management.Automation.SwitchParameter |
| Default value: | False |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-Scopes
An array of delegated permissions to consent to.
Parameter properties
| Type: | System.String[] |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-SendCertificateChain
Include x5c header in client claims when acquiring a token to enable subject name / issuer based authentication using given certificate.
Parameter properties
| Type: | System.Boolean |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
-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.
Parameter properties
| Type: | System.String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | Audience, Tenant |
Parameter sets
-UseDeviceCode
Use device code authentication instead of a browser control.
Parameter properties
| Type: | System.Management.Automation.SwitchParameter |
| Default value: | False |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | UseDeviceAuthentication, DeviceCode, DeviceAuth, Device |
Parameter sets
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.