Add resource settings for AADUser with docs

[FabienTschanz]

Pull Request (PR) description

This PR adds the new function Get-M365DSCResourceSettings to the M365DSCUtil module and includes documentation on how to skip the MemberOf processing for the AADUser resource.

In tenant cloning scenarios, especially when migrating users and / or groups, the members of the groups or the groups itself might not exist. This introduces issues, where errors might occur if a member is not found (because it doesn't exist) or assigning a user to a group fails (because it too doesn't exist). With using the resource setting AADUserApplyMemberOf with either true or false, it's possible to stop processing the MemberOf and only let the AADGroup manage the members. This solves the problem when creating users first and only after all of the users exist, then the groups are deployed. If this was not the case and a group wouldn't exist, errors would be thrown and the configuration would need to be applied multiple times until it succeeds.

This Pull Request (PR) fixes the following issues

None.

Task list

• Added an entry to the change log under the Unreleased section of the file CHANGELOG.md.
  Entry should say what was changed and how that affects users (if applicable), and
  reference the issue being resolved (if applicable).
• Resource parameter descriptions added/updated in the schema.mof.
• Resource documentation added/updated in README.md.
• Resource settings.json file contains all required permissions.
• Examples appropriately added/updated.
• Unit tests added/updated.
• New/changed code adheres to DSC Community Style Guidelines.

[NikCharlebois]

Can you provide additional details here? How will a customer specify within their configuration that they do not want the processing to happen?

[FabienTschanz]

@NikCharlebois The configuration can be applied using the environment variable M365DSC_RESOURCE_SETTINGS. It accepts a JSON string which contains settings for the M365DSC module to apply. In this case for AADUser, you can specify it like the following:

$resourceSettings = @(
    @{ AADUserApplyMemberOf = $false }
) | ConvertTo-Json -Compress

[System.Environment]::SetEnvironmentVariable('M365DSC_RESOURCE_SETTINGS', $resourceSettings, 'Machine')

Documentation for this feature is available in the docs/docs/user-guide/get-started/cloning-tenants.md file. It lists the available settings (currently only the one for AADUser), how it can be used and in which scenarios it makes sense to do so.

Edit: Because the AADUser resource does not accept a parameter / property with which we can configure that, and other resources might have such things as well in the future (I can already think of some), and the LCM runs in the SYSTEM context instead of the currently logged on user, the configuration for this feature needs to live somewhere else. Environment variables in the machine context are the place I thought of - If you have other ideas, I'm open to them.

[NikCharlebois]

Let me park this PR for a few more days to give me time to think this through and test it out. Thanks

[FabienTschanz]

Absolutely, take your time. It's something I stumbled upon with another user and we started some discussions on how to resolve that. This is what I came up with - Any ideas are welcome. Such a feature (and other "feature flags") should be possible for a user of Microsoft365DSC to configure. In what way is to be defined. I can easily rewrite the logic to adapt for another mechanism, but some functionality needs to be implemented.

[ricmestre]

I mentioned a few times in the past years implementing a resource dependency system either in settings.json files, or any other file, that way the resources could be either sorted in the blueprint since the LCM processes them from top to bottom in the order they appear in the blueprint, or even better like I explained in a couple of threads inject the DependsOn property dynamically on resources that depend on others.

FYI I have been using a mix of both in my solution, so my users don't need to mess with the order of the resources in the blueprint manually nor having to figure out the specific DependsOn strings themselves since they're injected dynamically and only if required.

I even have another 3rd way of doing this, sure enough is the worst of all these and not recommended which is to process only certain resources (the ones that can be dependencies for other resources) in a first deployment without specific properties, then do a second deployment with the those properties back in, in this specific case I think I process the AADGroup resources first without MemberOf and Members and Owners, then you get all groups created, then AADUser are processed later on without MemberOf, on the second deployment those properties can be added back in safely if everything went well on first deployment. Of course not for the faint of heart, the logs in the tenant will look a mess since the groups if they were populated before they will look like they've been emptied out and then put back in place a few minutes later.

[FabienTschanz]

I once mentioned implementing the DependsOn property to Nik, unfortunately I was turned down for it being the "box of Pandora" and not to be touched at the moment. Although I do like the idea, and with some thinking we could most likely implement this as well. Got a couple of ideas on how to do so. This here is a "quick fix" you could say to the matter and something that appears from time to time again.

[ricmestre]

Sure, this definitely scratches an itch and fixes this specific issue with minimal changes, any other dependency system implementation is beyond the scope of the PR and should involve more thought about it.