Authentication and Permissions

Authentication Options

Each of the required modules used by Microsoft365DSC has its own authentication possibilities. So depending on the DSC resource you are using, there are several authentication options to choose from.

It is also very important to understand the authentication process of Microsoft365DSC. The solution supports connecting to the various workloads for either applying the configuration, monitoring it for configuration drifts or taking a snapshot of an existing configuration. There are two ways of authenticating to Microsoft 365:

  1. A set of credentials for a user
  2. A Service Principal by specifying parameters such as an Azure Active Directory (AD) Application ID, Tenant ID and a Secret or Certificate.

Currently, each Microsoft 365 workload can support a different combination of authentication methods because of the underlying modules only supporting those methods. The table in the next paragraph shows which workload uses which module and therefore supports which authentication method.

Important: The recommendation is to use Service Principal whenever possible because:

  • Service principals offers the most granular levels of security and do not introduce the risk of having to send high privileged credentials across the wire to authenticate.
  • Since Desired State Configuration is an unattended process, the use of Multi Factor Authentication for user credentials is not supported by Microsoft365DSC.
  • Note: The only exception here is creating an Export of an existing tenant. Most often this is an interactive process where the ask for a second factor is possible.

Authentication Methods

The following table provides an overview of what authentication methods are supported by which workload and what underlying module is being used to authenticate:

Workload PowerShell Module Credential Service Principal Managed Identity
Certificate Thumbprint Certificate Path Application Secret
AzureAD* Microsoft.Graph.Authentication
(Connect-MgGraph)		 Check Check Cross Check Check
Exchange Online ExchangeOnlineManagement
(Connect-ExchangeOnline)		 Check Check Check Cross Cross
Intune* Microsoft.Graph.Authentication
(Connect-MgGraph)		 Check Check Cross Check Cross
Office 365* Microsoft.Graph.Authentication
(Connect-MgGraph)		 Check Check Cross Check Check
OneDrive PnP.PowerShell (Connect-PnPOnline) Check Check Check Check Cross
Power Apps Microsoft.PowerApps.
Administration.PowerShell		 Check Check Cross Check Cross
Planner* Microsoft.Graph.Authentication
(Connect-MgGraph)		 Check Check Cross Check Cross
Security & Compliance Center ExchangeOnlineManagement
(Connect-IPPSSession)		 Check Check Check Cross Cross
SharePoint Online PnP.PowerShell
(Connect-PnPOnline)		 Check Check Check Check Cross
Teams MicrosoftTeams
(Connect-MicrosoftTeams)		 Check Check Cross Cross Cross

Check = Supported / Cross = Not supported

We are having discussions with the various product groups that are responsible for these PowerShell modules inside of Microsoft, to have better consistency across all workloads on how to authenticate. Items in the table above marked with a asterisk (*), are workloads for which the Microsoft Graph PowerShell SDK is used to authenticate against. The plan is to update the underlying logic of every component inside of Microsoft365DSC to leverage that SDK as new APIs become available on Microsoft Graph.

It is possible for a configuration to use a mix of Credentials and Service Principals to authenticate against the various workloads. For example, if you decide to keep a master configuration for all the configuration of your tenant, you could have Azure AD components use the Service Principal of an app you have created to authenticate, and further down in the configuration have your Security and Compliance components use credentials. That approach is perfectly fine, but we would recommend to try and split different workloads across different (composite) configuration files. That way the configuration becomes less complex and easier to manage.

It is also important to note that we have added logic inside of the commands that allow you to take a snapshot of your current tenant configuration to warn you when the components you are trying to capture can’t be accessed based on the authentication model you have selected.

For example: If you are trying to take a snapshot of both Azure AD and Security and Compliance components, but are authenticating using a Service Principal, the tool will warn you that the Security and Compliance components can’t be captured and that they will be ignored. In this case, the resulting capture would only contain the Azure AD components because those are the only ones the tool can get access to using Service Principal.

Export only exports resources that support the used authentication method

Export only exports resources that support the used authentication method

Power Apps Permissions

