Connect-Entra

Reference

Module:: Microsoft.Graph.Entra

Connects with an authenticated account to use Microsoft Entra PowerShell cmdlet requests.

This module supports several authentication scenarios depending on your use case such as: delegated (interactive) and app-only (noninteractive).

Syntax

Connect-Entra
       [[-Scopes] <String[]>]
       [[-ClientId] <String>]
       [-TenantId <String>][-ContextScope <ContextScope>]
       [-Environment <String>]
       [-UseDeviceCode]
       [-ClientTimeout <Double>]
       [-NoWelcome][<CommonParameters>]

Connect-Entra
       [-ClientId] <String>
       [[-CertificateSubjectName] <String>]
       [[-CertificateThumbprint] <String>][-Certificate <X509Certificate2>]
       [-TenantId <String>]
       [-ContextScope <ContextScope>]
       [-Environment <String>][-ClientTimeout <Double>]
       [-NoWelcome]
       [<CommonParameters>]

Connect-Entra
       [[-ClientId] <String>]
       [-ContextScope <ContextScope>]
       [-Environment <String>][-ClientTimeout <Double>]
       [-Identity]
       [-NoWelcome]
       [<CommonParameters>]

Connect-Entra
       [-ClientSecretCredential <PSCredential>]
       [-TenantId <String>]
       [-ContextScope <ContextScope>][-Environment <String>]
       [-ClientTimeout <Double>]
       [-NoWelcome]
       [<CommonParameters>]

Connect-Entra
       [-AccessToken] <SecureString>
       [-Environment <String>]
       [-ClientTimeout <Double>]
       [-NoWelcome][<CommonParameters>]

Connect-Entra
       [-ContextScope <ContextScope>]
       [-Environment <String>]
       [-ClientTimeout <Double>][-EnvironmentVariable]
       [-NoWelcome]
       [<CommonParameters>]

Description

The Connect-Entra cmdlet connects to Microsoft Entra ID with an authenticated account for use with cmdlets from the Microsoft Entra PowerShell module.

Examples

Example 1: Delegated access: Connect a PowerShell session to a tenant

Connect-Entra

This command connects the current PowerShell session to a Microsoft Entra ID tenant using credentials.

Example 2: Delegated access: Connect a PowerShell session to a tenant with required scopes

Connect-Entra -Scopes 'User.Read.All', 'Group.ReadWrite.All'

Welcome to Microsoft Graph!

This example shows how to authenticate to Microsoft Entra ID with scopes.

Example 3: Delegated access: Using an access token

$secureString = ConvertTo-SecureString -String $AccessToken -AsPlainText -Force
Connect-Entra -AccessToken $secureString

Welcome to Microsoft Graph!

This example shows how to authenticate to Microsoft Entra ID using an access token.

For more information on how to get or create access token, see Request an access token.

Example 4: Delegated access: Using device code flow

Connect-Entra -UseDeviceCode

To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code A1B2CDEFGH to authenticate.

This example shows how to authenticate to Microsoft Entra ID with device.

For more information, see Device Code flow.

Example 5: App-only access: Using client credential with a Certificate thumbprint

$connectParams = @{
    TenantId = 'aaaabbbb-0000-cccc-1111-dddd2222eeee'
    ApplicationId = '00001111-aaaa-2222-bbbb-3333cccc4444'
    CertificateThumbprint = 'AA11BB22CC33DD44EE55FF66AA77BB88CC99DD00'
}

Connect-Entra @connectParams

Welcome to Microsoft Graph!

This command Connect a session using a ApplicationId and CertificateThumbprint.

For more information on how to get or create CertificateThumbprint, see Authenticate with app-only access.

Example 6: App-only access: Using client credential with a certificate name

$params = @{
    ClientId = '00001111-aaaa-2222-bbbb-3333cccc4444'
    TenantId = 'aaaabbbb-0000-cccc-1111-dddd2222eeee'
    CertificateName = 'YOUR_CERT_SUBJECT'
}

Connect-Entra @params

$Cert = Get-ChildItem Cert:\LocalMachine\My\$CertThumbprint
 Connect-Entra -ClientId '<App-Id>' -TenantId '<Tenant-Id>' -Certificate $Cert

You can find the certificate subject by running the above command.

Example 7: App-only access: Using client credential with a certificate

$Cert = Get-ChildItem Cert:\LocalMachine\My\$CertThumbprint
$params = @{
    ClientId = '00001111-aaaa-2222-bbbb-3333cccc4444'
    TenantId = 'aaaabbbb-0000-cccc-1111-dddd2222eeee'
    Certificate = $Cert
}

Connect-Entra @params

Example 8: App-only access: Using client secret credentials

$ClientSecretCredential = Get-Credential -Credential '00001111-aaaa-2222-bbbb-3333cccc4444'
# Enter client_secret in the password prompt.
Connect-Entra -TenantId 'aaaabbbb-0000-cccc-1111-dddd2222eeee' -ClientSecretCredential $ClientSecretCredential

This authentication method is ideal for background interactions.

For more information on how to get credential, see Get-Credential command.

