Connecting Azure Automation

This guide outlines the onboarding process for both new and existing Automation Accounts.

Overview

To enable RealmJoin Portal to deliver runbooks for automating daily tasks, you must connect an Azure Automation Account. This Automation Account will act as the host for your runbooks and provide the permissions required for the runbooks to function within your environment.

Considerations

The Automation Account's Managed Identity requires extensive permissions in your environment, such as the ability to modify group or user objects in Entra ID or manage mailboxes in Exchange Online. Limit administrative access to this account to prevent misuse of these privileges.

When using an existing Automation Account, note that RealmJoin Portal automatically creates, updates and removes runbooks coming from the shared online repository of runbooks. This functionality may not be supported in an existing Automation Account. If uncertain, we recommend creating a dedicated Azure Automation Account for RealmJoin Runbooks.

Prerequisites

Global Administrator privileges
Access to PowerShell with the Az module or AZ CLI
Contributor permissions on an Azure subscription
Runbook requirements

Instructions

Create an Azure Automation Account

Navigate to your Azure Portal > Automation Accounts
Create a new Automation Account
In the Basics tab, choose your desired Subscription, Resource Group, Automation Account Name and Region

A separate Resource Group for your Automation Account is recommended

In the Advanced tab, ensure the System Assigned Managed Identity is enabled
Select Review + Create and create your Automation Account
Navigate to the Resource Group containing your Azure Automation Account
In the IAM tab, assign the Azure Automation Account as a Contributor

Assign Permissions to Azure Automation Account

The RealmJoin shared runbooks use the Azure Automation's system assigned managed identity to interact with Entra ID, MS Graph API etc.

Managed Identity permissions cannot currently be granted through the Azure Portal. Use Microsoft Graph or PowerShell to assign these permissions.

Download the following PowerShell scripts and JSON files to the same folder. The script will assign the full permission set required by RealmJoin. Roles and permissions can be reviewed in the Requirements section and adjusted as needed in the JSON files.

https://github.com/Workplace-Foundation/approle-and-directoryrole-granter/blob/main/GrantAppPermToEntApp.ps1

# Allow assigning MS Graph and similar permissions to a Managed Identity - without using the AzureAD module

# Input should be readble (claim names in JSON), parsed from a file



# based on https://techcommunity.microsoft.com/t5/integrations-on-azure-blog/grant-graph-api-permission-to-managed-identity-object/ba-p/2792127



#Requires -modules Microsoft.Graph.Applications,Microsoft.Graph.Authentication



param(

    # Please give the managed identity's or enterprise app's object id.  

    [Parameter(Mandatory = $true)]

    [string] $enterpriseAppObjId,

    [string] $permissionsTemplate = "RealmJoinVnext\RjvNextPermissions.json",

    [switch] $disconnectAfterExecution = $false,

    [switch] $showErrors = $false

)



## Authenticate as admin (delegated). Use MS Graph PowerShell SDK to leverage existing (well known) clientId/app.

## Will sign you in using your browser and ask for granting permissions if needed.

Connect-MgGraph -Scopes "AppRoleAssignment.ReadWrite.All,Application.Read.All"



## Read the permission template

$permissions = Get-Content -Path $permissionsTemplate | ConvertFrom-Json



"## Set permissions on the enterprise app/mgd identity"

$permissions | ForEach-Object {

    $appId = $_.Id



    ## Get Service Principal from Application:

    $resourceApp = Get-MgServicePrincipal -Filter "AppId eq '$appId'" 

    $resourceId = $resourceApp.Id



    ## Get all AppRoles. Create a hashtable giving "Claim -> AppRoleId"

    $appRoles = @{}

    $resourceApp.AppRoles | ForEach-Object {

        $appRoles.add($_.Value, $_.Id)

    }



    ## Apply each permission to the Ent App/Mgd. Identity

    $_.AppRoleAssignments | ForEach-Object {

        "## Assigning $($resourceApp.DisplayName):$_"

        try {

            New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $enterpriseAppObjId -AppRoleId $appRoles[$_] -ResourceId $resourceId -PrincipalId $enterpriseAppObjId -ErrorAction Stop | Out-Null

        }

        catch {

            "## - Permission already assigned or assignment failed. Skipping..."

            if ($showErrors) {

                $_

            }

        }

    }

}



