Recommended deployment pattern
Before you start clicking, pause to decide which Microsoft account CXOrelay will sign in as. This is the single most important decision in the setup. You have two options:
| Option | When to use it | Trade-offs |
|---|---|---|
| Dedicated service account (recommended) Example: CXOsignal-alerts@yourcompany.com |
Any production deployment. Anything you want to keep running past your tenure on this project. | One-time setup: create a new Microsoft 365 user, give it a license, add it as Project Admin on a dedicated project. After that, the relay runs as that account, independent of any individual person. |
| Personal account (your own Microsoft account) | Quick proof-of-concept on your own machine; you're the only one who'll ever interact with this. | Notifications come from you. If you leave the company, the relay stops. Your machine has to stay on / your tab has to stay open. You can't share the work with a colleague. |
Strong recommendation: use a dedicated service account. The rest of this guide assumes that path. If you're just kicking the tires on your laptop for an hour, the personal-account path works too.
Why the service-account pattern
- Continuity. The relay is a long-running background process — not a person's tool. If CXOrelay is tied to your Microsoft account and you leave, it dies with you. Tied to a service account, it survives any individual departure.
- Notifications come from "CXOsignal-alerts", not from you personally. Recipients see emails from
CXOsignal-alerts@yourcompany.com, which is the right brand for an automated monitoring system. - Separation of duties. Whoever maintains the relay (you, IT, an ops team) interacts with it via the service account — not by impersonating you. Clean audit trail; clean security model.
- Dedicated machine. The relay needs a Mac (or any browser-capable computer) with an always-open tab. With a service account, that machine doesn't have to be your primary laptop — it can be a dedicated Mac.
The detailed setup tasks for the service-account pattern are in Tasks for your IT Admin. The two callouts below cover the two most common pitfalls.
Why the service account must be a member, not a guest
Microsoft Entra distinguishes between members (users created inside your tenant; have a license issued by your tenant) and guests (users invited from another tenant via B2B collaboration). They look the same in many UI surfaces but behave differently for cross-user data access.
Empirical finding (June 2026): Azure DevOps' Extension Data Service silently isolates the EDS namespace for guest accounts. A guest signed in to CXOrelay sees an empty Widget Registry even when their tenant has dozens of registered OKRsignal widgets — because the guest is reading their own (empty) per-tenant slice of the EDS store, not the shared org-wide slice that members read.
If you try to "save a license" by inviting an external mailbox as a guest, CXOrelay will sign in successfully but won't see any of the widgets it's supposed to be monitoring. The fix is to create a real member account with a license.
Why Project Admin — not Project Collection Administrator
The minimum permission CXOrelay's configuration surface needs is Edit team dashboards on the dashboard the relay runs on. Project Administrators on the dashboard's project have this by default, and that's the minimum-privilege role we recommend.
It might be tempting to make the service account a Project Collection Administrator (the org-wide super-admin role) instead. PCA also works — PCAs inherit every permission in the org — but PCA grants the service account access to everything in your ADO organization, far beyond what CXOrelay needs. A leaked PCA token compromises the entire org; a leaked Project Admin token compromises one isolated project. Stick with Project Admin unless you have a specific reason.