Microsoft Azure AD Assessment

Assessor Guide

If you are a Microsoft employee or partner performing the assessment for a customer please see the Wiki for the Assessment Guide.

Install from the PowerShell Gallery

If you run into any errors please see the FAQ section at the end of this document.

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.

## 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-<TenantDomain>.aad

If Data Collection command fails before completing, try running it again with the SkipReportOutput parameter.

Invoke-AADAssessmentDataCollection -SkipReportOutput

On each server running hybrid components, install the same module and run the Invoke-AADAssessmentHybridDataCollection command.

## Export Data to "C:\AzureADAssessment" into a single output package.
Invoke-AADAssessmentHybridDataCollection

The output package will be named according to the following pattern: AzureADAssessmentData-<Svc>-<ServerName>.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.

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.

## 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.

## 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

## 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.

## Connect using Service Principal identity with app permissions.
Connect-AADAssessment -ClientId <ClientId> -ClientCertificate (Get-Item 'Cert:\CurrentUser\My\<Thumbprint>') -TenantId <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.

## Example connecting to USGov cloud environment using user delegated permissions.
Connect-AADAssessment -ClientId <ClientId> -CloudEnvironment USGov -TenantId <TenantId>

## Example connecting to USGov cloud environment using app permissions.
Connect-AADAssessment -ClientId <ClientId> -ClientCertificate (Get-Item 'Cert:\CurrentUser\My\<Thumbprint>') -CloudEnvironment USGov -TenantId <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 (https://aka.ms/Update-PowerShellGet), while option 2 requires multiple commands and some possible troubleshooting.

### 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