if ($disconnectAfterExecution) {

    Disconnect-MgGraph | Out-Null

}

https://github.com/Workplace-Foundation/approle-and-directoryrole-granter/blob/main/AssignAzureADRoleToEntApp.ps1

# Allow assigning AzureAD Roles to a user, group or service principal - without using the AzureAD module

# Input should be readble (roles names in JSON), parsed from a file



#Requires -modules Microsoft.Graph.Authentication,Microsoft.Graph.Identity.DirectoryManagement



param(

    # Please give the managed identities AzureAD object id. 

    [Parameter(Mandatory = $true)]

    [string] $objectId,

    [string] $rolesTemplate = "RealmJoinVnext\RjvNextRoles.json",

    [switch] $disconnectAfterExecution = $false,

    [switch] $showErrors = $false

)



## Authenticate as admin (delegated). Use MS Graph PowerShell SDK to leverage existing (well known) clientId/app.

## Will sign you in using your browser and ask for granting permissions if needed.

Connect-MgGraph -Scopes "RoleManagement.ReadWrite.Directory"



## Read the roles template

$targetRoles = Get-Content -Path $rolesTemplate | ConvertFrom-Json

$allRoles = Get-MgDirectoryRole

$allRoleTemplates = Get-MgDirectoryRoleTemplate



## Check if all roles already exist. Create them if needed.

$targetRoles | ForEach-Object {

    $roleDisplayName = $_

    $adminRole = $allRoles | Where-Object { $_.DisplayName -eq $roleDisplayName }

    if (-not $adminRole) {

        "## Role '$roleDisplayName' not found (yet). Activating role from template..." 

        # Find Role Template...

        $roleTemplate = $allRoleTemplates | Where-Object { $_.DisplayName -eq $roleDisplayName }

        if (-not $roleTemplate) {

            throw "RoleTemplate '$roleDisplayName not found!"

        }

        $adminRole = New-MgDirectoryRole -RoleTemplateId $roleTemplate.Id

    }

    else {

        $adminRole = $allRoles | Where-Object { $_.DisplayName -eq $roleDisplayName }

        "## Role '$roleDisplayName' found. ID: $($adminRole.Id)"

    }



    # Add principal to role

    if ($adminRole) {

        "## Adding member '$objectId' to '$roleDisplayName'"

        try {

            New-MgDirectoryRoleMemberByRef -DirectoryRoleId ($adminRole.Id) -OdataId "https://graph.microsoft.com/v1.0/directoryObjects/$objectId" -ErrorAction Stop

        }

        catch {

            "## - Role already assigned or assignment failed. Skipping..."

            if ($showErrors) {

                $_

            }

        }

    }

    else {

        throw "## AdminRole '$roleDisplayName' not found!"

    }

}



if ($disconnectAfterExecution) {

    Disconnect-MgGraph | Out-Null

}

https://github.com/realmjoin/realmjoin-runbooks/blob/production/docs/other/json/AllRealmJoinRunbooks_collected_permissions.json

