Connect-MgGraph

  • Reference
Module:
Microsoft.Graph.Authentication

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