Skip to content

authentication.md

Latest commit

 

History

History
137 lines (88 loc) · 5.11 KB

authentication.md

File metadata and controls

137 lines (88 loc) · 5.11 KB

Auth with Microsoft Graph PowerShell

The Microsoft Graph PowerShell module supports two types of authentication:

  • Delegated Access
  • App-only Access

Delegated Access

Delegated access uses a public client to get an access token and consume Microsoft Graph resources on behalf of the signed-in user.

Microsoft Graph PowerShell module supports the following delegated access scenarios:

Interactive Browser

Connect-MgGraph -Scopes "User.ReadBasic.All", "Calendars.Read.Shared"

Device Code

Connect-MgGraph -Scopes "User.ReadBasic.All", "Calendars.Read.Shared" -UseDeviceCode

App-only Access

App-only access uses a confidential client to get an access token and consume Microsoft Graph resources without a user context (uses an app's context).

Microsoft Graph PowerShell module supports the following app-only access scenarios:

Client credential via a certificate

Load certificate from store using a certificate's thumbprint.

Connect-MgGraph -ClientId "Client_Id" -TenantId "Tenant_Id" -CertificateThumbprint "Cert_Thumbprint"

Load certificate from store using a certificate's subject name.

Connect-MgGraph -ClientId "Client_Id" -TenantId "Tenant_Id" -CertificateSubjectName "Cert_Subject_Name"

Load certificate from file.

$Cert = Get-ChildItem Cert:\LocalMachine\My\$CertThumbprint
Connect-MgGraph -ClientId "Client_Id" -TenantId "Tenant_Id" -Certificate $Cert

Using environment variables.

# Add environment variables to be used by Connect-MgGraph.
$Env:AZURE_CLIENT_ID = "application id of the client app"
$Env:AZURE_TENANT_ID = "Id of your tenant"
$Env:AZURE_CLIENT_CERTIFICATE_PATH = "path to a PFX or PEM-encoded certificate file including private key"

# Tell Connect-MgGraph to use your environment variables.
Connect-MgGraph -EnvironmentVariable

Client credential via client secret

Using PSCredential object.

$ClientSecretCredential = Get-Credential -Username "Client_Id"
# Enter client_secret in the password prompt.
Connect-MgGraph -TenantId "Tenant_Id" -ClientSecretCredential $ClientSecretCredential

Using environment variables.

# Add environment variables to be used by Connect-MgGraph.
$Env:AZURE_CLIENT_ID = "application id of the client app"
$Env:AZURE_TENANT_ID = "Id of your tenant"
$Env:AZURE_CLIENT_SECRET = "secret of the client app"

# Tell Connect-MgGraph to use your environment variables.
Connect-MgGraph -EnvironmentVariable

Managed Identity

System-assigned managed identity

Connect-MgGraph -Identity

User-assigned managed identity

Connect-MgGraph -Identity -ClientId "User_Assigned_Managed_identity_Client_Id"

Bring Your Own Token

Customers can acquire an access token using their preferred auth library and pass the access token to the Microsoft Graph PowerShell module using -AccessToken parameter on Connect-MgGraph. The module will then use the provided access token to consume Microsoft Graph resources.

The following considerations should be made before using -AccessToken:

Access Token Expiry

When using -AccessToken, we won't have access to the refresh token and the client id needed to refresh an access token when it has expired. Customers should ensure that the task they are running using the provided access token will finish within the access token's exp claim (expiry time). This is typically 60 minutes for most access tokens. The expiry time may vary depending on the CAE policy in place.

Access Token Scopes (scp) Claims

Before using the provided -AccessToken to get Microsoft Graph resources, customers should ensure that the access token has the necessary scopes/ permissions needed to access/modify a resource.

Web Account Manager (WAM)

WAM is a Windows 10+ component that acts as an authentication broker allowing the users of an app benefit from integration with accounts known to Windows, such as the account already signed into an active Windows session.

Microsoft Graph PowerShell module supports WAM in the following scenario:

  • To disable WAM on supported devices (requires a custom ClientId)
Set-MgGraphOption -DisableLoginByWAM $true
  • To re-enable WAM after disabling it
Set-MgGraphOption -DisableLoginByWAM $false

Note: Signin by Web Account Manager (WAM) is enabled by default on Windows and cannot be disabled. Setting this option to $False will have no effect on Windows systems. Except if you use your own app (see below)

Starting with v2.35.1, to disable WAM on Windows, use Set-MgGraphOption -DisableLoginByWAM $true and then connect with a custom -ClientId. To create your custom app, follow the guide to Use delegated access with a custom application for Microsoft Graph PowerShell. You should also add the redirect URI of ms-appx-web://Microsoft.AAD.BrokerPlugin/<yourAppId> to ensure that you can use WAM against that app registration as well.