Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/AzureAD/AzureADAssessment
Tooling for assessing an Azure AD tenant state and configuration
https://github.com/AzureAD/AzureADAssessment
powershell
Last synced: 3 days ago
JSON representation
Tooling for assessing an Azure AD tenant state and configuration
- Host: GitHub
- URL: https://github.com/AzureAD/AzureADAssessment
- Owner: AzureAD
- License: mit
- Created: 2019-06-07T22:19:30.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-06-12T15:56:54.000Z (5 months ago)
- Last Synced: 2024-10-11T00:15:15.722Z (about 1 month ago)
- Topics: powershell
- Language: PowerShell
- Homepage:
- Size: 13.1 MB
- Stars: 751
- Watchers: 37
- Forks: 107
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- Awesome-Azure-Pentest - Microsoft Azure AD Assessment - Tooling for assessing an Azure AD tenant state and configuration (Tools / Information Gathering)
README
# Microsoft Azure AD Assessment
[](https://www.powershellgallery.com/packages/AzureADAssessment) [](https://www.powershellgallery.com/packages/AzureADAssessment) [](https://www.powershellgallery.com/packages/AzureADAssessment)
## Assessor Guide
If you are a Microsoft employee or partner performing the assessment for a customer please see the Wiki for the [Assessment Guide](https://github.com/AzureAD/AzureADAssessment/wiki).
## Install from the PowerShell Gallery
If you run into any errors please see the [FAQ section](#faq) at the end of this document.
```PowerShell
Install-Module AzureADAssessment -Force -Scope CurrentUser
## If you have already installed the module, run the following instead to ensure you have the latest version.
Update-Module AzureADAssessment -Force -Scope CurrentUser
```
## Create an app in Entra ID
The assessment requires a custom app to be created in your tenant.
* Open **Entra admin center** > **Identity** > **Applications** > **App registrations**
* Select **New registration**
* Name: Enter a name for the application (e.g. Entra Assessment Account)
* Redirect URI:
* Select **Mobile and desktop applications** from the drop down
* Set the uri as `https://login.microsoftonline.com/common/oauth2/nativeclient`
* Select **Register** to create the app
* Select the **Authentication** blade of the app you just created from the left navigation
* Set **Allow public client flows** to **Yes**
* Click **Save**
## Run the Data Collection
Data collection from Azure AD can be run from any client with access to Azure AD. However, data collection from hybrid components such as AD FS, AAD Connect, etc. are best run locally on those servers. The AAD Connect data collection needs to be run on both Primary and Staging servers.
Verify that you have authorized credentials to access these workloads:
* Azure Active Directory as Global Administrator or Global Reader
* Domain or local administrator access to ADFS Servers
* Domain or local administrator access to Azure AD Proxy Connector Servers
* Domain or local administrator access to Azure AD Connect Server (Primary)
* Domain or local administrator access to Azure AD Connect Server (Staging Server)
> When Connecting for the first time you will be asked to consent to the permissions needed by the assessment. An admin will be needed to provide consent.
Run following commands to produce a package of all the Azure AD data necessary to complete the assessment.
```PowerShell
## Authenticate using a Global Admin or Global Reader account.
Connect-AADAssessment -ClientId "AppId of app created in the previous step"
## Export data to "C:\AzureADAssessment" into a single output package.
Invoke-AADAssessmentDataCollection
```
The output package will be named according to the following pattern: `AzureADAssessmentData-.aad`
If Data Collection command fails before completing, try running it again with the SkipReportOutput parameter.
```PowerShell
Invoke-AADAssessmentDataCollection -SkipReportOutput
```
On each server running hybrid components, install the same module and run the Invoke-AADAssessmentHybridDataCollection command.
```PowerShell
## Export Data to "C:\AzureADAssessment" into a single output package.
Invoke-AADAssessmentHybridDataCollection
```
The output package will be named according to the following pattern: `AzureADAssessmentData--.zip`
Once data collection is complete, provide the output packages to whoever is completing the assessment. Please avoid making any changes to the generated files including the name of the file.
## Complete Assessment Reports
If you are generating and reviewing the output yourself, please see the Wiki for the [Assessment Guide](https://github.com/AzureAD/AzureADAssessment/wiki).
##
Frequently Asked Questions
### I don't have internet access to install the module on AAD Connect, ADFS, App Proxy servers
To collect data from hybrid components (such as AAD Connect, AD FS, AAD App Proxy), you can export a portable version of this module that can be easily copied to servers with no internet connectivity.
```PowerShell
## Export Portable Module to "C:\AzureADAssessment".
Export-AADAssessmentPortableModule "C:\AzureADAssessment"
```
On each server running hybrid components, copy the module file "AzureADAssessmentPortable.psm1" and import it there.
```PowerShell
## Import the module on each server running hybrid components.
Import-Module "C:\AzureADAssessment\AzureADAssessmentPortable.psm1"
## Export Data to "C:\AzureADAssessment" into a single output package.
Invoke-AADAssessmentHybridDataCollection
```
### I want to output the assessment files to a different directory
```PowerShell
## If you would like to specify a different directory, use the OutputDirectory parameter.
Invoke-AADAssessmentDataCollection "C:\Temp"
Invoke-AADAssessmentHybridDataCollection "C:\Temp"
```
### I want to use a service principal identity to run the assessment instead of a user identity
If you prefer to use your own app registration (service principal) for automation purposes, you may connect using your own ClientId and Certificate like the example below. Your app registration should include Directory.Read.All, Policy.Read.All, and AuditLog.Read.All application permissions to MS Graph for a complete assessment. Once added, ensure you have completed admin consent on the service principal for those permissions.
```PowerShell
## Connect using Service Principal identity with app permissions.
Connect-AADAssessment -ClientId -ClientCertificate (Get-Item 'Cert:\CurrentUser\My\') -TenantId
```
### I have a tenant in sovereign cloud, how do I run this assessment?
You must create an application registration in your tenant and provide the ClientId when running Connect-AADAssessment. The default application configuration should work as long as you define the correct redirect URI for your cloud environment. For example, a "Mobile and desktop application" Redirect URI of `https://login.microsoftonline.us/common/oauth2/nativeclient`.
```PowerShell
## Example connecting to USGov cloud environment using user delegated permissions.
Connect-AADAssessment -ClientId -CloudEnvironment USGov -TenantId
## Example connecting to USGov cloud environment using app permissions.
Connect-AADAssessment -ClientId -ClientCertificate (Get-Item 'Cert:\CurrentUser\My\') -CloudEnvironment USGov -TenantId
```
### When trying to install the module I'm receiving the error 'A parameter cannot be found that matches parameter name 'AcceptLicense'
Run the following command to update PowerShellGet to the latest version before attempting to install the AzureADAssessment module again. Option 1 is a single command executing a script (), while option 2 requires multiple commands and some possible troubleshooting.
```PowerShell
### Option 1: Run the following command to download and execute a script to update PowerShellGet. Note: Navigate to this URL in a web browser to see the contents of the script in GitHub.
iex $(irm 'https://aka.ms/Update-PowerShellGet')
### Option 2: Run the following commands individually.
## Update Nuget Package and PowerShellGet Module
Install-PackageProvider NuGet -Scope CurrentUser -Force
Install-Module PowerShellGet -Scope CurrentUser -Force -AllowClobber
## Remove old modules from existing session
Remove-Module PowerShellGet,PackageManagement -Force -ErrorAction Ignore
## Import updated module
Import-Module PowerShellGet -MinimumVersion 2.0 -Force
Import-PackageProvider PowerShellGet -MinimumVersion 2.0 -Force
```
### If at any point you see the error, ` cannot be loaded because running scripts is disabled on this system. For more information, see about_Execution_Policies at http://go.microsoft.com/fwlink/?LinkID=135170.`, you must enable local scripts to be run.
```PowerShell
## Set globally on device
Set-ExecutionPolicy RemoteSigned
## Or set for just for current PowerShell session.
Set-ExecutionPolicy RemoteSigned -Scope Process
```
### MSAL.PS Certificate Error (Authenticode issuer)
The signing certificate for MSAL.PS is changing to use Microsoft's code signing process. If you see the following error, `PackageManagement\Install-Package : Authenticode issuer 'CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US' of the new module 'MSAL.PS' with version 'x.x.x.x' from root certificate authority 'CN=Microsoft Root Certificate Authority 2011, O=Microsoft Corporation, L=Redmond, S=Washington, C=US' is not matching with the authenticode issuer 'CN=Jason Thompson, O=Jason Thompson, L=Cincinnati, S=Ohio, C=US' of the previously-installed module 'MSAL.PS' with version 'x.x.x.x' from root certificate authority 'CN=DigiCert Assured ID Root CA, OU=www.digicert.com, O=DigiCert Inc, C=US'. If you still want to install or update, use -SkipPublisherCheck parameter.`, you can resolve it using the following command.
```PowerShell
Install-Module MSAL.PS -SkipPublisherCheck -Force
```
### Unable to sign in with device code flow
If you are using PowerShell Core (ie PowerShell 6 or 7) and your tenant has a conditional access policy that requires a Compliant or Hybrid Azure AD Joined device, you may not be able to sign in.
To work around this issue use Windows PowerShell (instead of PowerShell 6 or 7). To launch Windows PowerShell go to **Start > Windows PowerShell**
### Unable to load data in PowerBI templates ###
When you open the powerbi templates, you will be asked to reference the folder where the extracted data resides (csv and json). Once selected PowerBI will load the data.
While doing so PowerBI might complain with errors crossreferncing data sources:
```
Query '*' (step '*') references other queries or steps, so it may not directly access a datasource. Please rebuild this data combination.
```
To workarround this, configure PowerBI file settings to ignore privacy settings:
* **File > Options and settings > Options**
* In **Options** under **CURRENT FILE** find the **Privacy**
* In **Privacy Levels** select **Ignore the Privacy Levels and potentially improve performance**
## Contents
| File/folder | Description |
|-------------------|---------------------------------------------------------|
| `build` | Scripts to package, test, sign, and publish the module. |
| `src` | Module source code. |
| `tests` | Test scripts for module. |
| `.gitignore` | Define what to ignore at commit time. |
| `README.md` | This README file. |
| `LICENSE` | The license for the module. |
## 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 [[email protected]](mailto:[email protected]) with any additional questions or comments.
For more detailed guidance and recommendations for contributing, see the page for [contributing](CONTRIBUTING.md).