Authenticating to Microsoft Workloads using PowerShell

2024-11-28

In today's world, administrators must have about a dozen different PowerShell modules under their tool belt. It seems as if every workload out there has its own PowerShell module to allow you to administer its related configuration settings; add to this the fact that every module has its own intricacy for how it let's you authenticate. For Entra Id and Intune we have the Microsoft Graph PowerShell SDK, for Teams, we have the Teams PowerShell module, for Exchange Online, there's the Exchange Online Management Shell, etc. To help simplify the overall authentication process, we put together the MSCloudLoginAssistant module, which acts as an abstraction layer sitting on top of all these modules and provies a coherent and streamlined way to authenticate to them.

In today's article, I want to spend time walking down the authentication stack for each of the major workloads that are supported by Microsoft365DSC. For each one, we will describe how to authenticate using MSCloudLoginAssistant, but we'll also double click on how this module in turns authenticate to the lower layers by calling the workloads' specific PowerShell module directly. As part of this article, we will only focus on the Service Principal with certificate thumbprint flow. We will not cover the process of configuring a new App Registration in Entra ID as part of the article as therer are plenty of literature on the topic out there. We simply assume that you created your own app registration, and uploaded a certificate's public key to it, and that you have access to install the associated private key on your mahcine.

For each workload we will provide the instructions to connect via the MSCloudLoginAssistant module, via its native PowerShell module and we will provide additional information about how you can leverage Microsoft365DSC to have the Local Configuration Manager (LCM) service authenticate. It is important to understand that the LCM always runs in the context of the Local System and therefore having the certificate stored in the current user's store is not sufficient in a lot of cases.

Microsoft Graph (Entra Id and Intune)⚓

Both of the Entra Id and Intune workloads in Microsoft365DSC are leveraging the various Microsoft.Graph.* PowerShell modules. In order to authenticate with the Microsoft Graph PowerShell module, you simply need to have the certificate stored in your current user's store.

Certificate in the local user's store.

Via MSCloudLoginAssistant⚓

Connect-M365Tenant -Workload 'MicrosoftGraph' `
                   -ApplicationId '<your app id>' `
                   -TenantId '<your tenant>.onmicrosoft.com' `
                   -CertificateThumbprint '<your thumbprint>'

Connecting to Microsoft Graph via MSCloudLoginAssistant.

Via Microsoft.Graph.Authentication⚓

Connect-MgGraph -ClientId '<your app id>' `
                -TenantId '<your tenant>.onmicrosoft.com' `
                -CertificateThumbprint '<your thumbprint>'

Connecting to Microsoft Graph via Microsoft Graph PowerShell SDK.

Local Configuration Management⚓

Because the LCM service runs as the local system, we need to install the certificate in the Local Computer's store as well. If you omit to install the certificate in there as well, the LCM will not be able to authenticate to the Microsoft Graph.

Installing the certificate in the Local Machine's store.

Exchange Online⚓

Managing Exchange Online is done via the ExchangeOnlineManagement module. It is sufficient for you to have the certificate in the current user's store to authenticate. However, in this case, the associated application will also need to be granted the Manage as App permission, and an Entra Id role sufficient to manage Exchange. Refer to the official Exchange Online documentation for additional details.

Via MSCloudLoginAssistant⚓

Connect-M365Tenant -Workload 'ExchangeOnline' `
                   -ApplicationId '<your app id>' `
                   -TenantId '<your tenant>.onmicrosoft.com' `
                   -CertificateThumbprint '<your thumbprint>'

Connecting to Exchange Online via MSCloudLoginAssistant.

Via ExchangeOnlineManagement⚓

Connect-ExchangeOnline -AppId '<your app id>' `
                       -Organization '<your tenant>.onmicrosoft.com' `
                       -CertificateThumbprint '<your thumbprint>'

Connecting to Exchange Online via ExchangeOnlineManagement.

Local Configuration Management⚓

LCM requires the certificate to be installed in the Local Machine's store in order to authenticate.

Security and Compliance (Defender & Purview)⚓

Managing Defender and Purview is also is done via the ExchangeOnlineManagement module. Again, it is sufficient for you to have the certificate in the current user's store to authenticate. However, in this case, the associated application will also need to be granted the Manage as App permission, and an Entra Id role sufficient to manage Defender & Purview. Refer to the official Security & Compliance center documentation for additional details.

Via MSCloudLoginAssistant⚓