[
  {
    "Name": "Microsoft Graph",
    "Id": "00000003-0000-0000-c000-000000000000",
    "AppRoleAssignments": [
      "AppRoleAssignment.ReadWrite.All",
      "Application.ReadWrite.All",
      "Application.ReadWrite.OwnedBy",
      "AuditLog.Read.All",
      "BitlockerKey.Read.All",
      "Channel.ReadBasic.All",
      "ChannelMember.ReadWrite.All",
      "CloudPC.ReadWrite.All",
      "Device.ReadWrite.All",
      "DeviceLocalCredential.Read.All",
      "DeviceManagementApps.ReadWrite.All",
      "DeviceManagementConfiguration.ReadWrite.All",
      "DeviceManagementManagedDevices.PrivilegedOperations.All",
      "DeviceManagementManagedDevices.ReadWrite.All",
      "DeviceManagementServiceConfig.ReadWrite.All",
      "Directory.ReadWrite.All",
      "Group.Create",
      "Group.ReadWrite.All",
      "GroupMember.ReadWrite.All",
      "IdentityRiskyUser.ReadWrite.All",
      "InformationProtectionPolicy.Read.All",
      "Mail.Send",
      "Organization.Read.All",
      "Place.Read.All",
      "Policy.Read.All",
      "ReportSettings.ReadWrite.All",
      "Reports.Read.All",
      "RoleAssignmentSchedule.Read.Directory",
      "RoleManagement.Read.All",
      "RoleManagement.Read.Directory",
      "ServiceHealth.Read.All",
      "Team.Create",
      "TeamMember.ReadWrite.All",
      "TeamSettings.ReadWrite.All",
      "User.ReadWrite.All",
      "UserAuthenticationMethod.ReadWrite.All",
      "WindowsUpdates.ReadWrite.All"
    ]
  },
  {
    "Name": "Office 365 Exchange Online",
    "Id": "00000002-0000-0ff1-ce00-000000000000",
    "AppRoleAssignments": [
      "Exchange.ManageAsApp"
    ]
  },
  {
    "Name": "WindowsDefenderATP",
    "Id": "fc780465-2017-40d4-a0c5-307022471b92",
    "AppRoleAssignments": [
      "Machine.Isolate",
      "Machine.ReadWrite.All",
      "Machine.RestrictExecution",
      "Ti.ReadWrite.All"
    ]
  }
]

https://github.com/realmjoin/realmjoin-runbooks/blob/production/docs/other/json/AllRealmJoinRunbooks_collected_rbacroles.json

[
  "Application Developer",
  "Cloud Device Administrator",
  "Exchange Administrator",
  "Intune Administrator",
  "Teams Administrator",
  "User Administrator"
]

Note down the Object ID of the Azure Automation Account's Managed Identity in Account Settings > Identity
Open a PowerShell window.
Navigate to the folder containing the downloaded files

cd c:\temp\myfolder

Unblock scripts if necessary
Assign MS Graph Permissions to your Azure Automation Account using GrantAppPermToEntApp.ps1, replacing xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx with your Automation Account's Object ID

. .\GrantAppPermToEntApp.ps1 -enterpriseAppObjId "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -permissionsTemplate .\AllRealmJoinRunbooks_collected_permissions.json

Assign Entra ID Admin Roles to your Azure Automation Account using AssignAzureADRoleToEntApp.ps1 replacing xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx with your Automation Account's Object ID

. .\AssignAzureADRoleToEntApp.ps1 -objectId "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -rolesTemplate .\AllRealmJoinRunbooks_collected_rbacroles.json

The Azure Automation Account should now have the correct permissions to execute Runbooks

RealmJoin Runbook Configuration - Part 1

In RealmJoin Portal go to 'Settings -> Runbooks'.
Fill in the Tenant ID, Subscription ID and Resource Group name belonging to the Azure Automation Account The Tenant ID in the Entra ID Overview page
Copy the script in red underneath ResourceGroup. This script creates a Service Principal in Entra ID with access to your Automation Account, allowing RealmJoin to manage, run and monitor runbooks. The script is updated based on the inputs for Tenant ID, Subscription ID and Resource Group.
Leave the wizard open for now. We will return shortly in part 2.

Granting Access for RealmJoin to Azure Automation

You can use Azure CloudShell, so you don't need to install and authenticate a local copy of AZ CLI.

Run the script copied previously in PowerShell.
Note down the values for appId and password. The App Registration "RealmJoin Runbook Management" will be created.
App Registrations in Azure Portal

RealmJoin Runbook Configuration - Part 2

In RealmJoin Portal return to the open window/wizard for 'Settings -> Runbooks'
Fill in the missing values for appId and password created in the last step
Fill in the name of the Automation Account created previously
Choose the Branch of the shared runbook repository you want to follow. If unsure, please choose production All runbook branches may be viewed here: https://github.com/realmjoin/realmjoin-runbooks
Choose the same location as your Azure Automation Account to make sure your runbooks are executed in the correct Azure region

Press "Save" to start the initial import of runbooks. Please leave this window open until you see the message "Sync completed".

Last updated 7 days ago

Was this helpful?