# Connecting Azure Automation

## Overview

{% embed url="<https://www.youtube.com/watch?v=Ijp9XnE8UuA>" %}

To enable RealmJoin Portal to deliver [runbooks ](https://docs.realmjoin.com/automation/runbooks)for automating daily tasks, you must connect an [Azure Automation](https://learn.microsoft.com/en-us/azure/automation/overview) Account. This Automation Account will act as the host for your runbooks and provide the [permissions](https://docs.realmjoin.com/automation/connecting-azure-automation/azure-ad-roles-and-permissions) required for the runbooks to function within your environment.

## Considerations&#x20;

The Automation Account's [Managed Identity](https://learn.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/overview) requires extensive [permissions ](https://docs.realmjoin.com/automation/connecting-azure-automation/azure-ad-roles-and-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](https://github.com/realmjoin/realmjoin-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](https://learn.microsoft.com/en-us/powershell/azure/?view=azps-15.3.0) module or [AZ CLI](https://learn.microsoft.com/en-us/cli/azure/?view=azure-cli-latest)
* Contributor permissions on an Azure subscription
* [Runbook requirements](https://docs.realmjoin.com/automation/connecting-azure-automation/azure-ad-roles-and-permissions)

## Instructions

{% stepper %}
{% step %}

### Create an Azure Automation Account

1. Navigate to your [Azure Portal > Automation Accounts](https://portal.azure.com/#create/Microsoft.AutomationAccount)&#x20;
2. Create a new Automation Account
3. In the Basics tab, choose your desired Subscription, Resource Group, Automation Account Name and Region<br>

   <figure><img src="https://2868468309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2FqjBLc2zH3XCCqfAViEsU%2Fimage.png?alt=media&#x26;token=257816e0-eb8a-478c-973f-fb288324d8c8" alt=""><figcaption></figcaption></figure>

{% hint style="success" %}
A separate Resource Group for your Automation Account is recommended
{% endhint %}

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

   <figure><img src="https://2868468309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2F6EYSjUouHCtzNE99DYM8%2Fimage.png?alt=media&#x26;token=000d1f85-9ed0-458f-ae68-48b94f2dbf15" alt=""><figcaption></figcaption></figure>

5. Select Review + Create and create your Automation Account

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

7. In the IAM tab, assign the Azure Automation Account as a Contributor
   {% endstep %}

{% step %}

### 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](https://docs.realmjoin.com/automation/connecting-azure-automation/azure-ad-roles-and-permissions) section and adjusted as needed in the JSON files.

{% tabs %}
{% tab title="GrantAppPermToEntApp.ps1" %}
{% @github-files/github-code-block url="<https://github.com/Workplace-Foundation/approle-and-directoryrole-granter/blob/main/GrantAppPermToEntApp.ps1>" %}
{% endtab %}

{% tab title="AssignAzureADRoleToEntApp.ps1" %}
{% @github-files/github-code-block url="<https://github.com/Workplace-Foundation/approle-and-directoryrole-granter/blob/main/AssignAzureADRoleToEntApp.ps1>" %}
{% endtab %}

{% tab title="RJvNextPermissions.json" %}
{% @github-files/github-code-block url="<https://github.com/Workplace-Foundation/approle-and-directoryrole-granter/blob/main/RealmJoinVnext/RJvNextPermissions.json>" %}
{% endtab %}

{% tab title="RJvNextRoles.json" %}
{% @github-files/github-code-block url="<https://github.com/Workplace-Foundation/approle-and-directoryrole-granter/blob/main/RealmJoinVnext/RJvNextRoles.json>" %}
{% endtab %}
{% endtabs %}

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

   <figure><img src="https://2868468309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2F4ecZSM3NW9PWJJlaNmR4%2Fimage.png?alt=media&#x26;token=e5d5b56b-50f3-4f35-a41b-7cb4230dd3f3" alt=""><figcaption></figcaption></figure>

3. Open a PowerShell window.

4. Navigate to the folder containing the downloaded files

```
cd c:\temp\myfolder
```

5. Unblock scripts if necessary\
   ![](https://2868468309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2F2N1nXyV1f6allriXQ9Pb%2Fimage.png?alt=media\&token=e6009cd7-ec76-4af5-aa5c-037a92f958c7)
6. 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
```

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

8. The Azure Automation Account should now have the correct permissions to execute Runbooks<br>
   {% endstep %}

{% step %}

### RealmJoin Runbook Configuration - Part 1

1. In RealmJoin Portal go to '[Settings -> Runbooks](https://portal.realmjoin.com/settings/runbooks-configuration)'.<br>

   <figure><img src="https://2868468309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2FsSQHQwy9pChGMyTtidTt%2Fimage.png?alt=media&#x26;token=7bcec1d0-fb94-4591-8012-011a62295674" alt=""><figcaption></figcaption></figure>
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](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Overview)

   <figure><img src="https://2868468309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2F3MElTpxbL7jloR1y4i9U%2Fimage.png?alt=media&#x26;token=1b83cda8-7909-4739-a36d-7848c5d4f113" alt=""><figcaption></figcaption></figure>
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.<br>

   <figure><img src="https://2868468309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2FRoVmXCq53pQRPOdQQetg%2Fimage.png?alt=media&#x26;token=b53c79c3-cbac-4666-ad81-6d77ade1ad86" alt=""><figcaption></figcaption></figure>
4. Leave the wizard open for now. We will return shortly in part 2.
   {% endstep %}

{% step %}

### Granting Access for RealmJoin to Azure Automation

{% hint style="info" %}
You can use [Azure CloudShell](https://docs.microsoft.com/en-us/azure/cloud-shell/overview), so you don't need to install and authenticate a local copy of AZ CLI.
{% endhint %}

1. Run the script copied previously in PowerShell.

   <figure><img src="https://2868468309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2FylKg4jH8YJ6Cfeh6xF4z%2Fimage.png?alt=media&#x26;token=bdc3a594-0348-44f4-86be-de172247de67" alt=""><figcaption></figcaption></figure>

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

   ![App Registrations in Azure Portal](https://2868468309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2FAfaE2Y9DISjOLNwwLnfs%2Fimage.png?alt=media\&token=8f0a83c6-34b0-4b82-87eb-279597cfc961)
   {% endstep %}

{% step %}

### RealmJoin Runbook Configuration - Part 2

1. In RealmJoin Portal return to the open window/wizard for '[Settings -> Runbooks](https://portal.realmjoin.com/settings/runbooks-configuration)'
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](#create-an-azure-automation-account)
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](https://docs.microsoft.com/en-us/azure/availability-zones/az-overview)

![Automation Account Connection in RealmJoin Portal](https://2868468309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2FA0X3M2c9d13pxVt87Pf8%2Fimage.png?alt=media\&token=8e2f2b18-c3b1-4704-8cc8-eb4d43297dd1)

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

![](https://2868468309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fjro6ZW5ITGp9UbnCiD08%2Fimage.png?alt=media\&token=3bf1d1e8-a1ce-4528-99a5-686c0377e8b5)
{% endstep %}
{% endstepper %}