Muokkaa

Jaa

Automate Microsoft Entra ID Governance tasks via Azure Automation and Microsoft Graph

  • Artikkeli

Azure Automation is an Azure cloud service that allows you to automate common or repetitive systems management and processes. Microsoft Graph is the Microsoft unified API endpoint for Microsoft Entra features that manage users, groups, access packages, access reviews, and other resources in the directory.

You can manage Microsoft Entra ID at scale from the PowerShell command line, using the Microsoft Graph PowerShell SDK. You can also include the Microsoft Graph PowerShell cmdlets from a PowerShell-based runbook in Azure Automation, so that you can automate Microsoft Entra tasks from a simple script.

Azure Automation and the PowerShell Graph SDK supports certificate-based authentication and application permissions, so you can have Azure Automation runbooks authenticate to Microsoft Entra ID without needing a user context.

This article shows you how to get started using Azure Automation for Microsoft Entra ID Governance, by creating a simple runbook that queries entitlement management via Microsoft Graph PowerShell.

Create an Azure Automation account

Tip

Steps in this article might vary slightly based on the portal you start from.

Azure Automation provides a cloud-hosted environment for runbook execution. Those runbooks can start automatically based on a schedule, or be triggered by webhooks or by Logic Apps.

Using Azure Automation requires you to have an Azure subscription.

Prerequisite role: Azure subscription or resource group owner

  1. Sign in to the Azure portal . Make sure you have access to the subscription or resource group where the Azure Automation account will be located.

  2. Select the subscription or resource group, and select Create. Type Automation, select the Automation Azure service from Microsoft, then select Create.

  3. After the Azure Automation account has been created, select Access control (IAM). Then select View in View access to this resource. These users and service principals will subsequently be able to interact with the Microsoft service through the scripts to be created in that Azure Automation account.

  4. Review the users and service principals who are listed there and ensure they're authorized. Remove any users who are unauthorized.

Create a self-signed key pair and certificate on your computer

So that it can operate without needing your personal credentials, the Azure Automation account you created will need to authenticate itself to Microsoft Entra ID with a certificate.

If you already have a key pair for authenticating your service to Microsoft Entra ID, and a certificate that you received from a certificate authority, skip to the next section.

To generate a self-signed certificate,

  1. Follow the instructions in how to create a self-signed certificate, option 2, to create and export a certificate with its private key.

  2. Display the thumbprint of the certificate.

     $cert | ft Thumbprint

  3. After you have exported the files, you can remove the certificate and key pair from your local user certificate store. In subsequent steps you remove the .pfx and .crt files as well, once the certificate and private key have been uploaded to the Azure Automation and Microsoft Entra services.

Upload the key pair to Azure Automation

Your runbook in Azure Automation retrieves the private key from the .pfx file, and use it for authenticating to Microsoft Graph.

  1. In the Azure portal for the Azure Automation account, select Certificates and Add a certificate.

  2. Upload the .pfx file created earlier, and type the password you provided when you created the file.

  3. After the private key is uploaded, record the certificate expiration date.

  4. You can now delete the .pfx file from your local computer. However, don't delete the .crt file yet, as you need this file in a subsequent step.

Add modules for Microsoft Graph to your Azure Automation account

By default, Azure Automation doesn't have any PowerShell modules preloaded for Microsoft Graph. You need to add Microsoft.Graph.Authentication, and then additional modules, from the gallery to your Automation account.

  1. In the Azure portal for the Azure Automation account, select Modules and then Browse gallery.

  2. In the Search bar, type Microsoft.Graph.Authentication. Select the module, select Import, and select OK to have Microsoft Entra ID begin importing the module. After selecting OK, importing a module can take several minutes. Don't attempt to add more Microsoft Graph modules until the Microsoft.Graph.Authentication module import has completed, since those other modules have Microsoft.Graph.Authentication as a prerequisite.

  3. Return to the Modules list and select Refresh. Once the Status of the Microsoft.Graph.Authentication module has changed to Available, you can import the next module.

  4. If you're using the cmdlets for Microsoft Entra ID Governance features, such as entitlement management, then repeat the import process for the module Microsoft.Graph.Identity.Governance.

  5. Import other modules that your script could require, such as Microsoft.Graph.Users. For example, if you're using Microsoft Entra ID Protection, then you could wish to import the Microsoft.Graph.Identity.SignIns module.