Connect-M365Tenant -Workload 'SecurityComplianceCenter' `
                   -ApplicationId '<your app id>' `
                   -TenantId '<your tenant>.onmicrosoft.com' `
                   -CertificateThumbprint '<your thumbprint>'

Connecting to Security and Compliance via MSCloudLoginAssistant.

Via ExchangeOnlineManagement⚓

Connect-IPPSSession -AppId '<your app id>' `
                    -Organization '<your tenant>.onmicrosoft.com' `
                    -CertificateThumbprint '<your thumbprint>'

Connecting to Security and Compliance Center via ExchangeOnlineManagement.

Local Configuration Management⚓

LCM requires the certificate to be installed in the Local Machine's store in order to authenticate.

SharePoint Online⚓

In the case of Microsoft365DSC, the authentication to SharePoint Online is done via the PnP.PowerShell module. It is sufficient to have the certificate u=in the current user's store to authenticate. You will also need to make sure that the app registration is granted the Sites.FullControl.All permission for the SharePoint API (not Microsoft Graph!).

Via MSCloudLoginAssistant⚓

Connect-M365Tenant -Workload 'PnP' `
                   -ApplicationId '<your app id>' `
                   -TenantId '<your tenant>.onmicrosoft.com' `
                   -CertificateThumbprint '<your thumbprint>'

Connecting to SharePoint Online via MSCloudLoginAssistant.

Via PnP.PowerShell⚓

Connect-PnPOnline -ClientId '<your app id>' `
                  -Tenant '<your tenant>.onmicrosoft.com' `
                  -Thumbprint '<your thumbprint>' `
                  -Url 'https://<your tenant>-admin.sharepoint.com'

Connecting to SharePoint Online via PnP.PowerShell.

Local Configuration Management⚓

LCM requires the certificate to be installed in the Local Machine's store in order to authenticate.

Power Platforms

Authentication to Power Platforms is handled by the Microsoft.PowerApps.Administration.PowerShell. This module currently only supports placing the certificate in the current user's store. In order to properly authenticate with the module, you will need to make sure you register your service principal as a Power App Management app. For details on how to do this, please refer to the official documentation.

Via MSCloudLoginAssistant⚓

Connect-M365Tenant -Workload 'PowerPlatforms' `
                   -ApplicationId '<your app id>' `
                   -TenantId '<your tenant>.onmicrosoft.com' `
                   -CertificateThumbprint '<your thumbprint>'

Connecting to Power Platforms via MSCloudLoginAssistant.

Via Microsoft.PowerApps.Administration.PowerShell⚓

Add-PowerAppsAccount -ApplicationId '<your app id>' `
                     -TenantId '<your tenant>.onmicrosoft.com' `
                     -CertificateThumbprint '<your thumbprint>'

Connecting to Power Platforms via Microsoft.PowerApps.Administration.PowerShell.

Local Configuration Management⚓

This is where things get a little more complicated. At the time of writing this article, the Power Platforms PowerShell module only supports looking into the current user's store and not in the local system's one. Because the LCM always runs as the Local System user, this means that we need to install the certificate in the current user's store of the Local System user. Currently, the best way to achieve this is to use a tool such as PSExec to let you launch the Management Console as the Local System user and install the certificate in its store.

      Download and install the PSTools under C:\tools
      Launch a new PowerShell console as admin.
      Browse to C:\tools, and execute ./Psexec.exe -i -s cmd.exe
      When prompted, click on Agree (only shown if it's the first time you use the tool).
      In the new command prompt that appeared, type in mmc.exe.
      In the contols that opened, press CTRL+M to open the add-in selection.
      Select the Certificates add-in and choose the My user account option. Click on Finish, then Ok.
      Selecting th user's certificate store for the local system.
      Expand Certificates - Curent User and select the Personal folder.
      In the Object Type panel, right-click and choose All Tasks > Import
      Importing a certificate.
      Click Next then browse to select the private key (.pfx) for your certificate. You will need to change the file type to Personal Information Exchangefirst.
      Importing a private key for a given certificate.
      Click Next then provide the password for your private key.
      Click Next twice and then on Finish to complete the import process.

Teams⚓

Authentication to Microsof Teams is handled by the MicrosoftTeams PowerShell module. Just like all the other modules, it supports placing the certificate in the current user's store.

Via MSCloudLoginAssistant⚓

Connect-M365Tenant -Workload 'MicrosoftTeams' `
                   -ApplicationId '<your app id>' `
                   -TenantId '<your tenant>.onmicrosoft.com' `
                   -CertificateThumbprint '<your thumbprint>'

Connecting to Microsoft Teams via MSCloudLoginAssistant.

Via MicrosoftTeams⚓

Connect-MicrosoftTeams -ApplicationId '<your app id>' `
                       -TenantId '<your tenant>.onmicrosoft.com' `
                       -CertificateThumbprint '<your thumbprint>'

Connecting to Microsoft Teams via MicrosoftTeams.

Local Configuration Management⚓

LCM requires the certificate to be installed in the Local Machine's store in order to authenticate.