Share via


Migrate your Assessment application from Microsoft Azure Active Directory to Microsoft Graph

Background

We currently use the Microsoft Azure Active Directory (Azure AD) application for authentication and to gather information from tenants regarding technologies like SharePoint Online, Exchange Online, and Microsoft Entra ID.

The Azure AD application, the Azure AD module, and the Azure RM module are nearing the end of their lifecycle. The Azure AD application currently uses a certificate for authentication. Also, Azure Active Directory Authentication Library (ADAL) is being replaced by Microsoft Authentication Libraries (MSAL), so applications need to be migrated from ADAL to MSAL.

As part of these changes, you need to remove your current application, replace it with the new version, and update your assessment platform extension to access the new application.

The new application provides you with a smoother authentication process; instead of saving credentials locally and passing MFA, your browser experience retains your sign-in information. Existing certificate formatting and behavior remains the same.

Steps to take

Remove your existing Azure AD application

Open PowerShell and run the following cmdlet. Make sure you type "yes" afterwards to confirm you want to proceed with the deletion.

    Clear-MicrosoftAssessmentsApplication -IncludeAADApplication $true -Force $true

This cmdlet ensures that both your current application registered in Azure and any related local machine entries are removed.

Note

The new application's Application ID URI is slightly different from the old one, making it easier to tell them apart. The old one has V2 at the end of the Application ID URI, while the new one has V3.

The Application ID URI section where V3 is visible at the end of the link.

Update your extension

Note

You can use the Azure portal to see what extension version is installed on your machine. Verify the extension information for each machine you have with assessments installed. You can also check for this information on a local machine if you look under C:\Packages\Plugins\"ExtensionName".

Use the Azure Portal to update your extension to AssessmentPlatform version 4.8.

The new application code is present in the Microsoft.Assessments.AADApplicationManager PowerShell script module (version 4.3).

The script checks to see if the Azure AD Preview module and Azure Resource Manager (ARM) are present. If they are, the script removes them and installs the latest modules available for Azure PowerShell and Microsoft Graph. Your assessment can then begin to use the new module, verify that all modules are installed, and perform any further installations and removals as necessary.

Verify available deployed extensions

To verify available deployed extensions, run the following query in either PowerShell or the Azure Command-Line Interface (CLI).

Replace the item after -Type in this query to pull details about the latest version available in the Azure portal for your specific type.

Get-AzVMExtensionImage -Location "East US" -PublisherName "Microsoft.ServicesHub" -Type "ADAssessmentPlus" | Select-Object -Property Type, Version | Sort-Object -Property Version -Descending | Select-Object -First 1

Create your new Microsoft Graph application

This section of the article provides you with a script that creates your new Microsoft Graph application along with a self-signed certificate for it. The instructions also help you setup the required permissions that satisfy assessment prerequisites.

  1. In a new PowerShell window, run the following cmdlet. Make sure you don't use the same PowerShell window where you ran Clear-MicrosoftAssessmentsApplication, because that will cause errors.

    New-MicrosoftAssessmentsApplication
    

    Note

    Verify that the referenced version is version 4.3. If it isn't, review Update your extension and check Environment Variables - PSModule paths to make sure all upgrades are in place.

    PowerShell window with the "New-MicrosoftAssessmentsApplication" cmdlet run.

  2. Wait for the module's installation to finish, then user your cloud credentials to sign in when you're prompted.

  3. If you haven't used Microsoft Graph Command-Line Tools on your selected tenant yet, another prompt appears that asks for your consent to use Microsoft Graph. Select the checkbox labeled "Provide consent for your organization", then select Accept.

    Pop up that requests permissions for Microsoft Graph Command-Line Tools.

    The script's output should look similar to the following example:

    Output from the "New-MicrosoftAssessmentsApplication" cmdlet.

  4. Grant consent for the required permissions.

    List of requested permissions.

Once you provide your consent, your application is ready for use, and you should be redirected to the Microsoft Entra homepage within the Azure portal. Automated data collection and upload will resume the same as they were before you performed the update.

If you want to review or modify permissions you previously granted to Microsoft Graph Command-Line Tools, sign in to the Azure portal and navigate to the Enterprise Applications section.

The Microsoft Graph Command-Line Tools permissions view in the Azure Portal.

You can view your newly created application in the Azure portal, where the Application ID URI should contain the expected V3 marker, as shown in the following screenshot.

The Microsoft Assessments Overview section in the Azure portal.

Updating Assessment Platform from 4.7 to 4.8 and above:

After updating the Assessment Platform extension to 4.8, please run below commands in PowerShell before running any assessments.

Update-Module -Name Microsoft.Graph

After the module is updated, verify the newest version has been installed:

Import-Module Microsoft.Graph.Authentication
Get-Module

The version listed should be 2.28.0 or above:

ModuleType Version    Name                                ExportedCommands
---------- -------    ----                                ----------------
Script     2.28.0     Microsoft.Graph.Authentication      {Add-MgEnvironment, Connect-MgGraph, Disconnect-MgGraph, G...

If you are on AssessmentPlatform 4.7: (Ignore this if you are on 4.8 and above)

Microsoft Graph Powershell module version 2.26 has an issue that can cause the following error when you run the ODA:

Method not found: 'Void Microsoft.Graph.Authentication.
AzureIdentityAccessTokenProvider..ctor(Azure.Core.TokenCredential,
System.String[], Microsoft.Kiota.Authentication.Azure.ObservabilityOptions,
Boolean, System.String[])'.

To avoid this error, uninstall Microsoft Graph version 2.26 and install version 2.25 by running the following commands in a new PowerShell window, but only after New-MicrosoftAssesmentsApplication is completed.

  1. Uninstall Microsoft Graph version 2.26.

    Uninstall-Module -Name Microsoft.Graph -AllVersions
    Get-InstalledModule Microsoft.Graph.* | ? Name -ne "Microsoft.Graph.Authentication" | Uninstall-Module -AllVersions
    Uninstall-Module Microsoft.Graph.Authentication -AllVersions
    
  2. Reinstall version 2.25.

    Install-Module -Name Microsoft.Graph -RequiredVersion 2.25.0 -AllowClobber
    
  3. Verify you have the correct version installed for Microsoft.Graph.Authentication:

    PS C:\> Import-Module Microsoft.Graph.Authentication
    PS C:\> Get-Module
    
    ModuleType Version  Name                            ExportedCommands
    
    ---------- -------  ----                            ----------------
    
    Script     2.25.0   Microsoft.Graph.Authentication  {Add-MgEnvironment, 
    Connect-MgGraph, Disconnect-MgGraph,