Create an app registration and assign permissions

Next, you create an app registration in Microsoft Entra ID, so that Microsoft Entra ID recognizes your Azure Automation runbook's certificate for authentication.

  1. Sign in to the Microsoft Entra admin center as at least an Application Administrator.
  2. Browse to Identity > Applications > App registrations.
  3. Select New registration.
  4. Type a name for the application and select Register.
    1. Once the application registration is created, take note of the Application (client) ID and Directory (tenant) ID as you need these items later.
  5. Select Certificates and Secrets > Certificates > Upload certificate.
    1. Upload the .crt file created earlier.
  6. Select API permissions > Add a permission.
  7. Select Microsoft Graph > Application permissions.

    1. Select each of the permissions that your Azure Automation account requires, then select Add permissions.

      • If your runbook is only performing queries or updates within a single catalog, then you don't need to assign it tenant-wide application permissions; instead you can assign the service principal to the catalog's Catalog owner or Catalog reader role.
      • If your runbook is only performing queries for entitlement management, then it can use the EntitlementManagement.Read.All permission.
      • If your runbook is making changes to entitlement management, for example to create assignments across multiple catalogs, then use the EntitlementManagement.ReadWrite.All permission.
      • For other APIs, ensure that the necessary permission is added. For example, for Microsoft Entra ID Protection, the IdentityRiskyUser.Read.All permission might be needed.

The application created in the previous section has permissions that require someone with at least the Privileged Role Administrator role to approve before it works as intended.

  1. Sign in to the Microsoft Entra admin center as at least a Privileged Role Administrator.
  2. Browse to Identity > Applications > App registrations > All applications.
  3. Select the app that was created in the previous section.
  4. Select API permissions and review the permissions required.
  5. If appropriate, select Grant admin consent for "Your Tenant Name" to give the application those permissions.

Create Azure Automation variables

In this step, you create in the Azure Automation account three variables that the runbook uses to determine how to authenticate to Microsoft Entra ID.

  1. In the Azure portal, return to the Azure Automation account.

  2. Select Variables, and Add variable.

  3. Create a variable named Thumbprint. Type, as the value of the variable, the certificate thumbprint that was generated earlier.

  4. Create a variable named ClientId. Type, as the value of the variable, the client ID for the application registered in Microsoft Entra ID.

  5. Create a variable named TenantId. Type, as the value of the variable, the tenant ID of the directory where the application was registered.

Create an Azure Automation PowerShell runbook that can use Graph

In this step, you create an initial runbook. You can trigger this runbook to verify the authentication using the certificate created earlier is successful.

  1. Select Runbooks and Create a runbook.

  2. Type the name of the runbook, select PowerShell as the type of runbook to create, and select Create.

  3. Once the runbook is created, a text editing pane appears for you to type in the PowerShell source code of the runbook.

  4. Type the following PowerShell into the text editor.

Import-Module Microsoft.Graph.Authentication
$ClientId = Get-AutomationVariable -Name 'ClientId'
$TenantId = Get-AutomationVariable -Name 'TenantId'
$Thumbprint = Get-AutomationVariable -Name 'Thumbprint'
Connect-MgGraph -clientId $ClientId -tenantId $TenantId -certificatethumbprint $Thumbprint

  1. Select Test pane, and select Start. Wait a few seconds for the Azure Automation processing of your runbook script to complete.

  2. If the run of your runbook is successful, then the message Welcome to Microsoft Graph! will appear.

Now that you have verified that your runbook can authenticate to Microsoft Graph, extend your runbook by adding cmdlets for interacting with Microsoft Entra features.

Extend the runbook to use Entitlement Management

