Extract Office 365 Configuration from Existing Tenant

A few weeks ago, I posted what I consider to be a “Tease” Post regarding a new project I am involved with, Office365DSC. Today, I would like to share additional details regarding what our plans are for this module. Throughout the development process, the team and I will be completely transparent about what our progress, road-map and vision is. I will be using my personal blog to publish examples and keep the community informed about upcoming releases and changes.

The focus for today’s blog post will be on the ReverseDSC capabilities that are directly built into the module. For over two years now, the PowerShell team and I have been discussing possible approaches to have the ReverseDSC capabilities baked-in within each module, but could never figure out what the best approach to enforce this would be for existing modules. Since Office365DSC is a brand new resource, we decided to use it as our very first Proof-of-Concept, and have it included directly within it. There is currently an active Request for Change that proposes the introduction of a 4th function in each resource which would allow for the extraction of DSC configuration scripts for it.

The Office365DSC Approach

Our approach for Office365DSC was to introduce that 4th method, named Export-TargetResource, in each of our resources as a standard. This logic for this function is to be kept very simple: it calls into the Get-TargetResource function, and converts the returned hashtable into a consumable DSC block, represented as a string. This function only receives the Required parameters (primary and secondary keys). This function is a one-to-one mapping, meaning it receives the keys of a specific instance of the given resource, and return the string block representing that one instance.

In order to collect information about each instances of all resources supported by the module, we introduced a new public function, defined in the Office365DSCUtil.psm1 utility module, which is named Export-O365Configuration. This function is responsible for retrieving the keys of all instances of each resources, to call the specific Export-TargetResource function for it, and to collect and merge the retrieved DSC string blocks. To reduce the complexity of this function, we leverage the existing logic from the ReverseDSC module, and therefore Office365DSC is dependent on this module.

How to Use It?

The Office365DSC module is available on the PowerShell gallery. This release contains the mechanisms to automate the ReverseDSC extraction of existing Office365 tenants. In order to download it an initiate a ReverseDSC extract, you can run the following lines of PowerShell. Note: In order to initiate the extract, you will need to provide credentials from a user who is assigned the Global Admin role.

$GlobalAdmin = Get-Credential
Install-Module Office365DSC -Force
Import-Module Office365DSC -Force
Export-O365Configuration -GlobalAdminAccount $GlobalAdmin

Wrap-Up

We hope that this article properly articulated what our plans are with the Office365DSC. By making it as easy as possible for organizations to Reverse Engineer the configuration of their existing Office 365 tenant, we hope to to open the door to brand new adoption scenarios (a.k.a. easy replication across tenant, etc.) which weren’t possible up to now. As always, we encourage the community to submit feedback using the Issues tabs in the GitHub Repository for the project, and to contribute to the initiative by forking the repository and submitting Pull Requests.