Migrate from Microsoft 365 Copilot to Onyx: what the move involves
A renewal, a licensing change or a residency requirement is pushing many organizations to re-examine Microsoft 365 Copilot, which answers questions by grounding them in content that the user's Microsoft Entra account can reach through Microsoft Graph. Moving to Onyx is a re-platforming of search, identity and models, not a bulk export of prompts and files. The company documents, mailboxes and sites stay where they are. What changes is the layer that finds, permissions and answers questions over them. The work is usually run by a platform engineering team with security and Microsoft 365 administrators, because the hard decisions sit with identity, source permissions and the model endpoint rather than with the chat screen.
In Onyx, the Graph grounding that Copilot relies on is replaced by connectors. Onyx's connectors for SharePoint, OneDrive, Outlook and Microsoft Teams index content into the platform's own document index, and Onyx syncs source permissions so that answers only draw on documents each user can already see in the source application. Your team needs to confirm how each connector authenticates to Microsoft 365, which app registration and API permissions it requires, how often sync runs, and how deleted or re-permissioned items are handled. Sign-in is a separate workstream: Onyx supports OIDC and SAML for Entra ID sign-in and SCIM for user provisioning, so the identity configuration and the group mapping that drives role-based access should be designed before any users are onboarded.
Effort and risk are driven mostly by three choices: the model endpoint, the size of the index, and how long you run both systems side by side. Model hosting can be self-hosted with Ollama, LiteLLM or vLLM, or a proprietary API, and each option moves inference cost and data handling in a different direction. Run both assistants in parallel with a pilot group, compare answers and permission behavior against Copilot for the same questions, and keep Copilot licenses active until the permission tests pass. Ask any implementation partner for a written scope that names the connectors, identity settings, model hosting, test cases and cutover criteria, since those define the effort more than the platform does.
Which Copilot capabilities map to Onyx, and which need rework
This table maps each Copilot capability to its Onyx equivalent and marks it as clean, needs rework or gap. Clean means the documented Onyx capability covers the need with standard setup. Needs rework means the capability exists but requires connector design, identity configuration or an Enterprise Edition decision. Gap means no documented Onyx capability covers it, so confirm with the vendor before you plan the migration.
| Copilot capability | Onyx equivalent | Status |
|---|---|---|
| SharePoint and OneDrive grounding | SharePoint and OneDrive connectors index content and sync source permissions, so answers only use files the user can open | Needs rework |
| Outlook mail grounding | Outlook connector in the repository; confirm mailbox scope, calendar coverage and attachment handling | Needs rework |
| Teams chats, channels and meetings | Teams connector in the repository; confirm which chat, channel and meeting content it indexes | Needs rework |
| Entra ID sign-in | Sign-in through OIDC or SAML; confirm the Entra app registration, redirect settings and group claims | Clean |
| User provisioning and offboarding | SCIM provisioning is listed as an enterprise feature; test how removed users lose access to indexed content | Needs rework |
| Admin controls and role management | Role-based access control is part of the Enterprise Edition; confirm what Community Edition admins can manage | Needs rework |
| Model choice | Ollama, LiteLLM and vLLM for self-hosted models, plus Anthropic, OpenAI and Gemini providers | Clean |
| Audit and query history | Query history auditing is listed as an enterprise feature; confirm export format and retention against your records policy | Gap |
| In-app drafting in Word and Outlook | No supplied Onyx capability for in-app Office drafting; confirm with the vendor before scoping | Gap |
What data and identities move, and which integrations to rebuild
Migration splits into four separate workstreams: the document corpus, the identities that read it, the conversation history, and the custom prompts and workflows built on Copilot. Each one has its own owner, check and exit criteria, so none of them should be assumed to follow automatically from the others.
Source connectors for Microsoft 365 content
Onyx ships connectors for SharePoint, OneDrive, Outlook and Microsoft Teams, which is how it replaces Copilot's Graph grounding. Confirm each connector's scope against the sites, libraries, mailboxes and channels you intend to index, and test with a pilot group before a tenant-wide crawl. Check how deleted or moved items are reflected in the index, because stale copies are a common source of wrong answers.
Permission sync per source
Onyx syncs source permissions so answers only draw on documents a user can already see in the originating application. Treat this as a per-source verification task, not a global setting: run test accounts with known access in SharePoint, OneDrive, Outlook and Teams, and confirm that restricted content never appears in answers. Repeat the test after group membership changes and after a permission sync has run.
Entra ID sign-in and user provisioning
Onyx supports SSO through OIDC or SAML, along with SCIM user provisioning, so Entra ID can govern who signs in and who is removed. Decide which Entra groups map to Onyx roles before cutover, and confirm how deprovisioning reaches existing sessions and indexed content. Your identity team should own the app registration and the attribute mapping.
Copilot conversation history is not a corpus
Prompts and responses from Copilot are not a document set to import into Onyx. If legal or records teams need them, they can be retrieved through Microsoft's documented eDiscovery export paths, which are separate from the migration project and carry their own approval. Decide early whether any history must be kept, and who authorizes that retrieval, rather than discovering the requirement at license end.
Custom prompts, agents and workflows
Copilot prompts, agents, plugins and any workflow that depends on Graph grounding must be rebuilt as separate work in Onyx or another platform. Inventory each one, record the data it reads and the users it serves, and rebuild it against the new connectors. Budget this as its own line item, because it does not come across with the document index.
Parallel running and cutover checks
Run Copilot and Onyx side by side for a defined group of users before licenses lapse, comparing answers on the same questions and checking that access matches. Record discrepancies in permission behavior, freshness and missing sources as go or no-go criteria. Keep the Copilot license until these checks pass and your retention obligations for Copilot data are confirmed.
Migration sequence from inventory to Copilot decommission
This sequence moves users from Copilot to Onyx in controlled stages, so permissions are proven on real sources before any group loses access. Each stage produces a written record that justifies the next one. License decommission happens only after the parallel run has been validated.
Inventory sources, users and licenses
Build a register of every content source Copilot currently reaches through Microsoft Graph, including SharePoint sites, OneDrive, Exchange mailboxes, Teams channels and any non-Microsoft systems your staff search today. List user groups, their Copilot license assignments and the renewal or lapse dates shown in your Microsoft 365 admin center. The IT lead and a records or compliance owner should sign off on this source-to-permission register, which records for each source who owns it and which group is allowed to read it. The step is done when every source has an owner and every license has a named group.
Stand up Onyx with Entra ID sign-in
Deploy Onyx in your own infrastructure using the Docker, Kubernetes or Helm option that matches your platform team's standards, and connect it to Entra ID through OIDC or SAML. Confirm which Onyx edition provides the SSO, SCIM provisioning and role-based access controls you need, because the README lists these among enterprise features. Your identity team should test that group membership maps to the Onyx roles you defined. The step is done when a test user from each group signs in and sees only the roles they were assigned.
Connect a pilot source set and test permissions
Choose a small set of sources from the register, such as one SharePoint site, one OneDrive account and one Teams channel, and connect them using the Onyx connectors for those systems. Onyx syncs source permissions so that answers draw only on documents the user can already open in the source application. Test the boundary with deliberately restricted documents, using accounts from different groups and a document that a user has no access to. Record each test, the expected result and the actual result in a pilot acceptance record. The step is done when every restricted test returns no content the account could not open in the source.
Choose models and confirm the inference path
Select the model providers Onyx will call, either a hosted provider or a self-hosted model served through Ollama, LiteLLM or vLLM. Confirm with your security and data protection leads where prompts and retrieved content are processed, and whether any gateway in front of the models keeps logs. Document the decision, the model versions in use and the data flows in a model and data-flow record. If you run vLLM, review its security documentation before exposing any endpoint to users. The step is done when the record is approved and the data-flow diagram matches the actual configuration.
Run both tools in parallel for one group
Enable Onyx for a single pilot group while its members keep Copilot. Ask the group to run the same representative questions in both tools and to log where answers differ in accuracy, source coverage or permission behavior. Collect feedback on connectors that are missing or stale, and on the sources that are not yet connected. The owner of the parallel run should review the comparison log weekly, and the group should agree on the criteria that define a successful result before the run starts. The step is done when the group's comparison log shows that the agreed criteria were met or that the gaps have a fix and an owner.
Cut over by group with a rollback path
Move the remaining groups in stages, each with its own cutover runbook that lists the connectors to enable, the users to onboard, the communication to send and the steps to restore Copilot access if needed. Keep Copilot licenses active for each group until its cutover is accepted, so that a rollback does not depend on a new purchase. Confirm which admin actions reverse a group's assignment and who has authority to trigger the rollback. The step is done when each group has signed off on its runbook and no group is left without a working tool.
Validate and decommission Copilot licenses
Once all groups have run on Onyx through an agreed validation period, confirm that audit and query history, backup and restore, and access reviews work as your policies require. Export or retain any Copilot records your records policy requires before removing assignments, and confirm that the Microsoft Learn licensing terms for your tenant match what you plan to remove. Unassign licenses in the Microsoft 365 admin center, update the source-to-permission register and close the migration with a decommission record. The step is done when the decommission record is signed by the owner and the license count matches the approved plan.
How Onyx replaces Graph grounding with permission-synced indexes
Onyx replaces Copilot's Graph grounding with its own index, and the key point for your review is that it copies permissions along with content. Onyx connects to more than 50 applications and syncs their permissions, so an answer only draws on documents the user can already see in the source system. Copilot relies on Microsoft Graph and the access model of each Microsoft 365 workload; with Onyx, you must confirm for each connector (SharePoint, OneDrive, Outlook, Microsoft Teams) that the permission sync covers the scopes you care about, such as unlisted sharing links, group membership changes and deleted users. Test this with a set of restricted documents and a test account before you widen access, and record the results as evidence for your access review.
Onyx Standard is the full stack: Postgres for application data, Vespa or OpenSearch as the document index, Redis, and model inference servers, plus background sync workers and object storage. Plan capacity for the index and sync workers first, since they grow with the volume of mail, files and chat you connect. Onyx Lite is the lighter option: a chat and agents deployment without a vector database or background workers, which suits a pilot or a small group, but it does not give you the same continuous sync of permissions and content, so confirm that gap against the current deployment docs before you choose it for production.
Models connect in two ways. Self-hosted models run through Ollama, LiteLLM or vLLM, which keeps prompts and retrieved content inside your network. Proprietary APIs such as OpenAI, Anthropic or Gemini are also supported, but each one sends retrieved context to a third party, so the decision belongs in your data handling review, not in the connector setup. A practical first step is to run a fixed set of business questions against both a self-hosted model and your current Copilot answers, then compare citations, permission behavior and latency before you pick the model that serves production.
How the migration differs by tenant size and starting point
When SharePoint is the main document store and most collaboration happens in Microsoft 365, the migration is mostly a connector and permissions exercise. Onyx's connector set covers SharePoint, OneDrive, Outlook and Teams, so the core scope maps closely to what Copilot grounds on today. The harder work is confirming that permissions sync reflects the real access model, because inherited site permissions, broken inheritance and group-based sharing are common sources of surprises.
- Connector scope: Decide which SharePoint sites, OneDrive accounts, Outlook mailboxes and Teams channels are in scope, and whether personal OneDrive content is indexed at all.
- Identity mapping: Plan how Entra ID users and groups map to Onyx users, and whether SCIM provisioning or the sign-in path needs to be configured before indexing starts.
- Permission fidelity: Test a sample of restricted sites and private channels to confirm that answers do not expose documents the user cannot open in the source.
- Effort drivers: Large numbers of sites, deep permission inheritance and heavy use of external sharing usually add the most verification time.
- Model choice: Decide whether inference runs through a proprietary API or self-hosted models, since that changes data flow and the operating burden.
Confirm the connector configuration, sync behavior and sign-in method against the current Onyx documentation and your own tenant before committing to a timeline.
Organizations that store content in Google Drive, Confluence or Jira alongside Microsoft 365 gain the most from Onyx's multi-source search, because Copilot grounds only on Microsoft Graph content. The migration then becomes a question of how many sources must return results in one answer and how each source's permissions are honored. Each additional connector adds configuration, credential management and permission testing, so scope should be decided source by source rather than assumed.
- Connector scope: List every non-Microsoft source that users rely on today, such as Google Drive, Confluence, Jira or Slack, and rank them by business importance.
- Identity mapping: Confirm how each source's user identities correspond to the Entra ID or other identity provider accounts used for sign-in, since mismatched emails and aliases break permission matching.
- Permission fidelity: Verify that each connector syncs permissions, including shared drives and Confluence spaces with restricted access, and document any source where sync is partial.
- Effort drivers: Credential setup per source, differing permission models and the volume of content in each system usually dominate the work.
- Retention and duplication: Check whether the same document exists in several systems, since duplicates can make answers look inconsistent.
Ask the implementation partner to document, for each source, which permissions are synced and which connector version was tested.
Organizations that built agents in Copilot Studio or use Microsoft Graph calls inside business workflows face a larger change than search alone. Onyx provides chat, search and agents with actions, but the custom agents and Graph-triggered logic built in Microsoft's tools do not transfer automatically. This starting point requires an inventory of each agent and workflow, a decision about which ones are worth rebuilding, and a plan for the systems they call.
- Connector scope: Inventory each Copilot Studio agent and Graph-based flow, noting its data sources, actions and users, then decide which need an Onyx connector and which need a separate workflow tool.
- Identity mapping: Agents that act with delegated or application permissions need a new authorization design in Onyx, and each action must respect the same user rights the original relied on.
- Action rebuild: Each external action must be rebuilt against the target system's API, which is usually the largest single effort item in this group.
- Effort drivers: The count of agents, the number of connected systems and whether agents write data rather than only read it drive the work.
- Parallel running: Keep original agents active until rebuilt equivalents match expected results.
Review each agent's permissions and actions with the security team before rebuilding, and confirm current Onyx agent capabilities in its documentation.
What drives the cost and duration of the move
This table lists each cost component of moving from Microsoft 365 Copilot to a self-hosted Onyx stack, who is paid for it, whether it is one-time or recurring, and what pushes it up or down. Read it as a checklist for a written scope and quote, since no prices or durations are estimated here. The main takeaway is that the Copilot license is only one line, and the connector scope, permission complexity and model hosting choice usually decide the rest.
| Cost component | Who is paid or what it is | One-time or recurring | What drives it and how to keep it down |
|---|---|---|---|
| Copilot add-on licenses | Microsoft, per eligible user under your agreement | Recurring until removed from the tenant | Ask Microsoft or your reseller for the end date of each term. Run a pilot group on Onyx and remove licenses in waves rather than all at once. |
| Parallel-run overlap | Your staff and the implementation team, plus duplicate licenses during the overlap | Recurring for the length of the overlap | Plan the overlap around your renewal date. Shorten it by agreeing success criteria for permissions and answer quality before the cutover. |
| Inference on GPUs or APIs | GPU capacity you buy or rent, or token charges to a model provider | Recurring, usage or capacity based | Query volume, model size and context length drive it. Route simple queries to smaller models and confirm residency terms before choosing a provider. |
| vLLM operations | Your platform team, GPU or accelerator hosts, and the implementation work to deploy them | Setup is one-time, operations are recurring | The vLLM project has no paid edition, so cost sits in hardware and people. Multi-node runs need an isolated network, and the docs say inter-node traffic is unauthenticated by default. |
| LiteLLM gateway with PostgreSQL and Redis | Your team for hosting, plus the cost of PostgreSQL and Redis 7.0 or newer when more than one proxy runs | Recurring infrastructure and maintenance | Per-key budgets and rate limits need PostgreSQL. Reduce cost by standardizing on one gateway for all models rather than wiring each application separately. |
| Onyx Enterprise features | Onyx for the Enterprise Edition license if RBAC or SCIM is required | Recurring license under the Enterprise License | Community Edition covers RAG, chat and agents. Decide early whether SCIM provisioning and RBAC are required for your Entra ID groups, because they set the license scope. |
| Connector setup for SharePoint, OneDrive, Outlook and Teams | Implementation team and your Microsoft 365 administrators for app registrations and consent | One-time per source, with ongoing sync maintenance | Each source, site collection and mailbox group adds work. Start with the sources that hold most of your daily search traffic and expand in phases. |
| Permission mapping and validation | Implementation team with your security and identity owners | One-time, with reviews after changes | Broken inheritance, unique permissions, shared mailboxes and nested groups make this the largest effort driver. Test with sample users who hold different access levels before go-live. |
| Identity integration with Entra ID | Implementation team and your identity administrators | One-time, with ongoing group changes | OIDC or SAML setup is simple for a single tenant, but group-based roles and SCIM add review. Confirm which claims and groups your Entra ID tenant issues. |
| Residency and hosting location | Your cloud account, data center or on-premises hardware | Recurring hosting cost | Keeping indexes, prompts and logs in a region you choose can require a different GPU or hosting footprint. Confirm the location of each component in writing before sizing. |
What usually goes wrong and how to prevent it
Most failed migrations from Copilot to a self-hosted assistant do not fail on the model. They fail on access rules, network exposure and the people who were never told which tool to open. The cards below name the failure, the prevention step and what to check before users depend on the new stack.
Permission drift between source and index
Onyx answers only from documents a user can see in the source application, but that depends on permission sync running and staying current. If a SharePoint site is re-shared or a Teams channel membership changes and the index lags, answers can reflect access that no longer applies. Test with a sample of restricted users and documents after every connector change, and confirm how often permissions refresh. Also confirm which connectors sync permissions and which only index content. Run a permission test before each pilot wave.
Entra ID group changes break sign-in
Onyx supports SSO through OIDC or SAML, and SCIM user provisioning is listed as an enterprise feature. When Entra ID groups are renamed, nested or moved, role mappings in Onyx can silently grant or remove access. Map roles to stable group object IDs rather than display names, and document which group controls each Onyx role. Confirm with your identity team how deprovisioned users are removed from the index and sessions, not only from the login screen.
vLLM endpoint exposed without an allowlist
The vLLM --api-key option covers /v1 routes but not /metrics, /health or several control endpoints, and the vLLM security docs warn against relying on it alone. Place a reverse proxy in front of the model server that forwards only the endpoints Onyx needs, and block the rest at the network layer. Verify from outside the cluster that /metrics and control routes are unreachable. Never expose the model server port directly to users.
Unprotected traffic between inference nodes
vLLM's documentation states that communication between nodes in a multi-node deployment is insecure by default, with no authorization or encryption. If the model is split across machines with tensor or pipeline parallelism, that traffic must stay on an isolated network segment. Ask your platform team to confirm the node network is not routable from user subnets, and record that check as evidence for your security review.
Users not told which tool to use
During the parallel run, staff may open Copilot in Word or Outlook for one task and Onyx for another, and compare answers that were grounded differently. Publish a short guide that states which tool covers which tasks, which sources each one can see, and where to report wrong or missing answers. Keep the guide current as connectors are added. Without it, pilot feedback will mix tool quality with user confusion.
Treating Copilot licenses as one renewal date
Copilot add-on licenses are assigned per user and may not all end on the same date, especially when some departments were added later or moved between plans. Build an inventory of assigned licenses and their renewal dates, then set a cut-over date per group rather than per company. Keep a short overlap period so users can return to Copilot if a source is not yet connected. Ask your Microsoft account team to confirm the license terms that apply to your agreement.
Questions buyers ask before moving off Copilot
How much effort and cost should we expect to move off Copilot?
Expect two kinds of cost: a one-time implementation and a recurring run cost, and neither is a fixed number until the scope is written. The recurring side includes model inference (GPU capacity you run yourself or per-token API fees), hosting for Onyx's index, Postgres, Redis and model servers, and the staff who operate upgrades, backups and monitoring. The one-time side covers connector setup for SharePoint, OneDrive, Outlook and Teams, identity integration and testing. Costs rise with the number of sources, the size of the document estate, the number of users, whether you need Enterprise Edition features, and whether you run models on your own GPUs. Ask any implementation partner for a quote built from a written scope that separates these components, and ask which items recur.
How long does a parallel run of Onyx and Copilot take?
The length of a parallel run depends on how much you need to verify before you trust the new assistant, not on a fixed period. The main drivers are the number of connectors you must validate, how many user groups must test real questions, whether permission sync matches what each person can see in SharePoint and Teams, and how long your change board takes to approve a license reduction. Plan the run around the license renewal date, and confirm with Microsoft the notice period and when add-on licenses stop billing before you set the end date. Agree the exit criteria in writing, such as a test set of questions and permission checks that both sides pass, before any license is removed.
What does the work need from our side?
The work needs named people from identity, Microsoft 365 administration, security and the business groups who will use the assistant. On the identity side, you need an Entra ID application registration for OIDC or SAML sign-in and a decision on how group membership maps to Onyx roles. On the content side, you need service accounts or app registrations with read access to each source, and a clear view of where sensitive content sits, because the index will hold copies of it. You also need a hosting location in your own cloud account or data center, a model decision (hosted API or self-hosted through Ollama, LiteLLM or vLLM), and a test group with real questions drawn from daily work. Expect security to review data flows, retention and logging before go-live.
Can our own platform team run this without outside help?
A capable platform team can run Onyx, but the first deployment usually benefits from experienced help with connectors, permission sync and identity configuration. Check whether your team already operates Kubernetes or Docker, Postgres, a vector or keyword index such as Vespa or OpenSearch, Redis and GPU or model-serving infrastructure. Then check whether anyone has run Microsoft Graph and Entra ID integrations. Ask whether you need the ongoing work of upgrades, patching and monitoring covered by a retainer, or whether your staff can absorb it. DeployOpen plans, implements, integrates, hardens, backs up, upgrades and documents self-hosted platforms in your environment, and offers support and upgrades as retainers, so the split between your staff and an outside team is something to define in the written scope.
Is Onyx Community Edition enough, or do we need Enterprise Edition for SCIM and RBAC?
Community Edition covers RAG, AI chat, agents and actions under the MIT license, and it can connect your sources with their permissions. SCIM user provisioning and role-based access control are listed among Onyx's enterprise features, and code in the ee directories falls under the Onyx Enterprise License, so confirm which features your deployment needs before you pick an edition. If your access model depends on automatic deprovisioning from Entra ID or on fine-grained roles, plan for Enterprise Edition or a documented workaround and confirm it in writing. Onyx also offers a managed Onyx Cloud, which changes where your data is hosted, so check that option against your residency requirements.
Can we move our Copilot chat history into Onyx?
Treat Copilot chat history as a separate export problem, not as something Onyx imports automatically. Copilot prompts and responses are stored as items in each user's Exchange Online mailbox and can be found through Purview eDiscovery, and the related migration guidance covers how to export them. Onyx connects to live sources such as SharePoint, OneDrive, Outlook and Teams, so it indexes the documents and messages behind your work rather than replaying old assistant sessions. Decide with legal and records teams whether you need to keep old prompts at all, because an export can contain sensitive content that then needs its own retention and access controls.
What should we confirm with Microsoft before cancelling Copilot licenses?
Confirm the terms in your Microsoft agreement before removing any licenses, because the add-on and the base plan are billed separately. Ask Microsoft how the Copilot add-on is removed from each eligible plan, when billing stops, whether any notice period or minimum term applies, and whether web-based Copilot Chat stays available with your subscription. Check how your contract treats Microsoft 365 E3, E5, Business Premium and E7, since the licensing page describes Copilot as an add-on to some plans and included in others. Also confirm whether Copilot data retention or eDiscovery obligations continue after cancellation, and record the answers in writing with your procurement team.
How DeployOpen scopes, runs and supports the migration
DeployOpen plans, implements, integrates, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, so an Onyx deployment that replaces Copilot grounding runs in your cloud account or data center. Engagements are fixed-scope, with scope and deliverables agreed in writing before any work starts.
How we scope
- Written scope lists which SharePoint, OneDrive, Outlook and Teams sources Onyx will index, and which will stay out.
- Scope records the Entra ID sign-in method, either OIDC or SAML, and how SCIM provisioning will be handled.
- Scope names the model providers or self-hosted models, the deployment target and the side-by-side period before license end.
How we build
- We deploy Onyx with Docker, Kubernetes, Helm or Terraform in the environment you choose, following the agreed scope.
- We configure connectors and test that permission sync returns only documents each test user can already open in the source application.
- We document the model routing, index and database layout, and the logs and query history kept for your audit team.
How we hand over
- Handover includes runbooks for backups, upgrades, connector maintenance and access changes, written for your operations staff.
- We provide evidence for compliance assessments, such as configuration records and permission test results, for your independent auditors to review.
- We run the side-by-side comparison with your pilot users and record which Copilot workflows still need a replacement.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer, scoped separately from the migration.
- Retainers can cover Onyx version upgrades and Helm chart updates, tested against your connectors before they reach users.
- Confirm response expectations, service levels and upgrade windows in the written retainer scope before signing.
