From 35e902905527148723612e437eb45800c5508598 Mon Sep 17 00:00:00 2001 From: merill Date: Sat, 19 Aug 2023 09:01:31 +1000 Subject: [PATCH] Updated readme --- README.md | 77 +++++++---------------------------- src/Connect-EntraExporter.ps1 | 5 +++ src/EntraExporter.psd1 | 4 +- src/Export-Entra.ps1 | 40 +++++++++++------- src/Get-EEDefaultSchema.ps1 | 4 +- 5 files changed, 49 insertions(+), 81 deletions(-) diff --git a/README.md b/README.md index 69dc675..3c40616 100644 --- a/README.md +++ b/README.md @@ -17,13 +17,20 @@ This will provide tenant administrators with a historical view of all the settin ## Using the module -### Connecting to your tenant +### Connecting and exporting your config ```powershell Connect-EntraExporter + Export-Entra -Path 'C:\EntraBackup\' +``` + +While Connect-EntraExporter is available for convenience you can alternatively use Connect-MgGraph with the following scopes to authenticate. + +```powershell +Connect-MgGraph -Scopes 'Directory.Read.All', 'Policy.Read.All', 'IdentityProvider.Read.All', 'Organization.Read.All', 'User.Read.All', 'EntitlementManagement.Read.All', 'UserAuthenticationMethod.Read.All', 'IdentityUserFlow.Read.All', 'APIConnectors.Read.All', 'AccessReview.Read.All', 'Agreement.Read.All', 'Policy.Read.PermissionGrant', 'PrivilegedAccess.Read.AzureResources', 'PrivilegedAccess.Read.AzureAD', 'Application.Read.All' ``` -### Exporting objects and settings +### Export options To export object and settings use the following command: @@ -31,20 +38,14 @@ To export object and settings use the following command: Export-Entra -Path 'C:\EntraBackup\' ``` -This will export the most common set of objects and settings. +This default method exports the most common set of objects and settings. > [!NOTE] > We recommend using PowerShell 7+ to create a consistent output. While PowerShell 5.1 can be used the output generated is not optimal. The following objects and settings are not exported by default: -* B2C -* B2B -* Static Groups and group memberships -* Applications -* ServicePrincipals -* Users -* Privileged Identity Management (built in roles, default roles settings, non permanent role assignements) +* B2C, B2B, Static Groups and group memberships, Applications, ServicePrincipals, Users, Privileged Identity Management (built in roles, default roles settings, non permanent role assignements) To export all the objects and settings supported (no filter applied): @@ -65,31 +66,7 @@ The ``-Type`` parameter can be used to select specific objects and settings to e Export-Entra -Path 'C:\EntraBackup\' -Type "B2B","Config" ``` -The currently valid types are: - -* All (all elements) -* Config (default configuration) -* AccessReviews -* ConditionalAccess -* Users -* Groups -* Applications -* ServicePrincipals -* B2C -* B2B -* PIM -* PIMAzure -* PIMAAD -* AppProxy -* Organization -* Domains -* EntitlementManagement -* Policies -* AdministrativeUnits -* SKUs -* Identity -* Roles -* Governance +The currently valid types are: All (all elements), Config (default configuration), AccessReviews, ConditionalAccess, Users, Groups, Applications, ServicePrincipals, B2C, B2B, PIM, PIMAzure, PIMAAD, AppProxy, Organization, Domains, EntitlementManagement, Policies, AdministrativeUnits, SKUs, Identity, Roles, Governance This list can also be retrieved via: @@ -99,22 +76,10 @@ This list can also be retrieved via: Additional filters can be applied: -* To only export user and groups that are not synced from on-premises +* To exclude on-prem synced users from the export ```powershell -Export-Entra -Path 'C:\EntraBackup\' -CloudUsersAndGroupsOnly -``` - -* All groups (by default only dynamic groups are exported) - -```powershell -Export-Entra -Path 'C:\EntraBackup\' -AllGroups -``` - -* All will export all types and remove filters from groups and PIM: - -```powershell -Export-Entra -Path 'C:\EntraBackup\' -All +Export-Entra -Path 'C:\EntraBackup\' -All -CloudUsersAndGroupsOnly ``` > [!NOTE] @@ -247,20 +212,6 @@ New-ItemProperty ` Credit: @shaunluttin via https://bigfont.ca/enable-long-paths-in-windows-with-powershell/ and https://docs.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=powershell. -## Contributing - -This project welcomes contributions and suggestions. Most contributions require you to agree to a -Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us -the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com. - -When you submit a pull request, a CLA bot will automatically determine whether you need to provide -a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions -provided by the bot. You will only need to do this once across all repos using our CLA. - -This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). -For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or -contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. - ## Trademarks This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft diff --git a/src/Connect-EntraExporter.ps1 b/src/Connect-EntraExporter.ps1 index a031ea9..8ccf638 100644 --- a/src/Connect-EntraExporter.ps1 +++ b/src/Connect-EntraExporter.ps1 @@ -5,6 +5,11 @@ $global:TenantID = $null .DESCRIPTION This command will connect Microsoft.Graph to your Entra tenant. You can also directly call Connect-MgGraph if you require other options to connect + + Use the following scopes when authenticating with Connect-MgGraph. + + Connect-MgGraph -Scopes 'Directory.Read.All', 'Policy.Read.All', 'IdentityProvider.Read.All', 'Organization.Read.All', 'User.Read.All', 'EntitlementManagement.Read.All', 'UserAuthenticationMethod.Read.All', 'IdentityUserFlow.Read.All', 'APIConnectors.Read.All', 'AccessReview.Read.All', 'Agreement.Read.All', 'Policy.Read.PermissionGrant', 'PrivilegedAccess.Read.AzureResources', 'PrivilegedAccess.Read.AzureAD', 'Application.Read.All' + .EXAMPLE PS C:\>Connect-EntraExporter Connect to home tenant of authenticated user. diff --git a/src/EntraExporter.psd1 b/src/EntraExporter.psd1 index 5582019..b5b3015 100644 --- a/src/EntraExporter.psd1 +++ b/src/EntraExporter.psd1 @@ -4,7 +4,7 @@ RootModule = 'EntraExporter.psm1' # Version number of this module. - ModuleVersion = '2.0.1' + ModuleVersion = '2.0.2' # Supported PSEditions CompatiblePSEditions = 'Core','Desktop' @@ -22,7 +22,7 @@ Copyright = 'Microsoft Corporation. All rights reserved.' # Description of the functionality provided by this module - Description = 'This module exports all the Entra objects and identity related settings in your tenant.' + Description = 'This module exports an Entra tenant''s identity related configuration settings and objects and writes them to json files.' # Minimum version of the Windows PowerShell engine required by this module PowerShellVersion = '5.1' diff --git a/src/Export-Entra.ps1 b/src/Export-Entra.ps1 index f368b9b..71ae715 100644 --- a/src/Export-Entra.ps1 +++ b/src/Export-Entra.ps1 @@ -2,8 +2,7 @@ .Synopsis Exports Entra's configuration and settings for a tenant .Description - This cmdlet reads the configuration information from the target Entra tenant and produces the output files - in a target directory + This cmdlet reads the configuration information from the target Entra tenant and produces the output files in a target directory .PARAMETER OutputDirectory Specifies the directory path where the output files will be generated. @@ -17,12 +16,18 @@ .EXAMPLE .\Export-Entra -Path 'c:\temp\contoso' - Runs a default export and includes the key tenant configuration settings. Does not include large data collections such as Users, Groups, Applications, Service Principals, etc. -.EXAMPLE + Runs a default export and includes the key tenant configuration settings. Does not include large data collections such as users, static groups, applications, service principals, etc. + + .EXAMPLE .\Export-Entra -Path 'c:\temp\contoso' -All Runs a full export of all objects and configuration settings. +.EXAMPLE + .\Export-Entra -Path 'c:\temp\contoso' -All -CloudUsersAndGroupsOnly + + Runs a full export but excludes on-prem synced users and groups. + .EXAMPLE .\Export-Entra -Path 'c:\temp\contoso' -Type ConditionalAccess, AppProxy @@ -40,23 +45,30 @@ Function Export-Entra { ( [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true)] [String]$Path, + [Parameter(Mandatory = $false)] [ValidateSet('All', 'Config', 'AccessReviews', 'ConditionalAccess', 'Users', 'Groups', 'Applications', 'ServicePrincipals','B2C','B2B','PIM','PIMAzure','PIMAAD', 'AppProxy', 'Organization', 'Domains', 'EntitlementManagement', 'Policies', 'AdministrativeUnits', 'SKUs', 'Identity', 'Roles','Governance')] [String[]]$Type = 'Config', + [Parameter(Mandatory = $false)] [object]$ExportSchema, + [Parameter(Mandatory = $false)] [string[]]$Parents, + + # Performs a full export if true + [Parameter(Mandatory = $false)] [switch] $All, + + # Excludes onPrem synced users and groups from export + [Parameter(Mandatory = $false)] [switch] - $CloudUsersAndGroupsOnly, - [switch] - $AllGroups + $CloudUsersAndGroupsOnly ) if ($null -eq (Get-MgContext)) { - Write-Error "No active connection. Run Connect-EntraExporter to sign in and then retry." + Write-Error "No active connection. Run Connect-EntraExporter or Connect-MgGraph to sign in and then retry." exit } if($All) {$Type = @('All')} @@ -66,18 +78,18 @@ Function Export-Entra { if (!$ExportSchema) { $ExportSchema = Get-EEDefaultSchema } - # aditional filters foreach ($entry in $ExportSchema) { $graphUri = Get-ObjectProperty $entry "GraphUri" # filter out synced users or groups if ($CloudUsersAndGroupsOnly -and ($graphUri -in "users","groups")) { - $entry.Filter = "onPremisesSyncEnabled ne true" - } - # get all groups - if (($All -or $AllGroups) -and ($graphUri -eq "groups")) { - $entry.Filter = $null + if([string]::IsNullOrEmpty($entry.Filter)){ + $entry.Filter = "onPremisesSyncEnabled ne true" + } + else { + $entry.Filter = $entry.Filter + " and (onPremisesSyncEnabled ne true)" + } } # get all PIM elements if ($All -and ($graphUri -in "privilegedAccess/aadroles/resources","privilegedAccess/azureResources/resources")) { diff --git a/src/Get-EEDefaultSchema.ps1 b/src/Get-EEDefaultSchema.ps1 index d4f4a5e..a1495fb 100644 --- a/src/Get-EEDefaultSchema.ps1 +++ b/src/Get-EEDefaultSchema.ps1 @@ -684,11 +684,11 @@ function Get-EEDefaultSchema { }, @{ GraphUri = 'groups' - Filter = "NOT(groupTypes/any(c:c eq 'DynamicMembership'))" + Filter = "not(groupTypes/any(c:c eq 'DynamicMembership'))" Path = 'Groups' QueryParameters = @{ '$count' = 'true'; expand = 'extensions' } ApiVersion = 'beta' - Tag = @('All', 'Config', 'Groups') + Tag = @('All', 'Groups') DelegatedPermission = 'Directory.Read.All' ApplicationPermission = 'Directory.Read.All' Children = @(