Skip to Content
Task guidesTechnical: Customer Tenant Onboarding

Customer Tenant Onboarding

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

An end-to-end runbook for bringing a new customer onto the Entra multi-tenant SaaS profile: create their organization, trust their Entra tenant, wire up SCIM provisioning, and get their first users signed in as members of their own workspace. See Identity & Access for the reference material this runbook draws on — tenant-registration permanence, SCIM credential rotation, IdP group mapping mechanics — and use that page when you need the “why”, not the steps.

This flow only applies to the Entra multi-tenant SaaS profile (ORQESTRA_OIDC_ISSUER_MODE=entra_multi_tenant). It does not apply to a single-tenant or self-hosted deployment.

Platform side

Everything here is Platform-Admin-only, performed once per customer.

1. Create the organization

Administer → Access & org → Organizations → New organization creates the customer’s organization (display name, slug, plan) and requires an explicit initial governance policy commitment. Record the approved durations, jurisdiction, storage mode/backend, source, and authority references; the portal does not infer them. The same policy can later be managed from the organization detail page or Administer → Organization policy for the active workspace’s organization.

The API requires the same explicit commitment:

The following values are illustrative only; use the customer’s approved commitment and authority record, not these example durations.

curl -X POST http://localhost:8000/v1/organizations/ \
  -H "Content-Type: application/json" \
  -d '{"slug":"acme","display_name":"Acme Corp","initial_policy":{"short_retention_days":30,"long_retention_days":365,"hot_retention_days":90,"worm_retention_days":365,"jurisdiction":"EU","worm_mode":"GOVERNANCE","worm_backend":"s3","worm_backend_max_retention_days":3652058,"source_kind":"customer_commitment","source_ref":"customer-policy:2026-10","authority_ref":"approval:ticket-12"}}'

This returns the org_id the remaining steps need.

When local scripts/seed-auth.sh needs to create the default organization, set ORQESTRA_INITIAL_ORGANIZATION_POLICY_FILE to an approved JSON commitment; the script does not supply local retention or jurisdiction defaults.

2. Register the customer’s Entra tenant

Administer → Access & org → Organizations → (organization) → Trusted tenants (the same page documents this — see Registering a trusted tenant for what the permanent-binding warning means before you do this). Supply the customer’s Entra directory (tenant) ID — get this from the customer’s Entra admin, it is not something Orqestra can discover on its own.

API equivalent:

curl -X POST http://localhost:8000/v1/organizations/{org_id}/identity-tenants \
  -H "Content-Type: application/json" \
  -d '{"tenant_id": "<customer-directory-id>", "display_name": "Acme Corp Entra"}'

or orqestractl identity-tenant register --org-id <org_id> --tenant-id <customer-directory-id> --display-name "Acme Corp Entra".

This returns an identity_tenant_id — the next two steps need it.

3. Issue a SCIM provisioning credential

From the same organization detail page, the Trusted tenants section’s SCIM panel has an Issue credential button. API equivalent:

curl -X POST \
  http://localhost:8000/v1/organizations/{org_id}/identity-tenants/{identity_tenant_id}/scim-credentials \
  -H "Content-Type: application/json" \
  -d '{"expires_in_days": 90}'

The response’s secret field is shown once — copy it now, it hands off to the customer’s Entra admin as the SCIM “Secret Token” in step 6 below. See SCIM credentials: issuing, rotation, revocation for the two-active-credential rotation mechanics.

Customer side

The customer’s own Entra administrator performs these steps. The Orqestra application (client) ID and the SCIM secret from step 3 are the two values you hand them.

Send the customer’s Entra admin this URL, filled in with the portal’s own Entra application (client) ID:

https://login.microsoftonline.com/<customer-tid>/adminconsent?client_id=<portal-app-id>

This is the unversioned tenant-wide admin-consent shorthand. Microsoft’s current reference documents the equivalent, fully-parameterized /v2.0/adminconsent form, which requires redirect_uri — append &redirect_uri=https://<host>/api/auth/callback (the portal’s own registered callback, the only redirectUris entry on its app registration). Consent is recorded in the customer’s tenant before that redirect happens; the callback page itself expects an authorization code (a normal sign-in), which the admin-consent response does not carry, so it will show a sign-in error — that error is expected and does not mean consent failed. See the admin consent protocol reference  for the full parameter set.

