diff --git a/Get-O365AdminGroupsReport.ps1 b/Get-O365AdminGroupsReport.ps1 new file mode 100644 index 0000000..28cd9b0 --- /dev/null +++ b/Get-O365AdminGroupsReport.ps1 @@ -0,0 +1,161 @@ +<# +.SYNOPSIS +Get-O365AdminGroupsReport.ps1 - Reports on Office 365 Admin Role/Group Membership. + +.DESCRIPTION +This script produces a report of the membership of Office 365 admin role groups. + +.OUTPUTS +The report is output to CSV file. + +.PARAMETER ReportFile +You can provide a custom output file name. The file name you specify will be +modified with the current date, for example MyReportFileName.csv will become +MyReportFileName-ddMMyyyy.csv. If a file of the same name exists, a unique +character string will also be appended to the file name. + +.PARAMETER Overwrite +Overwrites an existing report file of the same name, instead of appending +a unique character string. + +.EXAMPLE +.\Get-O365AdminGroupsReport.ps1 + +.EXAMPLE +.\Get-O365AdminGroupsReport.ps1 -ReportFile MyReportFileName.csv -Overwrite + +.EXAMPLE +.\Get-O365AdminGroupsReport.ps1 -Verbose + +.LINK +https://practical365.com/security/reporting-office-365-admin-role-group-members + +.NOTES +Written by Paul Cunningham +For more Office 365 tips, tutorials and news check out Practical365.com. + +Version history: +V1.00, 17/04/2017 - Initial version + +License: + +The MIT License (MIT) + +Copyright (c) 2017 Paul Cunningham + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. + +#> + +[CmdletBinding()] +param ( + [Parameter( Mandatory = $false )] + [ValidatePattern('.csv$')] + [string]$ReportFile="Office365AdminGroupMembers.csv", + + [Parameter( Mandatory = $false )] + [switch]$Overwrite +) + +#................................... +# Variables +#................................... + +$O365AdminGroupReport = New-Object System.Collections.ArrayList +$now = Get-Date +$ShortDate = $now.ToShortDateString() -replace "/","" + +$ReportFileSplit = $ReportFile.Split(".") +$OutputFileNamePrefix = $ReportFileSplit[0..($ReportFileSplit.length -2)] +$OutputFileName = "$($OutputFileNamePrefix)-$($ShortDate).$($ReportFileSplit[-1])" + +#................................... +# Script +#................................... + +#Check if AzureAD PowerShell or AzureADPreview module is available +if (-not(Get-Module -Name AzureAD) -and -not (Get-Module AzureADPreview)) { + throw "The AzureAD PowerShell module is not installed on this computer." +} + +#Get the Azure AD roles for the tenant +Write-Verbose "Retrieving Azure AD admin roles" +try { + $AzureADRoles = @(Get-AzureADDirectoryRole -ErrorAction Stop) +} catch { + if ($_.Exception.Message -ieq "You must call the Connect-AzureAD cmdlet before calling any other cmdlets.") { + #Connect to Azure AD + try { + $AzureADConnection = Connect-AzureAD -ErrorAction Stop + $AzureADRoles = @(Get-AzureADDirectoryRole -ErrorAction Stop) + } catch { + throw $_.Exception.Message + } + } else { + throw $_.Exception.Message + } +} + +#Loop through the Azure AD roles +foreach ($AzureADRole in $AzureADRoles) { + + Write-Verbose "Processing $($AzureADRole.DisplayName)" + + #Get the list of members for the role + $RoleMembers = @(Get-AzureADDirectoryRoleMember -ObjectId $AzureADRole.ObjectId) + + #Loop through the list of members + foreach ($RoleMember in $RoleMembers) { + $ObjectProperties = [Ordered]@{ + "Role" = $AzureADRole.DisplayName + "Display Name" = $RoleMember.DisplayName + "Object Type" = $RoleMember.ObjectType + "Account Enabled" = $RoleMember.AccountEnabled + "User Principal Name" = $RoleMember.UserPrincipalName + "Password Policies" = $RoleMember.PasswordPolicies + "HomePage" = $RoleMember.HomePage + } + + $RoleMemberObject = New-Object -TypeName PSObject -Property $ObjectProperties + + #Add the role member's details to the array for the report data + [void]$O365AdminGroupReport.Add($RoleMemberObject) + } +} + +Write-Verbose "Outputting report" + +#Check if a file of the same name already exists +if (Test-Path -Path $OutputFileName) { + if (-not $Overwrite) { + #File exists and -Overwrite switch not used, so a random string will be appended to filename for uniqueness + $RandomString = -join(48..57+65..90+97..122 | ForEach-Object {[char]$_} | Get-Random -Count 4) + $OutputFileNameSplit = $OutputFileName.Split(".") + $OutputFileNamePrefix = $OutputFileNameSplit[0..($OutputFileNameSplit.length -2)] + $OutputFileName = "$($OutputFileNamePrefix)-$($RandomString).$($OutputFileNameSplit[-1])" + Write-Verbose "A file with the desired name already exists. New file name will be $($OutputFileName)" + } +} + +#Output the report to CSV +if ($Overwrite) { + $O365AdminGroupReport | Export-CSV -Path $OutputFileName -Force -NoTypeInformation +} else { + $O365AdminGroupReport | Export-CSV -Path $OutputFileName -NoClobber -NoTypeInformation +} diff --git a/README.md b/README.md index 10be19d..a433d1b 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,50 @@ -# Office365AdminGroupsReport -A PowerShell script to generate a report of Office 365 admin role/group membership. +# Office 365 Admin Groups Report + +### A PowerShell script to generate a report of Office 365 admin role/group membership. + +This script produces a report of the membership of Office 365 admin role groups. The report is output to CSV file. + +## Usage + +This script relies on the AzureAD PowerShell module, which you can [install from the PowerShell Gallery](https://docs.microsoft.com/en-us/powershell/azure/install-adv2?view=azureadps-2.0). + +1. Download the latest release from the [TechNet Script Gallery](https://gallery.technet.microsoft.com/office/Office-365-Role-Groups-b1eb6c6a). +2. Run the script using the usage examples below. You will be prompted to authenticate to Azure AD if you are not already connected. + +### Parameters + +- **ReportFile** - You can provide a custom output file name. The file name you specify will be modified with the current date, for example MyReportFileName.csv will become MyReportFileName-ddMMyyyy.csv. If a file of the same name exists, a unique character string will also be appended to the file name. + +- **Overwrite** - Overwrites an existing report file of the same name, instead of appending a unique character string. + +### Examples + +``` +.\Get-O365AdminGroupsReport.ps1 +``` + +``` +.\Get-O365AdminGroupsReport.ps1 -ReportFile MyReportFileName.csv -Overwrite +``` + +``` +.\Get-O365AdminGroupsReport.ps1 -Verbose +``` + +## Credits + +Written by: Paul Cunningham + +Find me on: + +* My Blog: http://paulcunningham.me +* Twitter: https://twitter.com/paulcunningham +* LinkedIn: http://au.linkedin.com/in/cunninghamp/ +* Github: https://github.com/cunninghamp + +For more Office 365 tips, tricks and news check out [Practical 365](http://practical365.com). + +* Website: https://practical365.com +* Twitter: http://twitter.com/practical365 +* Facebook: https://www.facebook.com/Practical365 +