Since the summer of 2020, the AzureAD PowerShell module provides cmdlets that can help you manage Conditional access policies. This can give you some nice options to backup, document and restore Conditional access policies. In my opinion, the PowerShell cmdlets aren’t all that intuitive, which is the reason I want to show in this post how to backup and restore Conditional Access Policies with PowerShell.
AzureAD module or the Graph API?
The cmdlets we are going to use today are part of the AzureAD module. I assume they are a wrapper around the Graph API, which also makes it possible to manage Conditional Access Policies. You do have the option to call the API directly from PowerShell. (To learn more about how, see my previous post.)
So which should you choose? Practically, there are some advantages on using the Graph API. The biggest one being that it works natively in PowerShell 7+, where the AzureAD module doesn’t. And automation running in for example Azure Functions is more clean thanks to working with a service principal.
If you would like to use PowerShell 7 and a Service Principal without learning the API, you could consider the DCToolbox module.
In my opinion, using the AzureAD module is the best way to go if you want to call these scripts interactively. Authentication through Connect-AzureAD is a breeze compared to the service principal approach you need for the Graph API. So if that is your use case, the AzureAD module is the way to go.
Prerequisites and limitations
The cmdlets we are going to use are part of the AzureAD PowerShell module. You can install the module from the PowerShell gallery by using
Install-Module AzureAD
After you have installed the module, you can import it and connect to your tenant
Import-Module AzureAD
Connect-AzureAD
An Authentication windows will pop up and you can authenticate as usual.
There are some limitations to keep in mind though:
PowerShell 5.1
AzureAD is officially not supported in PowerShell 7+. You are able to install the module, but you are not able to authenticate. So you have to use Windows PowerShell. There is more information on that here.
You should be able to use the module in PowerShell 7+ by using Windows PowerShell compatibility, but you do need Windows PowerShell on the device.
Import-Module AzureAD -UseWindowsPowerShell
The AzureAD module works natively in Cloud Shell, but the current version does not have the Conditional Access cmdlets available at the time of writing.
Preview policies
When you run the scripts to backup and restore Conditional Access Policies, all policies that are in Preview will not be touched. You do not get warned on this, you will just get an incomplete list.
To work around this, you can use the AzureADPreview module, as this module does collect the policies that are in preview. Read more about it here.
Backup up Conditional Access policies
Enough talking, let’s start working with the policies.
Our first goal is to create a backup for all the policies.
I did some experimenting with this and found the cleanest way to store the policies is by using JSON files. I did try to get a clean overview in a CSV, as that might be helpful as documentation. But there is too much layering in the objects to get a nice view. The JSONs are pretty readable with the right editor (like Visual Studio Code).
With the following code, you can create the backup files. All files will be saved as the Conditional Access ID.
Restore Conditional Access policies
While creating the backup was pretty straightforward, it is a bit more work to use those files to create new Conditional Access policies. The reason is that the policy object in PowerShell is divided into pretty specific types. If you use the following code, it will create new policies based on all the policies you just stored in JSON. By using the Prefix parameter, you can rename the policies, for example by adding restore in front of the name.
Remove existing policies
If you run above script, it will create all policies again, even if they already exist. So If you want to overwrite the existing policies, it might be a good idea to first remove the policies that you had backed up. You can do that by using the following code:
Note: There is no check on the Remove-AzureADMSConditionalAccessPolicy cmdlet. Be careful that you do not remove items you wanted to keep
Conclusion
So this is how you can Backup and restore Conditional access policies with PowerShell. I think it is great there is finally automation around the policies available, so you are able to make this part of your infra as code, to ease migrations or to set up a business standard.