An administrator who can grant tenant-wide admin consent for the customer’s tenant (typically a Global Administrator, Privileged Role Administrator, or Cloud Application Administrator) signs in there. Because the Orqestra API app registration lists the portal as a knownClientApplications / pre-authorized client, this single consent creates both service principals in the customer’s tenant — the portal application and the Orqestra API — and grants consent for the delegated permissions both request: openid, profile, email, offline_access (portal) and access_as_user (API). See Microsoft’s multitenant consent guide  for how knownClientApplications bundles multi-tier consent into one step. Consent alone grants nothing inside Orqestra: until the platform side registers this tenant (step 2), tokens from it are rejected.

5. Create the enterprise application for provisioning

Provisioning is configured on its own non-gallery enterprise application, separate from the service principals admin consent created. In the customer’s Entra admin center: Entra ID → Enterprise applications → New application → Create your own application, choose “integrate any other application you don’t find in the gallery (Non-gallery)”, name it, and select Add.

6. Configure automatic SCIM provisioning

On that enterprise application: Provisioning → Get started, set Provisioning Mode to Automatic, then fill in:

  • Tenant URL: https://<host>/scim/v2
  • Secret Token: the SCIM credential secret from step 3

Select Test Connection before saving — Entra issues a filtered GET /Users query against the tenant URL to confirm the endpoint and credential work. See Microsoft’s SCIM provisioning tutorial  for the general mechanics of this screen.

7. Required attribute-mapping change: externalId

This step is not optional. Entra’s default non-gallery SCIM mapping sets externalId’s source attribute to mailNickname. Orqestra’s SCIM endpoint requires externalId to be the Entra objectId (a GUID) and rejects anything else with a 400 scim_external_id_invalid error — mailNickname is not a GUID, so every provisioning request fails until this is fixed.

Under Provisioning → Attribute Mapping → Users, edit the mapping whose target attribute is externalId, and change its Source attribute from mailNickname to objectId. See Microsoft’s attribute-mapping customization guide  for the general edit flow (Provisioning → Attribute Mapping → pencil icon).

8. Assign users and groups, then provision

Under Users and groups, assign the users or groups that should be provisioned into Orqestra. Group-based assignment requires Entra ID P1 or P2; on the free tier, assign users directly (see Entra licensing and group shape — only direct group membership provisions, nested groups are not expanded).

The first automatic cycle can take anywhere from 20 minutes to several hours. To provision one specific user immediately instead of waiting, use Provisioning → Provision on demand and select that user.

Sign-in and workspace membership

A provisioned user existing in Orqestra (a scim_user row) is not the same as that user being a member of a workspace. Two more things have to be true before they can sign in and use a workspace:

  1. The workspace must belong to the customer’s own organization. Orqestra refuses to bind an Entra actor from tenant A into an organization whose registered tenant is B (422 principal_not_admissible_in_organization) — including refusing an operator-tenant actor into any customer organization outright. A customer’s users can only ever become members of workspaces under their own org.

  2. Something has to grant them a role. The two ways:

    • IdP group mapping (recommended, automatic): map one of the customer’s Entra group GUIDs to a role at namespace or organization scope, per IdP Group Mapping. Membership is granted the moment a mapped user’s token carries that group claim — no manual per-user step.
    • Direct workspace-member add: a Workspace Admin (from the customer side, once at least one of their users has a role) adds individual members by actor reference.

Operator-tenant users are never workspace members

Users signed in through the operator’s own Entra tenant (ORQESTRA_ENTRA_OPERATOR_TENANT_ID) are Orqestra platform staff. They can only ever be Platform Admins, never workspace members of any organization: admission itself refuses an operator-tenant actor that doesn’t hold a platform admin group, and the organization-binding check above refuses that actor into any organization even if it did. There is no configuration that lets an operator-tenant identity join a customer’s workspace — provision a real account in the customer’s own tenant for that.

Configure AI resources and the workspace assistantTechnical reference: Pen-Test Runbook