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
Office365 Global Admin credentials
Inputing Office 365 Global Admin credentials
Installing Office365DSC with PowerShell
Installing Office365DSC with PowerShell
The Install-Module cmdlet automatically downloads and installs the dependencies
The Install-Module cmdlet automatically downloads and installs the dependencies
Importing the Office365DSC module displays warning about the SharePoint Online dependencies
Importing the Office365DSC module displays warning about the SharePoint Online dependencies
Initiated the Office365DSC Extraction Process
Initiated the Office365DSC Extraction Process
User will be prompted to select a destination to save the files
User will be prompted to select a destination to save the files
Office 365 Configuration was successfully extracted
Office 365 Configuration was successfully extracted

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.

2 thoughts on “Extract Office 365 Configuration from Existing Tenant

  1. Great post and I like the idea of the Office365DSC and I will play with the stuff 🙂

    But you have a little mistake (spelling mistake) in the post. In the source code, you write
    Export-O365Configuration -Credential $GlobalAdmin
    But if we look in the screenshot we need the parameter -GlobalAdminAccount

    And with get-help Export-O365Configuration we get:
    SYNTAX
    Export-O365Configuration [-GlobalAdminAccount] []

    not matter, I like your stuff!

Leave a Reply to AlterMartin Cancel reply

Your email address will not be published. Required fields are marked *