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

1

Create an Azure Automation Account

1. Navigate to your Azure Portal > Automation Accounts

2. Create a new Automation Account

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

1. In the Advanced tab, ensure the System Assigned Managed Identity is enabled

   

2. Select Review + Create and create your Automation Account

3. Navigate to the Resource Group containing your Azure Automation Account

4. In the IAM tab, assign the Azure Automation Account as a Contributor

2

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.

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

GrantAppPermToEntApp.ps1

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

}

AssignAzureADRoleToEntApp.ps1

RJvNextPermissions.json

RJvNextRoles.json

1. Note down the Object ID of the Azure Automation Account's Managed Identity in Account Settings > Identity

   

2. Open a PowerShell window.

3. Navigate to the folder containing the downloaded files

cd c:\temp\myfolder

1. Unblock scripts if necessary

2. 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 .\RJvNextPermissions.json

1. 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 .\RJvNextRoles.json

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

3

RealmJoin Runbook Configuration - Part 1

1. In RealmJoin Portal go to 'Settings -> Runbooks'.

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

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

   
4. Leave the wizard open for now. We will return shortly in part 2.

4

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.

1. Run the script copied previously in PowerShell.

   

2. Note down the values for appId and password. The App Registration "RealmJoin Runbook Management" will be created.

   

   App Registrations in Azure Portal

5

RealmJoin Runbook Configuration - Part 2

1. In RealmJoin Portal return to the open window/wizard for 'Settings -> Runbooks'

2. Fill in the missing values for appId and password created in the last step

3. Fill in the name of the Automation Account created previously

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

5. Choose the same location as your Azure Automation Account to make sure your runbooks are executed in the correct Azure region

Automation Account Connection in RealmJoin Portal

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