Authentication and Permissions
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:
- A set of credentials for a user
- 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. For example: The Security and Compliance and Microsoft Teams modules do not support authenticating using a Service Principal. 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.
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|
|Certificate Thumbprint||Certificate Path||Application Secret|
|Security & Compliance Center||ExchangeOnlineManagement
= Supported / = Not supported
Note: As you can see, while using Credentials is the least preferred option for security reasons, it is the only option that works across all supported workloads.
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 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 allows 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.
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:
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.
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.
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.
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 permission 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.
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.
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)
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.
Providing Consent For Graph Permissions¶
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.
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
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 Authentication in DSC configurations¶
See the next chapter to see how to use the Authentication options in DSC configurations
- Authentication and authorization basics for Microsoft Graph
- Microsoft Graph permissions reference
- Quickstart: Register an application with the Microsoft identity platform
- Register an application with Azure AD and create a service principal
- Grant tenant-wide admin consent to an application
- API permissions