Connect-Entra

Module:: Microsoft.Entra Module v1.1

Connect to Microsoft Entra ID with an authenticated account.

Syntax

UserParameterSet (Default)

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

AppCertificateParameterSet

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

IdentityParameterSet

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

AppSecretCredentialParameterSet

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

AccessTokenParameterSet

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

EnvironmentVariableParameterSet

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

Description

The Connect-Entra cmdlet connects to Microsoft Entra ID with an authenticated account.

Several authentication scenarios are supported based on your use case, such as delegated (interactive) and app-only (non-interactive).

Connect-Entra is an alias for Connect-MgGraph.

Examples

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

Connect-Entra

This example shows how to connect your 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 interactively 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 interactively authenticate to Microsoft Entra ID using device code flow.

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 example shows how to authenticate using an 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.

Parameter properties

Type:	SecureString
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

AccessTokenParameterSet

Position:	Named
Mandatory:	True
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-Certificate

An X.509 certificate supplied during invocation.

Parameter properties

Type:	X509Certificate2
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

AppCertificateParameterSet

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-CertificateSubjectName

The subject distinguished name of a certificate. The certificate is 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

AppCertificateParameterSet

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	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.

Parameter properties

Type:	System.String
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

AppCertificateParameterSet

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-ClientId

Specifies the application ID of the service principal.

Parameter properties

Type:	System.String
Default value:	None
Supports wildcards:	False
DontShow:	False
Aliases:	AppId, ApplicationId

Parameter sets

UserParameterSet

Position:	1
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

IdentityParameterSet

Position:	1
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

AppCertificateParameterSet

Position:	1
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	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.

Parameter properties

Type:	PSCredential
Default value:	None
Supports wildcards:	False
DontShow:	False
Aliases:	SecretCredential, Credential

Parameter sets

AppSecretCredentialParameterSet

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-ClientTimeout

Sets the HTTP client timeout in seconds.

Parameter properties

Type:	System.Double
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

(All)

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-ContextScope

Determines the scope of authentication context. This ContextScope accepts Process for the current process, or CurrentUser for all sessions started by user.

Parameter properties

Type:	ContextScope
Default value:	None
Accepted values:	Process, CurrentUser
Supports wildcards:	False
DontShow:	False

Parameter sets

UserParameterSet

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

AppCertificateParameterSet

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

IdentityParameterSet

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

AppSecretCredentialParameterSet

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

EnvironmentVariableParameterSet

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-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

(All)

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	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

Parameter properties

Type:	System.Management.Automation.SwitchParameter
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

EnvironmentVariableParameterSet

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-Identity

Sign-in using a managed identity

Parameter properties

Type:	System.Management.Automation.SwitchParameter
Default value:	None
Supports wildcards:	False
DontShow:	False
Aliases:	ManagedIdentity, ManagedServiceIdentity, MSI

Parameter sets

IdentityParameterSet

Position:	1
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-NoWelcome

Hides the welcome message.

Parameter properties

Type:	System.Management.Automation.SwitchParameter
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

(All)

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-Scopes

An array of delegated permissions to consent to.

Parameter properties

Type:	System.String[]
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

UserParameterSet

Position:	1
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-SendCertificateChain

Include x5c header in client claims when acquiring a token to enable subject name / issuer based authentication using given certificate.

Parameter properties

Type:	Boolean
Default value:	None
Supports wildcards:	False
DontShow:	False

Parameter sets

AppCertificateParameterSet

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	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.

Parameter properties

Type:	System.String
Default value:	None
Supports wildcards:	False
DontShow:	False
Aliases:	Audience, Tenant

Parameter sets

UserParameterSet

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

AppCertificateParameterSet

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

AppSecretCredentialParameterSet

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

-UseDeviceCode

Use device code authentication instead of a browser control.

Parameter properties

Type:	System.Management.Automation.SwitchParameter
Default value:	None
Supports wildcards:	False
DontShow:	False
Aliases:	UseDeviceAuthentication, DeviceCode, DeviceAuth, Device

Parameter sets

UserParameterSet

Position:	Named
Mandatory:	False
Value from pipeline:	False
Value from pipeline by property name:	False
Value from remaining arguments:	False

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.

Disconnect-Entra

Share via

Connect-Entra

Syntax

UserParameterSet (Default)

AppCertificateParameterSet

IdentityParameterSet

AppSecretCredentialParameterSet

AccessTokenParameterSet

EnvironmentVariableParameterSet

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

Parameter properties

Parameter sets

-Certificate

Parameter properties

Parameter sets

-CertificateSubjectName

Parameter properties

Parameter sets

-CertificateThumbprint

Parameter properties

Parameter sets

-ClientId

Parameter properties

Parameter sets

-ClientSecretCredential

Parameter properties

Parameter sets

-ClientTimeout

Parameter properties

Parameter sets

-ContextScope

Parameter properties

Parameter sets

-Environment

Parameter properties

Parameter sets

-EnvironmentVariable

Parameter properties

Parameter sets

-Identity

Parameter properties

Parameter sets

-NoWelcome

Parameter properties

Parameter sets

-Scopes

Parameter properties

Parameter sets

-SendCertificateChain

Parameter properties

Parameter sets

-TenantId

Parameter properties

Parameter sets

-UseDeviceCode

Parameter properties

Parameter sets

CommonParameters

Related Links

Feedback