Onboarding a client¶
Onboarding is the one part of the workflow with genuine Microsoft-side steps. The goal is a client tenant the platform can resolve tickets to and execute against — with delegated access you can prove, not a password you store.
There are five surfaces to get right. Four are in-app; the fifth (GDAP + consent in Microsoft) is the real work.
1. Establish GDAP¶
Set up a granular delegated admin (GDAP) relationship with the client tenant, scoped to the roles the platform needs to do its job (identity, Exchange, and — where used — compliance administration). GDAP is time-bound and role-scoped by design: the platform never holds standing global admin, and access expires unless renewed.
Scope to what you'll actually run
Grant the admin roles that match the operations you expect to perform for this client. You can widen scope later; start with what onboarding and everyday tickets need.
2. Consent the platform's app access¶
The platform acts through its own app registrations — one per workload (Graph, Exchange, and, where used, compliance and SharePoint) — using application permissions, authenticated with certificates or an app secret, never user passwords. An administrator grants admin consent for those apps in the client tenant; the Portal gives you the consent link to send.
Until consent is granted, discovery and execution calls for that tenant will fail with a permissions error. This is expected — grant consent, then re-run discovery.
3. Register the tenant and discover execution access¶
Add the client in the Portal, then let the platform discover what it can execute. Discovery probes each workload (Graph, Exchange, and compliance where enabled) and records, per workload, whether the platform can actually authenticate and act.
The result is a per-tenant readiness picture:
| Signal | Meaning |
|---|---|
| Ready for execution | Every configured workload authenticated and can run operations. |
| Degraded | Some workloads are ready and at least one isn't (consent, a directory role, or a permission is missing for that one). This does not block the healthy workloads — the ready ones still execute; only the specific unhealthy workload is refused, with a clear reason. An honest "not everything is ready yet," not a stop. |
| Consent / permission pending | The app or GDAP grant isn't in place yet — finish steps 1–2 and re-discover. |
| Not reachable | The tenant record or connection details need attention. |
Consent isn't the same as a role
Admin consent grants an app its API permissions but not the Entra directory roles some workloads need — Exchange needs Exchange Administrator, compliance needs Compliance Administrator. A workload can read as consented but still be unable to act until that role is assigned in the client tenant. Discovery surfaces this as Degraded for that workload rather than a silent failure at execution time.
Vanity-domain tenants
Exchange and compliance operations connect using the tenant's *.onmicrosoft.com organization, which is not the same as a client's primary vanity domain. The platform captures and stores that organization during onboarding so those workloads can target the right organization on a client whose primary domain is a vanity domain — no separate step for you.
4. Confirm ticket → tenant resolution¶
When a ticket arrives, the platform resolves it to a managed tenant automatically — by the requester's email domain and other hints. A ticket only proceeds to planning once it has resolved to a single tenant. If resolution is ambiguous or the tenant isn't onboarded, the ticket is held rather than acted on.
5. Connect a PSA¶
Connect the client's PSA so tickets flow in. In the Portal, Settings → PSA connectors, choose the system (HaloPSA today), and enter the connection essentials. Sensible defaults for endpoints and options are pre-filled — you generally only supply what's genuinely per-customer (the instance URL and the API credentials).
- Credentials are stored as secret references, never in plain text.
- You can send a test and confirm tickets pull before going live.
- A connector can be disconnected later, which clears its credentials and stops ingestion.
No PSA yet? You can still work
While a client is being set up you can pull tickets on demand or enter them directly, so onboarding and testing don't have to wait on the PSA connection.
Once a client shows ready for execution and tickets resolve to it, you're ready to run the platform.