> For the complete documentation index, see [llms.txt](https://docs.realmjoin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmjoin.com/deployment/onboarding-realmjoin-portal/advanced-setup.md).

# Advanced Setup

The Advanced Setup allows you to assign permissions in a more granular and customized way. This approach is more flexible but more complex and requires running the RealmJoin PowerShell module.

The RealmJoin PowerShell module automates the setup of your RealmJoin tenant. It:

* Creates the required Microsoft Entra ID service principals for the RealmJoin applications
* Assigns the appropriate Microsoft Graph permissions based on the features you select
* Configures RealmJoin features (Portal, Intune LAPS, Autopilot, device actions, remediation scripts, security features)
* Cleans up legacy applications from previous configurations

The module is published on the [PowerShell Gallery](https://www.powershellgallery.com/packages/RealmJoin).

## Prerequisites

{% hint style="info" %}
The required Azure PowerShell modules (`Az.Accounts`, `Az.Resources`, `Az.Automation`) are installed automatically in the versions the module pins, for the current user, the first time you run a command.
{% endhint %}

* **PowerShell 5.1** or later (Windows PowerShell or PowerShell 7)
* An account that can **create service principals and grant application permissions** in Microsoft Entra ID — for example *Global Administrator* or *Privileged Role Administrator*
* Sign-in happens through `Connect-AzAccount`, which uses the **Azure PowerShell** first-party application. Tenants that restrict user consent may need an administrator to grant admin consent to that application first.
* Access to the [PowerShell Gallery](https://www.powershellgallery.com/packages/RealmJoin) to install the module

An Azure subscription is only needed for the Azure resources (`Set-RJLogAnalyticsWorkspace`, `Set-RJAutomationAccount`). `New-RJTenant` and `Update-RJTenant` work in a tenant without any subscription; sign in to it with `Connect-AzAccount -Tenant <tenant-id>` first.

## Recommended Setup

The setup command displayed by the RealmJoin Portal runs `Complete-RJTenantOnboarding` (alias of `Update-RJTenant`) without a feature selection. It assigns the permissions of the mandatory feature and all default features:

* Core portal functionality (`RealmJoinPortal`, mandatory)
* Intune LAPS (`IntuneLAPS`)
* Sign-in data (`ShowSignin`)
* Autopilot (`Autopilot`)
* Intune device actions (`DeviceIntuneActions`)
* Remediation scripts (`DeviceHealthScript`)
* BitLocker recovery keys (`BitLockerRecoveryKeys`)
* Windows device update enrollment (`WindowsDeviceUpdateEnrollment`)

Features that are already configured in the tenant, for example `SecurityFeatures` or `Client`, are kept. To add all features or individual features, see [Other Commands](#other-commands).

{% stepper %}
{% step %}

#### Open PowerShell on Windows/Mac

We recommend installing and running the RealmJoin PowerShell module in a **freshly opened** PowerShell session on your own device rather than in Azure Cloud Shell. The module requires a fixed minor version line of each `Az.*` module (`Az.Accounts` 5.5.x, `Az.Resources` 10.2.x, `Az.Automation` 1.12.x); if a different version is already loaded in the session — which is typically the case in Cloud Shell — it stops with a version conflict that cannot be resolved without opening a new session.

An elevated ("Run as administrator") session is not required: modules are installed with `-Scope CurrentUser`.
{% endstep %}

{% step %}

#### Copy and Run the RealmJoin Onboarding Script

The script will prompt you to sign in to Azure. Use an account that can create service principals and grant application permissions, for example your Global Administrator.

The token in the command links the run to your tenant in the RealmJoin Portal. It is valid for one hour; if it has expired, open the Advanced Setup page in the portal again to get a command with a new token.

```powershell
Install-Module -Force -Name RealmJoin
Complete-RJTenantOnboarding -Token 1234ABCD 6>&1
```

{% hint style="info" %}
**About `6>&1`:** These commands write their progress updates to PowerShell's Information stream. The `6>&1` redirection displays that output in the console — without it you won't see the detailed progress messages during execution.
{% endhint %}

<figure><img src="https://2868468309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2FdxYM2mTZ5LNcJhgudknf%2FSnipaste_2026-01-27_12-00-54.png?alt=media&amp;token=1fa4cd4e-485a-43e4-8a90-f6e6f6f57cb5" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Begin using RealmJoin

After the permissions have been assigned, the command sends the token to the RealmJoin API. The Advanced Setup page in the portal checks periodically whether the token has been used and then redirects you to the portal. Keep the page open while the command runs.

If the RealmJoin Portal service principal did not exist in the tenant before, the command also opens the RealmJoin Portal in your browser.

{% hint style="info" %}
**Signing out afterwards:** the Azure sign-in stays active after the command has finished. Once you are done, run `Disconnect-AzAccount` to sign out of the existing session.
{% endhint %}
{% endstep %}
{% endstepper %}

## Other Commands

### Interactive Setup

For a guided, menu-driven experience covering tenant setup, configuration changes, the Log Analytics workspace and the Automation Account:

```powershell
Show-RJInteractiveSetup
```

To review the available features before configuring anything:

```powershell
Show-RJFeatureInfo
```

### Custom Configuration

`New-RJTenant` configures a tenant with exactly the selected features. Use it for tenants that are not configured yet.

{% hint style="warning" %}
On a tenant that is already configured, `New-RJTenant` removes the permissions of every configured feature that is not part of the selection and deletes service principals that are left without permissions. For example, `New-RJTenant` without parameters removes `SecurityFeatures` and `Client`. To change an existing configuration, use [`Update-RJTenant`](#updating-existing-configuration).
{% endhint %}

#### Default Features

Enables the mandatory core portal functionality plus the default optional features (all except `Client`, `SecurityFeatures` and `AndroidApps`):

```powershell
New-RJTenant 6>&1
```

#### Minimal Features (only mandatory features)

```powershell
New-RJTenant -Features @('RealmJoinPortal') 6>&1
```

#### Full Feature Set

```powershell
New-RJTenant -All 6>&1
```

#### Read-Only Permissions

Assigns read-only permissions where available (for example, `Group.ReadWrite.All` becomes `Group.Read.All`):

```powershell
New-RJTenant -ReadOnly 6>&1
```

Three features have no read-only variant and keep their permissions with `-ReadOnly`:

| Feature                         | Permission                                                |
| ------------------------------- | --------------------------------------------------------- |
| `DeviceIntuneActions`           | `DeviceManagementManagedDevices.PrivilegedOperations.All` |
| `WindowsDeviceUpdateEnrollment` | `WindowsUpdates.ReadWrite.All`                            |
| `AndroidApps`                   | `DeviceManagementConfiguration.ReadWrite.All`             |

For a configuration without write permissions, leave these features out:

```powershell
New-RJTenant -Features @('IntuneLAPS', 'ShowSignin', 'Autopilot', 'DeviceHealthScript', 'BitLockerRecoveryKeys') -ReadOnly 6>&1
```

#### Custom Feature Selection

```powershell
New-RJTenant -Features @('RealmJoinPortal', 'IntuneLAPS', 'Autopilot') 6>&1
```

### Updating Existing Configuration

`Update-RJTenant` adjusts an already-configured tenant. The alias `Complete-RJTenantOnboarding` can be used interchangeably with `Update-RJTenant`.

* Without `-Features`, `-All`, `-AddFeatures` or `-RemoveFeatures`, the features already configured in the tenant are kept and the default features are added. Nothing is removed.
* `-Features` replaces the configuration: configured features that are not in the list are removed, including their service principal. An empty list is rejected.
* `-AddFeatures` and `-RemoveFeatures` change only the named features.
* Every run also removes legacy RealmJoin applications from the tenant, see [Switching from Quick Setup](#switching-from-quick-setup).

#### Add New Features

```powershell
Update-RJTenant -AddFeatures @('SecurityFeatures') 6>&1
```

#### Remove Features

```powershell
Update-RJTenant -RemoveFeatures @('ShowSignin') 6>&1
```

#### Switch to Read-Only Permissions

Switches the configured features and the default features to their read-only permissions. The features listed under [Read-Only Permissions](#read-only-permissions) keep their write permissions.

```powershell
Update-RJTenant -ReadOnly 6>&1
```

Combined with `-AddFeatures`, `-ReadOnly` applies only to the added features; the permissions of the features already configured stay unchanged.

#### Preview Changes

```powershell
Update-RJTenant -AddFeatures @('SecurityFeatures') -WhatIf 6>&1
```

### Azure Resources

The module also deploys the companion Azure resources RealmJoin uses. These are not Graph permission features and are not selected with `-Features`:

* `Set-RJLogAnalyticsWorkspace` — deploys the Log Analytics workspace with its custom tables and Data Collection Rules, see [Connecting Azure Log Analytics Workspace](https://docs.realmjoin.com/monitoring-and-logs/log-analytics.md)
* `Set-RJAutomationAccount` — deploys the RealmJoin Automation Account with a managed identity and the permissions it needs, see [Connecting Azure Automation](https://docs.realmjoin.com/automation/connecting-azure-automation.md)

Both commands are generated with the matching parameters and an onboarding token on the relevant settings page in the RealmJoin Portal.

## Available Features

Use these feature names with the `-Features`, `-AddFeatures`, and `-RemoveFeatures` parameters. Mandatory features are always enabled. The default configuration (`New-RJTenant` without parameters) enables the features marked below; **SecurityFeatures**, **Client** and **AndroidApps** have to be selected explicitly.

| Feature                         | Description                                                                                                                                                                                          | Default |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-----: |
| `RealmJoinPortal`               | Core portal functionality for user self-service and admin interaction (mandatory)                                                                                                                    |    ☑️   |
| `IntuneLAPS`                    | Retrieve and manage local admin passwords via Intune LAPS                                                                                                                                            |    ☑️   |
| `ShowSignin`                    | Display user sign-in history and audit logs                                                                                                                                                          |    ☑️   |
| `Autopilot`                     | View Windows Autopilot deployment profiles and status                                                                                                                                                |    ☑️   |
| `DeviceIntuneActions`           | Execute privileged device actions (sync, restart, wipe, etc.)                                                                                                                                        |    ☑️   |
| `DeviceHealthScript`            | Manage and deploy PowerShell remediation scripts to devices                                                                                                                                          |    ☑️   |
| `BitLockerRecoveryKeys`         | View BitLocker recovery keys for managed devices                                                                                                                                                     |    ☑️   |
| `WindowsDeviceUpdateEnrollment` | Manage Windows Device Updates enrollment                                                                                                                                                             |    ☑️   |
| `SecurityFeatures`              | [Defender for Endpoint integration](https://docs.realmjoin.com/ugd-management/defender-integration.md) on device pages (requires MDE licenses)                                                       |         |
| `Client`                        | RealmJoin Agent — client application for device management                                                                                                                                           |         |
| `AndroidApps`                   | [Android app deployment](https://docs.realmjoin.com/application-management/packages/android-apps-managed-google-play.md) through Managed Google Play (`DeviceManagementConfiguration.ReadWrite.All`) |         |

## Switching from Quick Setup

A tenant onboarded with Quick Setup uses the **RealmJoin Portal - Core Features** app registration, which holds all portal permissions. To move it to Advanced Setup, go to **Organization → Features** in the RealmJoin Portal and select **Go to advanced mode** on the **Advanced setup** card. The portal then shows the onboarding command with a token, as described under [Recommended Setup](#recommended-setup).

<figure><img src="https://2868468309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fgit-blob-90feb65a312dda59e5e23473be499c34566c8b1c%2Forganization-features-advanced-setup-switch.png?alt=media" alt="Advanced setup card on the Organization Features page"><figcaption><p>Advanced setup card for tenants on Quick Setup</p></figcaption></figure>

When the command runs, the module creates the service principals for the selected features and removes the **RealmJoin Portal - Core Features** app registration as a legacy application. Once the new permissions are in place, the portal switches the tenant to Advanced Setup.

{% hint style="warning" %}
The switch is one-way. After the Core Features app registration has been removed, permissions are managed with the RealmJoin PowerShell module only.
{% endhint %}

## Troubleshooting

{% hint style="warning" %}
**"Insufficient privileges"** — creating service principals and granting application permissions requires an appropriately privileged account, for example *Global Administrator* or *Privileged Role Administrator*. See [Prerequisites](#prerequisites).
{% endhint %}

{% hint style="warning" %}
**"Need admin approval" or a consent error during sign-in** — sign-in uses the **Azure PowerShell** first-party application. If your tenant restricts user consent, an administrator has to grant admin consent to that application once.
{% endhint %}

{% hint style="warning" %}
**"RealmJoin module is outdated - execution cannot proceed"** — every command verifies once per session that you are running the latest published version. Install the current version, then close the session and open a new one:

```powershell
Install-Module -Name RealmJoin -Force -Scope CurrentUser
```

{% endhint %}

{% hint style="warning" %}
**"Authentication failed (401). The token may be invalid or expired."** — the permissions have been assigned, but the tenant could not be registered with RealmJoin because the onboarding token has expired (after one hour) or is invalid. Open the Advanced Setup page in the RealmJoin Portal again and run the command with the new token. Running it again does not change permissions that are already in place.
{% endhint %}

{% hint style="warning" %}
**A module version conflict is reported** — an `Az.*` module in a version other than the one the module pins is already loaded. This cannot be fixed in the running session: close PowerShell, open a new session and run the command again.
{% endhint %}

If the module cannot be found, confirm the PowerShell Gallery is available and reinstall:

```powershell
Get-PSRepository
Install-Module -Name RealmJoin -Force -Scope CurrentUser
```

### Getting Help

```powershell
Get-Help New-RJTenant -Full
Get-Help Update-RJTenant -Examples
Get-Help Show-RJInteractiveSetup -Detailed
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.realmjoin.com/deployment/onboarding-realmjoin-portal/advanced-setup.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
