2.10 Users and role-based access

Outcome

The customer's full team is provisioned, each with the right role, and the customer's TENANT_ADMIN is comfortable adding new users without your help.

Prerequisites

• 2.4 First tenant admin is signed in and active.

Hand off to the customer

After 2.4, the customer's TENANT_ADMIN is responsible for their own user roster. Your job here is to:

• Confirm RBAC roles cover the team's responsibilities.
• Walk the customer through the user-management UI.
• Verify the audit log captures the user changes.

Roles available

Role	Typical assignee	What they can do
TENANT_ADMIN	IT lead, COO	Manage everything, including users and roles.
BILLING_LEAD	Billing manager	Manage payers, fee schedules, claims, denials.
BILLER	Billing specialist	Day-to-day claim work.
RCM_ANALYST	Reporting / finance	View dashboards, run reports.
MEMBER_SERVICES	Front desk, intake	Manage member records, eligibility.
READONLY	Auditor, exec dashboard	View only.

Custom roles can be defined in Settings → Roles → Add role if needed; assemble from the canonical permission set.

Steps

1. Walk the customer through Settings → Users → Add user

   Have them add their first 2–3 team members live, with you on the call. Confirm:

   • Email gets the OTP (check identity.tenant_audit for USER_CREATED).
   • New user can log in and is forced to change password on first sign-in.

2. Walk the customer through Settings → Roles

   Confirm they can:

   • View the canonical roles.
   • Create a custom role and assign permissions.
   • Edit a user's role assignment.

3. Document escalation path for forgotten passwords

   The customer's TENANT_ADMIN can reset passwords from the user list. If the TENANT_ADMIN themselves locks out, only a platform admin can reset via impersonation.

4. Confirm SSO posture

   The platform supports password auth today. SSO via Entra ID or SAML for tenant users is on the roadmap; if the customer requires SSO at go-live, surface this to engineering early.

Validation

Check	Expected
security.app_user count	matches customer roster
security.user_role rows	every user has at least one role
identity.tenant_audit USER_CREATED count	matches step 1
Customer admin demos add/remove user	confident, no calls to support

Troubleshooting

Symptom	Likely cause	Fix
New user OTP email never arrives	SMTP not configured at platform level	Check the platform mailer config (Admin → System → Notifications).
Customer admin can't add users	Their role is below TENANT_ADMIN	Confirm security.user_role for that user.
Login lockout after 5 attempts	Account-locking policy	Wait 15 min, or reset via UI.

Next

2.11 — End-to-end test