In order to authenticate to Power Apps using a Service Principal (Certificate Thumbprint or ApplicationSecret), you will first need to define your app as a Power App Management app. For details on how to proceed, please refer to the folloring link: https://learn.microsoft.com/en-us/power-platform/admin/powershell-create-service-principal#registering-an-admin-management-application

Additionally, to be able to authenticate using a Certificate Thumbprint, the underlying Power Apps PowerShell module used by Microsoft365DSC requires the certificate's private key (.pfx) to be registered under the current user's certificate store at Cert:\CurrentUser\My\. Omitting to register the private key will result in Microsoft365DSC throwing the following error when trying to authenticate to the Power Platform:

Get-Item: Cannot find path 'Cert:\CurrentUser\My\****************************************' because it does not exist.

Microsoft Graph Permissions

Most components of the Microsoft365DSC solution are using the Microsoft Graph PowerShell SDK under the cover to authenticate and interact with Microsoft 365. The Graph API has two different authentication implementations:

  1. Delegated permissions: Here a username/password is used to authenticate.

    This option is using an AzureAD app in the background to call the Graph API (named "Microsoft Graph PowerShell"). However the effective permissions will be the intersection of the delegated permissions and the user privileges. By default, the Graph app has no permissions meaning it can't access anything and therefore won't work. You have to grant these permissions to the app before using them. Consent for these permissions can be given by the user himself or by an admin for all users in the tenant.

    For example: If your account only has permissions on three SharePoint sites, only these sites can be retrieved. Even when the AzureAD app has Sites.FullControll.All permissions granted.

    Using the Graph API with Delegated Permissions and the default App Registration
    Using the Graph API with Delegated Permissions and the default App Registration

    To update the delegated permissions on the Graph app, you can use the Update-M365DSCAllowedGraphScopes cmdlet and specify the resources you are using. This will read the required permissions for those resources and update those on the Graph app.

    NOTE: It is possible to specify your own App registration when using Delegated permissions, but if you don't, the generic Graph app is created and used.

  2. Application permissions: Here authentication is done using app credentials (either using a secret or certificate).

    This option requires your own app to be registered in Azure AD. You can specify what permissions you want your app to have or even create an app for each workloads if necessary. Effective permissions will always be the granted permissions (an user context does not exist). Only admins can grant these permissions.

    NOTE: This is the easiest option to use.

    Using the Graph API with a custom application
    Using the Graph API with a custom application

IMPORTANT: Applications with high privileges should be monitored closely. In practice there are advantages to use conditional access policies for these applications to limit access to specific sources or user accounts.

Check out the links in the "More information" section below to learn more about creating your own Azure Active Directory application registration and granting permissions.

Determine Required Permissions

In order to be able to interact with these components, you need to grant your application or the Microsoft Graph PowerShell one the proper permissions against the Microsoft Graph scope. To determine what permissions are required by a given component that uses Microsoft Graph, you can use the Get-M365DSCCompiledPermissionList cmdlet and pass in the list of parameters for which you wish to grant permissions for.

Example of how to check for the required permissions

Example of how to check for the required permissions

Doing so will return an object with two properties. The ReadPermissions property contains a list of the minimal permissions that need to be granted for the app to be able to read information about the selected components. These are the permissions you want to grant if you are taking a snapshot of the configuration of an existing tenant. The second property, UpdatePermissions, contains the minimal permissions required to interact with and configure the selected components. You will need to grant your application these permissions if you are trying to apply a configuration onto a tenant.

By default, this cmdlet outputs the permissions required for Delegated permissions. To output the Application permissions, use the PermissionsType parameter

Get-M365DSCCompiledPermissionList -ResourceNameList @('AADUser', 'AADApplication') -Source 'Graph' -PermissionsType 'Application'

If you are trying to interact with all available components in Microsoft365DSC, you can get a complete picture of all permissions required across all resources by running the following line of PowerShell.

Get-M365DSCCompiledPermissionList -ResourceNameList (Get-M365DSCAllResources)

How to retrieve the Graph permissions for all resources

How to retrieve the Graph permissions for all resources

The Get-M365DSCAllResources cmdlet will return a list of all components available inside of the Microsoft365DSC solution which will then by passed in the Get-M365DSCCompiledPermissionList cmdlet which will compile the resulting permissions needed for the list of components it receives, in occurrence all of them. These permissions need to be granted to your application instance, either using the Azure portal or automating the process via PowerShell.

