Onboarding runbook (IT admin)

This is the canonical runbook the Onboarding Portal walks you through. It’s also reproducible end-to-end via the Claresia API for customers who prefer programmatic onboarding (CI/CD, Terraform, Ansible).

Audience: IT admin (Persona P2) Time: 30–90 minutes (Mode A/B); spans days for Mode C BYOC. Pre-reqs: signed contract; access to your IdP admin; access to your LLM platform admin.

The 10 steps

1. Click the welcome-email link. You arrive at onboarding.claresia.com/{tenant_slug}?token=... with a 10-step progress bar.

2. Sign in via your corporate SSO. WorkOS handles the IdP redirect. ~30s.

3. Confirm tenant details — display name, region, deployment mode, billing contact, support tier. Click Confirm. ~2 min.

4. Configure SSO — paste SAML metadata URL or upload SAML XML or enter OIDC discovery URL. Click Test login. See:

   • Okta
   • Azure AD / Entra ID
   • Google Workspace ~5–10 min.

5. Configure SCIM — copy the SCIM endpoint URL + bearer token from the portal. Paste into your IdP’s SCIM provisioning panel. Click Sync now. See SCIM 2.0 reference. ~5 min.

6. Connect LLM platform — pick from:

   • Claude Enterprise
   • Microsoft Copilot M365
   • OpenAI ChatGPT Enterprise
   • Google Gemini for Workspace

   For each, paste the credential + click Test connection. ~10–15 min total.

7. Provision Hub. Mode A: 1-click (~30s). Mode B: choose region, generate CMEK key, click Provision (~3–5 min). Mode C: paste mTLS endpoint URL + customer cert from your Terraform output (~5 min). See Storage backends. ~5–15 min.

8. Map roster to archetypes — auto from SCIM (recommended) or upload CSV. cc-061 archetype classifier achieves >99% on most rosters. Review unmatched rows. ~10–30 min depending on size.

9. Confirm skill entitlements — per-archetype defaults are pre-generated from the Cowork pack you chose (or auto-selected). Toggle off any policy-blocked skills. Click Publish. See Skill catalog. ~10–20 min.

10. Run smoke test — portal opens an in-app guide:

    Now go to your LLM and type @claresia.gatespic.pipeline-hygiene.

    Portal listens for the telemetry event. When it lands: green check + congratulations + links to Command Center, Hub, CSM Slack/Teams Connect channel. ~5 min.

What happens at each step

Step	Layer touched	governance_event emitted
1 — link click	Identity	auth.login (token-grant)
2 — SSO	Identity	auth.login
3 — confirm	Command Center	tenant.config_changed
4 — SSO config	Identity	connector.added(scim_idp)
5 — SCIM sync	Identity	roster.scim_sync_completed
6 — LLM connect	Distribution Plane	connector.added(llm)
7 — Hub provision	Hub	hub.provisioned, cmek.key_created (Mode B)
8 — roster map	Roster	rbac.archetype_assigned per user
9 — entitlement	Skill entitlement	skill.entitlement_changed
10 — smoke test	All 6	tenant.live

Every event is co-signed and queryable via the Hub API — the IT admin’s audit trail starts the moment they click the welcome link.

Programmatic onboarding (advanced)

If you prefer Terraform / CI / scripts:

# 1. Authenticate as a service account (after Step 1-3 in portal)
export CLARESIA_TOKEN=$(curl -X POST ...)

# 2. Configure SSO via API
curl -X POST https://api.claresia.com/api/v1/identity/sso/configure ...

# 3. Configure SCIM
curl -X POST https://api.claresia.com/api/v1/identity/scim/configure ...

# 4. Connect LLM
curl -X POST https://api.claresia.com/api/v1/llm/connectors ...

# 5. Provision Hub
curl -X POST https://api.claresia.com/api/v1/hub/provision ...

# 6. Sync roster
curl -X POST https://api.claresia.com/api/v1/roster/scim:sync ...

# 7. Apply Cowork
curl -X POST https://api.claresia.com/api/v1/skill-entitlement/coworks/.../apply ...

# 8. Trigger republish
curl -X POST https://api.claresia.com/api/v1/skill-entitlement/distribution:republish ...

# 9. Validate
curl https://api.claresia.com/api/v1/observability/tenant-health

Full Terraform module: terraform-claresia-tenant. Pinned to your subscription config in the Onboarding Portal Step 3.

Verifying the tenant is live

Open Command Center and check:

• ✅ Identity tab — SSO connection green, SCIM last-sync within last hour
• ✅ Distribution tab — at least one platform connected, last publish within last 60s
• ✅ Hub tab — provisioned, CMEK key shown (Mode B), tenant_id shown
• ✅ Roster tab — user count > 0, unmatched count = 0
• ✅ Skills tab — skills in published state, archetype grants set
• ✅ Telemetry tab — at least one event from the smoke test
• ✅ Audit log — tenant.live event present

If any of these are red, do not proceed to pilot launch. Talk to your CSM.

Common gotchas (across all 10 steps)

Symptom	Cause	Fix
Portal magic link expired	24h TTL exceeded	Request fresh link from CSM (Slack/Teams Connect)
SSO test fails	IdP attribute mapping missing email	See Identity → Overview
SCIM sync 0 users	Users not assigned to Claresia app	Assign in IdP, retry
LLM connect fails	API key scope insufficient	Re-mint with admin scopes (per-platform docs)
Smoke test event never lands	LLM platform audit ingest delay	Wait 5 min p95; check status page

Post-onboarding checklist

After Step 10 completes:

• Forward End-user guides to your pilot users
• Bookmark status.claresia.com for proactive alerts
• Subscribe to Trust Center email digest
• Schedule the pilot mid-check-in with your CSM
• If Mode C, confirm your customer-side backup/restore runbooks (see Backup + restore)