> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neoagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Hybrid AD User Onboarding

> Set up Neo to onboard users in on-prem Active Directory and sync them to Microsoft 365

## Overview

Use this recipe when new users are created in on-prem Active Directory and then synced to Microsoft 365 through Azure AD Connect.

In a hybrid identity environment, Neo creates or updates the user in Active Directory, then triggers an Azure AD Connect sync so the change appears in Entra ID and Microsoft 365.

<Info>
  If users are created directly in Entra ID, use the [cloud Microsoft 365 setup](/integrations/m365/cloud). If users only exist in local Active Directory and never sync to Microsoft 365, use [on-prem Active Directory setup](/integrations/m365/on-prem) without Hybrid.
</Info>

## When to use Hybrid

| Scenario                                                    | Company identity provider   |
| ----------------------------------------------------------- | --------------------------- |
| Users are created in on-prem AD and synced to Microsoft 365 | Hybrid                      |
| Both directories exist but AD Connect does NOT sync them    | Hybrid (no AD Connect sync) |
| Users are created only in Microsoft Entra ID                | Entra ID                    |
| Users are created only in local Active Directory            | On-prem AD                  |

<Warning>
  "Hybrid" assumes a working Azure AD Connect sync. If your AD Connect was decommissioned (or never existed) but you still maintain both directories, pick **"Hybrid (no AD Connect sync)"** instead — Neo will then create and manage users in **both** on-prem AD and Entra ID directly. With plain "Hybrid" and no working sync, the on-prem user is created but never reaches Microsoft 365, so licensing and mailbox steps can't proceed.
</Warning>

## Setup checklist

| Check                                 | What the MSP needs to do                                                                                                                                                        |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Company is configured as Hybrid       | Set **Identity Provider Type** to **Hybrid** in [Company Settings](/integrations/m365/on-prem#1-configure-company-settings)                                                     |
| Neo can run AD PowerShell             | Set the AD runner hostname, [upload the Neo wrapper script](/integrations/m365/on-prem#2-upload-the-neo-script-to-your-rmm), and run an RMM sync                                |
| Neo can trigger AD Connect sync       | Set the AD Connect server hostname and make sure the service account can trigger sync. Not needed for **Hybrid (no AD Connect sync)** — Neo writes to both directories directly |
| Optional license buying is configured | If the agent should buy Microsoft licenses, connect a [license marketplace integration](/integrations/marketplaces/intro) and add the company's marketplace ID                  |

## Configure the company

Go to **Companies** in Neo and open the end-client company.

Set:

* **Identity Provider Type:** Hybrid
* **AD Runner Hostname:** the RMM device Neo should use to run Active Directory commands
* **AD Connect Server Hostname:** the server running Azure AD Connect
* **AD Service Account Username / Password:** only if the runner needs a dedicated domain service account

<Note>
  Hostnames must match the device names discovered from your RMM. See the [on-prem setup guide](/integrations/m365/on-prem#1-configure-company-settings) for field details.
</Note>

## Configure the RMM path

Neo runs on-prem Active Directory commands through your RMM. Before using a hybrid onboarding agent:

<Steps>
  <Step title="Upload the wrapper script">
    Follow the [Neo wrapper script setup](/integrations/m365/on-prem#2-upload-the-neo-script-to-your-rmm) for your RMM.
  </Step>

  <Step title="Sync RMM devices and scripts">
    After uploading the script, run an RMM sync in Neo so the script and devices are discoverable.
  </Step>

  <Step title="Confirm the runner machine">
    If Neo should run AD commands from a runner instead of directly on the domain controller, follow the [runner machine setup](/integrations/m365/on-prem#3-set-up-a-runner-machine).
  </Step>

  <Step title="Verify connectivity">
    Run the checks in [Verify Connectivity](/integrations/m365/on-prem#6-verify-connectivity) before running the agent live.
  </Step>
</Steps>

## Configure the onboarding agent

Create or edit an [Onboard/Offboard M365 User](/building-automations/actions/ai/onboard-offboard-m365-user) agent or workflow.

On the agent's **Integrations** tab, use a Microsoft 365 access profile that allows the onboarding work you want Neo to perform. For hybrid onboarding, the key requirement is that Neo can make the on-prem AD change and trigger Azure AD Connect sync.

If the agent also needs to create or manage mailboxes through on-prem Exchange, see [Exchange Hybrid setup](/integrations/m365/on-prem#exchange-hybrid).

<Tip>
  Start with [Technician-in-the-Loop](/core/technician-in-the-loop) enabled for write actions. Once the workflow is proven, reduce approval steps where appropriate.
</Tip>

## Common errors

| Error                                                       | Meaning                                                                                  | Action                                                                                                                                                                  |
| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AD Connect sync is only available for hybrid environments` | The agent tried to sync AD changes, but the company is configured as On-prem AD          | Set the company Identity Provider Type to **Hybrid**, or remove AD Connect sync from the agent if the company is truly on-prem-only                                     |
| `...no AD Connect sync to trigger`                          | The company is set to **Hybrid (no AD Connect sync)**, where directories are independent | Usually nothing — Neo manages both directories directly in this mode. If the company actually has a working AD Connect, change its Identity Provider Type to **Hybrid** |
| `Neo wrapper script not found in RMM`                       | Neo cannot run PowerShell through the RMM                                                | [Upload the Neo wrapper script](/integrations/m365/on-prem#2-upload-the-neo-script-to-your-rmm), then run an RMM sync                                                   |
| `Target server not found in RMM`                            | The configured runner hostname does not match an RMM device                              | Update the hostname in [Company Settings](/integrations/m365/on-prem#1-configure-company-settings) or sync RMM devices                                                  |
| `No license marketplace integration is configured`          | Neo cannot buy licenses automatically                                                    | Connect a [license marketplace integration](/integrations/marketplaces/intro)                                                                                           |
| `Marketplace company ID is not set`                         | Neo knows the marketplace, but not this company's marketplace ID                         | Add the company's marketplace company ID in Companies                                                                                                                   |

## Before running live

<Steps>
  <Step title="Confirm company identity mode">
    The company should be set to **Hybrid** if Neo needs to trigger Azure AD Connect sync.
  </Step>

  <Step title="Confirm RMM script execution">
    The Neo wrapper script should be uploaded and visible after RMM sync.
  </Step>

  <Step title="Confirm AD Connect access">
    The service account should be able to trigger sync on the AD Connect server.
  </Step>

  <Step title="Run with approval first">
    Use Technician-in-the-Loop approval for the first few onboarding runs.
  </Step>
</Steps>