Azure Active Directory Identity Protection and the Microsoft Graph PowerShell SDK

Microsoft Graph is the Microsoft unified API endpoint and the home of Azure Active Directory Identity Protection APIs. This article will show you how to use the Microsoft Graph PowerShell SDK to get risky user details using PowerShell. Organizations that want to query the Microsoft Graph APIs directly can use the article, Tutorial: Identify and remediate risks using Microsoft Graph APIs to begin that journey.

Connect to Microsoft Graph

There are four steps to accessing Identity Protection data through Microsoft Graph:

Create a certificate

In a production environment you would use a certificate from your production Certificate Authority, but in this sample we will use a self-signed certificate. Create and export the certificate using the following PowerShell commands.

$cert = New-SelfSignedCertificate -Subject "CN=MSGraph_ReportingAPI" -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256
Export-Certificate -Cert $cert -FilePath "C:\Reporting\MSGraph_ReportingAPI.cer"

Create a new app registration

  1. In the Azure portal, browse to Azure Active Directory > App registrations.
  2. Select New registration.
  3. On the Create page, perform the following steps:
    1. In the Name textbox, type a name for your application (for example: Azure AD Risk Detection API).
    2. Under Supported account types, select the type of accounts that will use the APIs.
    3. Select Register.
  4. Take note of the Application (client) ID and Directory (tenant) ID as you will need these items later.

Configure API permissions

In this example, we configure application permissions allowing this sample to be used unattended. If granting permissions to a user who will be logged on, choose delegated permissions instead. More information about different permission types can be found in the article, Permissions and consent in the Microsoft identity platform.

  1. From the Application you created, select API permissions.
  2. On the Configured permissions page, in the toolbar on the top, click Add a permission.
  3. On the Add API access page, click Select an API.
  4. On the Select an API page, select Microsoft Graph, and then click Select.
  5. On the Request API permissions page:
    1. Select Application permissions.
    2. Select the checkboxes next to IdentityRiskEvent.Read.All and IdentityRiskyUser.Read.All.
    3. Select Add permissions.
  6. Select Grant admin consent for domain

Configure a valid credential

  1. From the Application you created, select Certificates & secrets.
  2. Under certificates, select Upload certificate.
    1. Select the previously exported certificate from the window that opens.
    2. Select Add.
  3. Take note of the Thumbprint of the certificate as you will need this information in the next step.

List risky users using PowerShell

To enable the ability to query Microsoft Graph, we need to install the Microsoft.Graph module in our PowerShell window, using the Install-Module Microsoft.Graph command.

Modify the following variables to include the information generated in the previous steps, then run them as a whole to get risky user details using PowerShell.

$ClientID       = "<your client ID here>"        # Application (client) ID gathered when creating the app registration
$tenantdomain   = "<your tenant domain here>"    # Directory (tenant) ID gathered when creating the app registration
$Thumbprint     = "<your client secret here>"    # Certificate thumbprint gathered when configuring your credential

Select-MgProfile -Name "beta"
  
Connect-MgGraph -ClientId $ClientID -TenantId $tenantdomain -CertificateThumbprint $Thumbprint

Get-MgRiskyUser -All

Next steps