Example 9: App-only access: Using managed identity: System-assigned managed identity

Connect-Entra -Identity

Uses an automatically managed identity on a service instance. The identity is tied to the lifecycle of a service instance.

Example 10: App-only access: Using managed identity: User-assigned managed identity

Connect-Entra -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 as a different identity

Connect-Entra -ContextScope 'Process'

Welcome to Microsoft Graph!

To connect as a different identity other than CurrentUser, specify the ContextScope parameter with the value Process.

For more information on how to get the current context, see Get-EntraContext command.

Example 12: Connecting to an environment or cloud

Get-EntraEnvironment

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

Connect-Entra -Environment 'Global'

When you use Connect-Entra, you can choose to target other environments. By default, Connect-Entra targets the global public cloud.

Example 13: Sets the HTTP client timeout in seconds

Connect-Entra -ClientTimeout 60

Welcome to Microsoft Graph!

This example Sets the HTTP client timeout in seconds.

Example 14: Hides the welcome message

Connect-Entra -NoWelcome

This example hides the welcome message.

Example 15: Allows for authentication using environment variables

Connect-Entra -EnvironmentVariable

This example allows for authentication using environment variables.

Parameters

-AccessToken

Specifies a bearer token for Microsoft Entra service. Access tokens do time out and you have to handle their refresh.

Type:	SecureString
Position:	Named
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 is retrieved from the current user's certificate store.

Type:	System.String
Aliases:	CertificateSubject, CertificateName
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-CertificateThumbprint

Specifies the certificate thumbprint of a digital public key X.509 certificate of a user account that has permission to perform this action.

Type:	System.String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ClientId

Specifies the application ID of the service principal.

Type:	System.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:	System.Double
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ContextScope

Determines the scope of authentication context. This ContextScope 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:	System.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:	System.Management.Automation.SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Identity

Sign-in using a managed identity

Type:	System.Management.Automation.SwitchParameter
Aliases:	ManagedIdentity, ManagedServiceIdentity, MSI
Position:	1
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-NoWelcome

Hides the welcome message.

Type:	System.Management.Automation.SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ProgressAction

The ProgressAction parameter takes one of the ActionPreference enumeration values: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend, or Break.

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:	System.String[]
Position:	1
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-TenantId

Specifies the ID of a tenant.

If you don't specify this parameter, the account is authenticated with the home tenant.

You must specify the TenantId parameter to authenticate as a service principal or when using Microsoft account.

Type:	System.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:	System.Management.Automation.SwitchParameter
Aliases:	UseDeviceAuthentication, DeviceCode, DeviceAuth, Device
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

Disconnect-Entra

Share via

Connect-Entra

Syntax

Description

Examples

Example 1: Delegated access: Connect a PowerShell session to a tenant

Example 2: Delegated access: Connect a PowerShell session to a tenant with required scopes

Example 3: Delegated access: Using an access token

Example 4: Delegated access: Using device code flow

Example 5: App-only access: Using client credential with a Certificate thumbprint

Example 6: App-only access: Using client credential with a certificate name

Example 7: App-only access: Using client credential with a certificate

Example 8: App-only access: Using client secret credentials

Example 9: App-only access: Using managed identity: System-assigned managed identity

Example 10: App-only access: Using managed identity: User-assigned managed identity

Example 11: Connecting to an environment as a different identity

Example 12: Connecting to an environment or cloud

Example 13: Sets the HTTP client timeout in seconds

Example 14: Hides the welcome message

Example 15: Allows for authentication using environment variables

Parameters

-AccessToken

-Certificate

-CertificateSubjectName

-CertificateThumbprint

-ClientId

-ClientSecretCredential

-ClientTimeout

-ContextScope

-Environment

-EnvironmentVariable

-Identity

-NoWelcome

-ProgressAction

-Scopes

-TenantId

-UseDeviceCode

Feedback

Feedback

Additional resources

Share via

Connect-Entra

Syntax

Description

Examples

Example 1: Delegated access: Connect a PowerShell session to a tenant

Example 2: Delegated access: Connect a PowerShell session to a tenant with required scopes

Example 3: Delegated access: Using an access token

Example 4: Delegated access: Using device code flow

Example 5: App-only access: Using client credential with a Certificate thumbprint

Example 6: App-only access: Using client credential with a certificate name

Example 7: App-only access: Using client credential with a certificate

Example 8: App-only access: Using client secret credentials

Example 9: App-only access: Using managed identity: System-assigned managed identity

Example 10: App-only access: Using managed identity: User-assigned managed identity

Example 11: Connecting to an environment as a different identity

Example 12: Connecting to an environment or cloud

Example 13: Sets the HTTP client timeout in seconds

Example 14: Hides the welcome message

Example 15: Allows for authentication using environment variables

Parameters

-AccessToken

-Certificate

-CertificateSubjectName

-CertificateThumbprint

-ClientId

-ClientSecretCredential

-ClientTimeout

-ContextScope

-Environment

-EnvironmentVariable

-Identity

-NoWelcome

-ProgressAction

-Scopes

-TenantId

-UseDeviceCode

Related Links

Feedback

Feedback

Additional resources