- 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" -UseDeviceAuthenticationThis 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 $AccessTokenThis 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\$CertThumbprintPS C:\> Connect-MgGraph -ClientId "YOUR_APP_ID" -TenantId "YOUR_TENANT_ID" -Certificate $CertFollow 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 $ClientSecretCredentialThis 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 -IdentityUses 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-MgEnvironmentName AzureADEndpoint GraphEndpoint Type---- --------------- ------------- ----China https://login.chinacloudapi.cn https://microsoftgraph.chinacloudapi.cn Built-inGlobal https://login.microsoftonline.com https://graph.microsoft.com Built-inUSGov https://login.microsoftonline.us https://graph.microsoft.us Built-inUSGovDoD https://login.microsoftonline.us https://dod-graph.microsoft.us Built-inPS C:\> Connect-MgGraph -Environment USGovWhen 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 ProcessTo 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