We provide an easy way of consenting permissions to the Delegated Permissions application "Microsoft Graph PowerShell" in your tenant with the Update-M365DSCAllowedGraphScopes cmdlet. This cmdlet accepts either a list of components to grant the permissions for or can grant it for all resources if the -All switch is used. You also need to specify what type of permissions, Read or Update, you wish to grant it using the -Type parameter.

Consenting to requested Graph permissions

Consenting to requested Graph permissions

Executing the cmdlet will prompt you to authenticate using an administrator account that has access to consent permissions to Azure AD applications in your environment.

NOTE: If you get the error "Device code terminal timed-out after 120 seconds", check out the Troubleshooting section

Creating a custom service principal

As mentioned earlier in this article, there is also the possibility to use Application permissions or custom service principal to authenticate against Microsoft 365. This custom service principal can be created and configured manually, but Microsoft365DSC also offers the Update-M365DSCAzureAdApplication cmdlet. With this cmdlet, you can create the custom service application, grant the correct permissions, provide admin consent and create credentials (secret or certificate).

Update-M365DSCAzureAdApplication -ApplicationName 'Microsoft365DSC' -Permissions @(@{Api='SharePoint';PermissionName='Sites.FullControl.All'}) -AdminConsent -Type Secret

or

Update-M365DSCAzureAdApplication -ApplicationName 'Microsoft365DSC' -Permissions @(@{Api='SharePoint';PermissionName='Sites.FullControl.All'}) -AdminConsent -Type Certificate -CreateSelfSignedCertificate -CertificatePath c:\Temp\M365DSC.cer

SharePoint PnP PowerShell Permissions

All SharePoint Online resources are using the SharePoint PnP PowerShell module. Just like the Graph module, you can use the default PnP PowerShell app registration or create your own app registration.

Note: For more information about authentication in PnP PowerShell, check out this article.

Default PnP PowerShell app registration

Use the "Register-PnPManagementShellAccess" cmdlet to register this application in Azure Active Directory and grant the correct permissions.

Using your own Azure AD app

Create a new app registration in Azure AD yourself and grant the correct permissions to this app. The documentation on this website for each of the SharePoint Online resources list the permissions needed for the resource.

As an alternative, you can use the "Register-PnPAzureADApp" cmdlet to have PnP PowerShell create the app registration for you and grant the correct permissions.

Using Application Secret

SharePoint Online uses the legacy ACS model to authenticate using an Application Secret. In order to get started with it, you will need to register your Azure AD App against your tenant.

  1. Navigate to https://-admin.sharepoint.com/_layouts/15/appinv.aspx.
  2. In the App Id box, type in the application id of your Azure AD App you wish to authenticate with and click on the Lookup button.
  3. In the App domain box, type in www..com.
  4. Leave the Redirect URL box empty.
  5. In the Permission request XML box, put in the following XML: 
      <AppPermissionRequests AllowAppOnlyPolicy="true">
    <AppPermissionRequest Scope="http://sharepoint/content/tenant" Right="FullControl" />
  </AppPermissionRequests>
  6. Click on the Create button. Register a new app for SharePoint Online.
  7. On the next screen, click on the Trust It button to complete the registration process. Register a new app for SharePoint Online.

You should now be able to connect to SharePoint Online using an Application Secret.

Exchange Permissions

For the Exchange Online resources, the service account needs certain permissions in order to be able to connect and manage the settings in Exchange Online. You can request the required permissions/roles and the corresponding rolegroups using the Get-M365DSCCompiledPermissionList cmdlet.

To request the permissions,

Get-M365DSCCompiledPermissionList -ResourceNameList @('EXOAcceptedDomain') -Source 'Exchange'

How to retrieve the permissions for Exchange resources

How to retrieve the permissions for Exchange resources

Then make sure your service account is a member of the specified Role Group or has been granted the required roles.

NOTE: There are resources, like the EXOAddressList which roles by default are not granted to any of the default role groups. Make sure you grant these permissions correctly before using them.

Using Authentication in DSC configurations

See the next chapter to see how to use the Authentication options in DSC configurations

More information