# Conditional Access PowerToys (CA-PowerToys)
[](https://pypi.org/project/ca-pwt)
[](https://pypi.org/project/ca-pwt)
[](https://github.com/0x6f677548/zerotrust-ca-powertoys/actions/workflows/lint.yml)
[](https://github.com/0x6f677548/zerotrust-ca-powertoys/actions/workflows/test.yml)
CA-PowerToys is a set of tools to help you manage Conditional Access policies in your tenant. It is a command line tool that can be used to export and import Conditional Access policies and associated groups, facilitating the editing of the policies in a human readable format. This is particular useful if you are implementing a Policy-as-Code approach, eventually using a Git repository to store your policies and a CI/CD pipeline (like Azure DevOps) to import them into your tenant.
## Why ?
There are several tools to manage Conditional Access policies, such as Graph PowerShell, Microsoft Graph API, Azure AD PowerShell and even M365DSC. Unfortunately, none of these tools can be used to export Conditional Access policies in a **format that can be human readable and editable**, and then **import them back to another tenant**. This is where CA-PowerToys can help you, with several commands that can be chained to export, clean up, replace guids with attributes, and import Conditional Access policies and groups.
## Capabilities
CA-PowerToys can be used to:
- **Get an access token** to be used in subsequent commands or to be used in other tools, such as Graph PowerShell, using a desired client_id (useful if Graph PowerShell or other tools are blocked in the target tenant)
- **Export/Import Conditional Access policies** to/from a file
- **Export groups** that are used in Conditional Access policies to a file
- **Clean up Conditional Access policies and Groups files**, removing attributes that are read-only or not allowed in the import process
- **Replace guids with attributes in Conditional Access policies (and vice-versa)**, making it "human readable" and editable. For example, replace the `id` attribute with the `displayName` attribute in a list of excluded groups in a Conditional Access policy
- **Throttle the number of requests** to the Graph API, to avoid hitting the rate limits
## Zero Trust Sample Policies
A set of sample policies can be found in the [Zero Trust Conditional Access Policies](https://github.com/0x6f677548/zerotrust-ca-policies) repository. These policies are based on the samples available at https://github.com/microsoft/ConditionalAccessforZeroTrustResources and the [recommended guidelines](https://docs.microsoft.com/en-us/azure/architecture/guide/security/conditional-access-zero-trust?msclkid=d1768a34ceda11ec9b6c8f244f8d05bd) and can be used as a starting point to implement a Zero Trust strategy in your organization.
## Installation
CA-PowerToys is a command line tool that can be used in Windows, Linux, and MacOS. It is written in Python and can be used as a module or as a standalone tool, as long as you have Python >3.7 installed (or Docker).
### pip
To install it, you can use pip:
```console
> pip install ca-pwt
> ca-pwt --help
```
### From source code
You can also install it from the source code:
```console
> git clone https://github.com/0x6f677548/zerotrust-ca-powertoys.git
> cd ca-powertoys
> pip install .
> ca-pwt --help
```
### Docker
Alternatively, you can use the Docker image:
```console
> docker pull ghcr.io/0x6f677548/zerotrust-ca-powertoys:latest
> docker run -it --rm ghcr.io/0x6f677548/zerotrust-ca-powertoys --help
```
## Usage
All available commands and options can be seen by using the `--help` option.
```console
> ca-pwt --help
```
To get help on a specific command, use the `--help` option with the command name. For example, to get help on the `export-policies` command, use the following command:
```console
> ca-pwt export-policies --help
```
### Usage Examples
#### Obtaining an access token
There are several ways to obtain an access token. The easiest is to use `acquire-token` in chain with other commands and login interactively. In the example below, the token obtained will be injected in the subsequent command to export the policies.
```console
> ca-pwt acquire-token export-policies --output_file policies.json
```
```
Exporting conditional access policies...
Obtaining policies from tenant...
Writing policies to file policies.json...
```
##### Store it in a variable to be used in subsequent commands
You can also obtain an access token and store it in a variable to be used in subsequent commands. In this case, you need to instruct the command to output the token using the `--output_token` option.
(pwsh)
```console
> $token = (ca-pwt acquire-token --output_token)
> ca-pwt --access_token $token export-policies --output_file policies.json
```
(bash)
```console
> token = $(ca-pwt acquire-token --output_token)
> ca-pwt --access_token $token export-policies --output_file policies.json
```
```
Exporting conditional access policies...
Obtaining policies from tenant...
Writing policies to file policies.json...
```
If you are in an endpoint where you can't use the interactive login, you can use `acquire-token` command with `--client_id` and `--client_secret` options, or, alternatively, using device flow, through the `--device_code` option.
```console
> $token = (ca-pwt acquire-token --device_code --output_token)
To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code 123456789 to authenticate.
```
##### Using the tool in a CI/CD pipeline
If you are using the tool in a CI/CD pipeline, CA-PowerToys supports authentication through a service principal, using the `--client_id` and `--client_secret` options. In this case, you need to instruct the command to output the token using the `--output_token` option. You should also use the `--tenant_id` option to specify the tenant where the service principal was created.
```console
> $token = (ca-pwt acquire-token --client_id $client_id --client_secret $client_secret --tenant_id $tenant_id --output_token)
> ca-pwt --access_token $token import-policies --input_file policies.json --duplicate_action overwrite
```
#### Exporting policies
```console
> ca-pwt --access_token $token export-policies --output_file policies.json
```
```
Exporting conditional access policies...
Obtaining policies from tenant...
Writing policies to file policies.json...
```
You can also define oData filters to export only a subset of the policies. In the example below, we export only the policies that have the word "Global" in the DisplayName.
```console
> ca-pwt --access_token $token export-policies --output_file policies.json --filter "startswith(displayName,'Global')"
```
```
Exporting conditional access policies...
Obtaining policies from tenant...
Writing policies to file policies.json...
```
#### Exporting all Policies and associated Groups
```console
> ca-pwt --access_token $token export-policies --output_file policies.json export-policy-groups --output_file groups.json
```
```
Exporting ca policies...
Output file: policies.json
Exporting groups found in CA policies...
Input file: policies.json; Output file: groups.json; Lookup cache file: None
```
#### Exporting all Policies and associated Groups, replace guids with human-readable attributes in the policies file and make the file ready for import
```console
> ca-pwt --access_token $token export-policies --output_file policies.json cleanup-policies replace-guids-with-attrs export-policy-groups --output_file groups.json cleanup-groups
```
```
Exporting ca policies...
Output file: policies.json
Cleaning up CA policies for import...
Input file: policies.json; Output file: policies.json
Replacing guids with attributes in CA policies...
Input file: policies.json; Output file: policies.json
Exporting groups found in CA policies...
Input file: policies.json; Output file: groups.json
Cleaning up groups for import...
Input file: groups.json; Output file: groups.json
```
#### Importing groups and policies
```console
> ca-pwt --access_token $token import-groups --input_file groups.json import-policies --input_file .\policies-humanreadable.json
```
```
Importing groups...
Input file: groups.json
Successfully created groups:
97d90185-6aef-4b84-9051-ed92c3b023a1: CA-Test-Group
Importing CA policies...
Input file: policies-humanreadable.json; Lookup cache file:
Successfully created policies:
896d7a7f-8300-4537-8d39-287b25f7259c: CA-Test-Policy
```
#### Using CA-PowerToys to export policies and import them using Graph PowerShell
You can use CA-PowerToys to export policies in a compatible format with Graph PowerShell. This is useful if you want to export policies from one tenant and import them into another tenant and use Graph PowerShell to import them (you can also use CA-PowerToys to import them, using the `import-policies` command).
This example chains the `export-policies` and `cleanup-policies` commands to export the policies and clean them up for import. The output is stored in the policies.json file. Then we read the policies from the file and import them using the New-MgIdentityConditionalAccessPolicy command.
```console
> ca-pwt --access_token $token export-policies --output_file policies.json cleanup-policies
```
```
Exporting conditional access policies...
Obtaining policies from tenant...
Writing policies to file policies.json...
Cleaning up conditional access policies for import...
Reading policies from file policies.json...
Cleaning up policies...
Writing policies to file policies.json...
```
```powershell
> $policy = Get-Content -Path .\policies.json | ConvertFrom-Json -AsHashtable
> $policy.count
2
> New-MgIdentityConditionalAccessPolicy -BodyParameter $policy[0]
```
```
Id CreatedDateTime Description DisplayName
-- --------------- ----------- -----------
7b385aec-569a-470a-980b-8624bfa6332c 14/10/2023 07:52:54 CA001-Global-BaseProtection-All…
```
Note: In the above example, a token was previously obtained using the `acquire-token` and stored in the `$token` variable.
Raw data
{
"_id": null,
"home_page": "",
"name": "ca-pwt",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "azure,azure-ad,conditional-access,entraid,microsoft,policies,policy-as-code",
"author": "0x6f677546 (Hugo Batista)",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/91/01/6510fbbfa2982c7bdd73efa9b1096581f84e6df2e24cc78c32d76a14c736/ca_pwt-0.1.0.tar.gz",
"platform": null,
"description": "# Conditional Access PowerToys (CA-PowerToys)\n\n[](https://pypi.org/project/ca-pwt)\n[](https://pypi.org/project/ca-pwt)\n[](https://github.com/0x6f677548/zerotrust-ca-powertoys/actions/workflows/lint.yml)\n[](https://github.com/0x6f677548/zerotrust-ca-powertoys/actions/workflows/test.yml)\n\nCA-PowerToys is a set of tools to help you manage Conditional Access policies in your tenant. It is a command line tool that can be used to export and import Conditional Access policies and associated groups, facilitating the editing of the policies in a human readable format. This is particular useful if you are implementing a Policy-as-Code approach, eventually using a Git repository to store your policies and a CI/CD pipeline (like Azure DevOps) to import them into your tenant.\n\n## Why ?\nThere are several tools to manage Conditional Access policies, such as Graph PowerShell, Microsoft Graph API, Azure AD PowerShell and even M365DSC. Unfortunately, none of these tools can be used to export Conditional Access policies in a **format that can be human readable and editable**, and then **import them back to another tenant**. This is where CA-PowerToys can help you, with several commands that can be chained to export, clean up, replace guids with attributes, and import Conditional Access policies and groups. \n\n## Capabilities\n\nCA-PowerToys can be used to:\n- **Get an access token** to be used in subsequent commands or to be used in other tools, such as Graph PowerShell, using a desired client_id (useful if Graph PowerShell or other tools are blocked in the target tenant)\n- **Export/Import Conditional Access policies** to/from a file\n- **Export groups** that are used in Conditional Access policies to a file\n- **Clean up Conditional Access policies and Groups files**, removing attributes that are read-only or not allowed in the import process\n- **Replace guids with attributes in Conditional Access policies (and vice-versa)**, making it \"human readable\" and editable. For example, replace the `id` attribute with the `displayName` attribute in a list of excluded groups in a Conditional Access policy\n- **Throttle the number of requests** to the Graph API, to avoid hitting the rate limits\n\n## Zero Trust Sample Policies\nA set of sample policies can be found in the [Zero Trust Conditional Access Policies](https://github.com/0x6f677548/zerotrust-ca-policies) repository. These policies are based on the samples available at https://github.com/microsoft/ConditionalAccessforZeroTrustResources and the [recommended guidelines](https://docs.microsoft.com/en-us/azure/architecture/guide/security/conditional-access-zero-trust?msclkid=d1768a34ceda11ec9b6c8f244f8d05bd) and can be used as a starting point to implement a Zero Trust strategy in your organization.\n\n## Installation\nCA-PowerToys is a command line tool that can be used in Windows, Linux, and MacOS. It is written in Python and can be used as a module or as a standalone tool, as long as you have Python >3.7 installed (or Docker).\n\n### pip\nTo install it, you can use pip:\n```console\n> pip install ca-pwt\n> ca-pwt --help\n```\n\n### From source code\nYou can also install it from the source code:\n```console\n> git clone https://github.com/0x6f677548/zerotrust-ca-powertoys.git\n> cd ca-powertoys\n> pip install .\n> ca-pwt --help\n```\n### Docker\nAlternatively, you can use the Docker image:\n```console\n> docker pull ghcr.io/0x6f677548/zerotrust-ca-powertoys:latest\n> docker run -it --rm ghcr.io/0x6f677548/zerotrust-ca-powertoys --help\n```\n\n## Usage\nAll available commands and options can be seen by using the `--help` option.\n```console\n> ca-pwt --help\n```\n\nTo get help on a specific command, use the `--help` option with the command name. For example, to get help on the `export-policies` command, use the following command:\n```console\n> ca-pwt export-policies --help\n```\n\n### Usage Examples\n\n#### Obtaining an access token \n\nThere are several ways to obtain an access token. The easiest is to use `acquire-token` in chain with other commands and login interactively. In the example below, the token obtained will be injected in the subsequent command to export the policies. \n\n```console\n> ca-pwt acquire-token export-policies --output_file policies.json\n```\n```\nExporting conditional access policies...\nObtaining policies from tenant...\nWriting policies to file policies.json...\n```\n##### Store it in a variable to be used in subsequent commands\nYou can also obtain an access token and store it in a variable to be used in subsequent commands. In this case, you need to instruct the command to output the token using the `--output_token` option. \n\n(pwsh)\n```console\n> $token = (ca-pwt acquire-token --output_token)\n> ca-pwt --access_token $token export-policies --output_file policies.json\n```\n(bash)\n```console\n> token = $(ca-pwt acquire-token --output_token)\n> ca-pwt --access_token $token export-policies --output_file policies.json\n```\n```\nExporting conditional access policies...\nObtaining policies from tenant...\nWriting policies to file policies.json...\n```\nIf you are in an endpoint where you can't use the interactive login, you can use `acquire-token` command with `--client_id` and `--client_secret` options, or, alternatively, using device flow, through the `--device_code` option. \n```console\n> $token = (ca-pwt acquire-token --device_code --output_token)\nTo sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code 123456789 to authenticate.\n```\n\n##### Using the tool in a CI/CD pipeline\nIf you are using the tool in a CI/CD pipeline, CA-PowerToys supports authentication through a service principal, using the `--client_id` and `--client_secret` options. In this case, you need to instruct the command to output the token using the `--output_token` option. You should also use the `--tenant_id` option to specify the tenant where the service principal was created.\n```console\n> $token = (ca-pwt acquire-token --client_id $client_id --client_secret $client_secret --tenant_id $tenant_id --output_token)\n> ca-pwt --access_token $token import-policies --input_file policies.json --duplicate_action overwrite\n```\n\n\n#### Exporting policies\n \n```console\n> ca-pwt --access_token $token export-policies --output_file policies.json\n```\n```\nExporting conditional access policies...\nObtaining policies from tenant...\nWriting policies to file policies.json...\n```\n\nYou can also define oData filters to export only a subset of the policies. In the example below, we export only the policies that have the word \"Global\" in the DisplayName. \n\n```console\n> ca-pwt --access_token $token export-policies --output_file policies.json --filter \"startswith(displayName,'Global')\"\n```\n```\nExporting conditional access policies...\nObtaining policies from tenant...\nWriting policies to file policies.json...\n```\n\n#### Exporting all Policies and associated Groups\n\n```console\n> ca-pwt --access_token $token export-policies --output_file policies.json export-policy-groups --output_file groups.json\n```\n```\nExporting ca policies...\nOutput file: policies.json\nExporting groups found in CA policies...\nInput file: policies.json; Output file: groups.json; Lookup cache file: None\n```\n\n#### Exporting all Policies and associated Groups, replace guids with human-readable attributes in the policies file and make the file ready for import\n\n```console\n> ca-pwt --access_token $token export-policies --output_file policies.json cleanup-policies replace-guids-with-attrs export-policy-groups --output_file groups.json cleanup-groups\n```\n```\nExporting ca policies...\nOutput file: policies.json\nCleaning up CA policies for import...\nInput file: policies.json; Output file: policies.json\nReplacing guids with attributes in CA policies...\nInput file: policies.json; Output file: policies.json\nExporting groups found in CA policies...\nInput file: policies.json; Output file: groups.json\nCleaning up groups for import...\nInput file: groups.json; Output file: groups.json\n```\n#### Importing groups and policies\n\n```console\n> ca-pwt --access_token $token import-groups --input_file groups.json import-policies --input_file .\\policies-humanreadable.json\n```\n```\nImporting groups...\nInput file: groups.json\nSuccessfully created groups:\n97d90185-6aef-4b84-9051-ed92c3b023a1: CA-Test-Group\nImporting CA policies...\nInput file: policies-humanreadable.json; Lookup cache file:\nSuccessfully created policies:\n896d7a7f-8300-4537-8d39-287b25f7259c: CA-Test-Policy\n```\n\n#### Using CA-PowerToys to export policies and import them using Graph PowerShell\n\nYou can use CA-PowerToys to export policies in a compatible format with Graph PowerShell. This is useful if you want to export policies from one tenant and import them into another tenant and use Graph PowerShell to import them (you can also use CA-PowerToys to import them, using the `import-policies` command).\n\nThis example chains the `export-policies` and `cleanup-policies` commands to export the policies and clean them up for import. The output is stored in the policies.json file. Then we read the policies from the file and import them using the New-MgIdentityConditionalAccessPolicy command. \n\n```console\n> ca-pwt --access_token $token export-policies --output_file policies.json cleanup-policies\n```\n```\nExporting conditional access policies...\nObtaining policies from tenant...\nWriting policies to file policies.json...\nCleaning up conditional access policies for import...\nReading policies from file policies.json...\nCleaning up policies...\nWriting policies to file policies.json...\n```\n```powershell\n> $policy = Get-Content -Path .\\policies.json | ConvertFrom-Json -AsHashtable\n> $policy.count\n2\n> New-MgIdentityConditionalAccessPolicy -BodyParameter $policy[0]\n```\n```\n\nId CreatedDateTime Description DisplayName\n-- --------------- ----------- -----------\n7b385aec-569a-470a-980b-8624bfa6332c 14/10/2023 07:52:54 CA001-Global-BaseProtection-All\u2026\n```\nNote: In the above example, a token was previously obtained using the `acquire-token` and stored in the `$token` variable.\n",
"bugtrack_url": null,
"license": "",
"summary": "CA-PowerToys is a set of tools to help you manage Conditional Access policies. It is a command line tool that can be used to export, import, and clean up Conditional Access policies and associated Groups",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/0x6f677548/ca-pwt#readme",
"Issues": "https://github.com/0x6f677548/ca-pwt/issues",
"Source": "https://github.com/0x6f677548/ca-pwt"
},
"split_keywords": [
"azure",
"azure-ad",
"conditional-access",
"entraid",
"microsoft",
"policies",
"policy-as-code"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c531775f3ac89e24a0c6a7d5eece8f8adfb830b52cfdce417e2cf198dc850d06",
"md5": "2b998fd1d6a9493df4af532aecb24036",
"sha256": "2dae706ba3330caaaad1d117347838694c84013229d18d8436e54c26b34315d2"
},
"downloads": -1,
"filename": "ca_pwt-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2b998fd1d6a9493df4af532aecb24036",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 57127,
"upload_time": "2024-01-05T19:49:31",
"upload_time_iso_8601": "2024-01-05T19:49:31.303472Z",
"url": "https://files.pythonhosted.org/packages/c5/31/775f3ac89e24a0c6a7d5eece8f8adfb830b52cfdce417e2cf198dc850d06/ca_pwt-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "91016510fbbfa2982c7bdd73efa9b1096581f84e6df2e24cc78c32d76a14c736",
"md5": "a57896340a5ee0879e5266cecf5ef8e5",
"sha256": "ae4826ab745ca872a8cc3e889e9c17cac47782bacbf9853253158f342877dddb"
},
"downloads": -1,
"filename": "ca_pwt-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "a57896340a5ee0879e5266cecf5ef8e5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 55639,
"upload_time": "2024-01-05T19:49:32",
"upload_time_iso_8601": "2024-01-05T19:49:32.649503Z",
"url": "https://files.pythonhosted.org/packages/91/01/6510fbbfa2982c7bdd73efa9b1096581f84e6df2e24cc78c32d76a14c736/ca_pwt-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-05 19:49:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "0x6f677548",
"github_project": "ca-pwt#readme",
"github_not_found": true,
"lcname": "ca-pwt"
}
JSON