If the app registration for your runbook has the EntitlementManagement.Read.All or EntitlementManagement.ReadWrite.All permissions, then it can use the entitlement management APIs.

  1. For example, to get a list of Microsoft Entra entitlement management access packages, you can update the above-created runbook, and replace the text with the following PowerShell.
Import-Module Microsoft.Graph.Authentication
$ClientId = Get-AutomationVariable -Name 'ClientId'
$TenantId = Get-AutomationVariable -Name 'TenantId'
$Thumbprint = Get-AutomationVariable -Name 'Thumbprint'
$auth = Connect-MgGraph -clientId $ClientId -tenantid $TenantId -certificatethumbprint $Thumbprint
Import-Module Microsoft.Graph.Identity.Governance
$ap = @(Get-MgEntitlementManagementAccessPackage -All -ErrorAction Stop)
if ($null -eq $ap -or $ap.Count -eq 0) {
   ConvertTo-Json @()
} else {
   $ap | Select-Object -Property Id,DisplayName | ConvertTo-Json -AsArray
}

  1. Select Test pane, and select Start. Wait a few seconds for the Azure Automation processing of your runbook script to complete.

  2. If the run was successful, the output instead of the welcome message will be a JSON array. The JSON array includes the ID and display name of each access package returned from the query.

Provide parameters to the runbook (optional)

You can also add input parameters to your runbook, by adding a Param section at the top of the PowerShell script. For instance,

Param
(
    [String] $AccessPackageAssignmentId
)

The format of the allowed parameters depends upon the calling service. If your runbook does take parameters from the caller, then you need to add validation logic to your runbook to ensure that the parameter values supplied are appropriate for how the runbook could be started. For example, if your runbook is started by a webhook, Azure Automation doesn't perform any authentication on a webhook request as long as it's made to the correct URL, so you need an alternate means of validating the request.

Once you configure runbook input parameters, then when you test your runbook you can provide values through the Test page. Later, when the runbook is published, you can provide parameters when starting the runbook from PowerShell, the REST API, or a Logic App.

Parse the output of an Azure Automation account in Logic Apps (optional)

Once your runbook is published, you can create a schedule in Azure Automation, and link your runbook to that schedule to run automatically. Scheduling runbooks from Azure Automation is suitable for runbooks that don't need to interact with other Azure or Office 365 services that don't have PowerShell interfaces.

If you wish to send the output of your runbook to another service, then you might wish to consider using Azure Logic Apps to start your Azure Automation runbook, as Logic Apps can also parse the results.

  1. In Azure Logic Apps, create a Logic App in the Logic Apps Designer starting with Recurrence.

  2. Add the operation Create job from Azure Automation. Authenticate to Microsoft Entra ID, and select the Subscription, Resource Group, Automation Account created earlier. Select Wait for Job.

  3. Add the parameter Runbook name and type the name of the runbook to be started. If the runbook has input parameters, then you can provide the values to them.

  4. Select New step and add the operation Get job output. Select the same Subscription, Resource Group, Automation Account as the previous step, and select the Dynamic value of the Job ID from the previous step.

  5. You can then add more operations to the Logic App, such as the Parse JSON action that uses the Content returned when the runbook completes. (If you're auto-generating the Parse JSON schema from a sample payload, be sure to account for PowerShell script potentially returning null; you might need to change some of the "type": ​"string" to "type": [​"string",​ "null"​] in the schema.)

In Azure Automation, a PowerShell runbook can fail to complete if it tries to write a large amount of data to the output stream at once. You can typically work around this issue by having the runbook output just the information needed by the Logic App, such as by using the Select-Object -Property cmdlet to exclude unneeded properties.

Plan to keep the certificate up to date

If you created a self-signed certificate following the steps above for authentication, keep in mind that the certificate has a limited lifetime before it expires. You need to regenerate the certificate and upload the new certificate before its expiration date.

There are two places where you can see the expiration date in the Azure portal.

  • In Azure Automation, the Certificates screen displays the expiration date of the certificate.
  • In Microsoft Entra ID, on the app registration, the Certificates & secrets screen displays the expiration date of the certificate used for the Azure Automation account.

Next steps