Module 08
Administration & Role-Based Access Control
Access in Marketing Central is not a configuration toggle — it is an architectural constraint enforced server-side on every request. A user's effective access equals their role intersected with their data scope, derived from the Admin System, and checked on the server regardless of what the client sends.
"Accommodate entity/territory/office/support associations, role-based permissions that restrict what users can see and do, and SSO integration with existing Liberty identity infrastructure."
The Six User Roles
Marketing Central supports six user role types. Each role is assigned in Entra ID (for corporate users) or Entra External ID (for franchise and vendor users) as an App Role. Role assignment is a Liberty admin action — no user can self-assign a role.
| Role | Who Has It | What They Can Do | Fund Control |
|---|---|---|---|
| Franchisee | Individual franchise office owners | Storefront, Design Builder, checkout (own office), claims submission, order history, dashboard | Spend own funds only |
| Entity | Multi-office franchise owners | All franchisee capabilities + entity-level reporting across owned offices | Spend own entity's funds |
| Marketing | Liberty marketing team members | All platform access, fund allocation, claims review, vendor approval, catalog management, emulation | Full fund controls |
| Admin | Liberty system administrators | All Marketing capabilities + user management, vendor onboarding, system configuration, audit logs | Full fund controls |
| Corporate View | Liberty corporate stakeholders | All reporting and dashboard access across all offices — read only | None — read-only reporting only |
| Vendor | Third-party print and fulfillment vendors | Own product catalog, orders for own products, order status updates, shipping telemetry | None |
The Corporate View role was designed specifically to solve the problem the current platform cannot: giving Liberty's corporate stakeholders full reporting visibility without fund control access. A Corporate View user can see every fund balance, every order, every claim status — but cannot allocate funds, approve claims, or take any action that affects money. The separation is enforced server-side, not by UI hiding alone.
How Access Scoping Works
A user's role defines what kinds of actions they can take. Their data scope — derived from the Admin System — defines which offices, entities, and territories they can take those actions on. Effective access is the intersection of the two, enforced on every server-side request.
The Authorization Model
When a user makes a request — view an office's fund balance, place an order, approve a claim — the server checks two things independently: does this user's role permit this action type, and does this user's scope include the specific entity/office this action affects? Both checks must pass. A Marketing user who has been scoped to specific offices (hypothetically) could not take fund actions on offices outside their scope, even though their role permits fund actions.
Admin System as the Authority
Data scope is never self-reported and never stored only in Marketing Central. The Admin System is the authoritative source for which franchisee owns which territories and which offices. Marketing Central syncs this data and uses it as the basis for access decisions. When an office changes hands, the Admin System update propagates to Marketing Central — there is no manual step to update access in the platform separately.
Access control is enforced in the application's server-side API layer. What the UI renders is a consequence of the server's access decisions — it is not the access control mechanism itself. A client that sends a modified request to access data outside its scope receives an authorization error, not the data. UI-only access control is not access control.
Emulation (Act-on-Behalf)
Emulation allows Marketing and Admin users to act on behalf of any franchisee — placing orders, submitting claims, managing designs — as if they were that franchisee. This is essential for support workflows, training, and the Canada claims onboarding transition.
Session-Based Emulation
A Marketing or Admin user initiates emulation by selecting a franchisee office. The session immediately switches to that office's context — the user sees exactly what the franchisee sees, scoped to their office, their fund balance, and their order history. A persistent banner indicates the active emulation session and identifies whose context is active.
No Privilege Escalation
During emulation, the user's available actions are capped at the franchisee role's permissions — not the emulating user's role. A Marketing Admin emulating a franchisee cannot take admin actions using the franchisee's context. Emulation restricts; it does not elevate.
No Credential Exchange
The emulating user never sees, uses, or acquires the franchisee's login credentials. Emulation is a platform feature, not a shared login. The emulating user authenticates as themselves; the platform switches their working context to the target office.
Full Audit Trail
Every action taken during an emulation session is logged with both the emulating user's identity and the target office context. The audit log records session start, every action taken, and session end. Emulation sessions are not anonymous — they are more traceable than direct franchisee actions, because they carry two identities.
Office & Territory Management
Marketing Central's access model is only as good as the underlying office and territory data. The platform is designed to handle the full lifecycle of franchise office changes — openings, closings, and ownership transfers — without manual intervention beyond what the Admin System already tracks.
New Office Openings
When a new franchise office is added to the Admin System, it propagates to Marketing Central automatically. The new office appears in the appropriate entity's portfolio, fund allocation for the new office can be set by admin, and the new franchisee user can be onboarded via Entra External ID. No manual record creation in Marketing Central is required.
Office Closings
When an office closes in the Admin System, its Marketing Central record is deactivated. Historical data (orders, claims, fund history) is retained for audit purposes but the office is no longer accessible for new activity. Any pending orders or open claims are flagged for admin review at the time of closure.
Ownership Transfers
When a franchise office changes owners — one of the more complex scenarios in franchise operations — the Admin System update propagates the change to Marketing Central. The new owner's entity is associated with the office; the previous owner loses access. Historical data is retained but attributed correctly for audit trail integrity. Fund balances transfer per Liberty's configured rules.
US/CAN Toggle
Liberty's US and Canadian operations are managed in a single platform — there are no separate logins or separate instances. An in-app US/CAN toggle scopes reporting, catalog, currency, and certain features to the appropriate country. The toggle is role-specific: corporate-level users can toggle between countries freely; franchisees default to their country based on their office location.
US & Canada: One Platform, Configured Per Country
The RFP asks to customize the brand portal based on the two countries, US and Canada. Marketing Central satisfies this through configuration and scoping — not by standing up two separately-branded portals to maintain in parallel. It is one platform that presents the right country's experience to the right user, and that experience is data-driven rather than hard-coded.
What varies per country is controlled configuration:
- Catalog and product availability — which products and campaigns are offered in each country.
- Currency (USD / CAD) and tax rules — pricing and tax calculation appropriate to the country and province/state.
- Legal disclaimers and license-language requirements — the compliance copy that must appear for each market.
- Fund structures — US Zee Funds vs. Canada's MRA model.
- Language — EN/ES for the US, EN/FR for Canada.
An in-app US/CAN toggle scopes the experience to the right country without separate logins — a single identity, a single platform, presented correctly for the user's market. Country-specific presentation (terminology, compliance content, currency) is driven by configuration data that Liberty's Marketing team controls. A new country-specific rule, disclaimer, or label is therefore a settings change, not a code change. This fully meets the requirement: each country gets a portal experience tailored to its catalog, currency, compliance, funds, and language, delivered from one maintainable platform.
Audit Logging
An event-level audit log is maintained for all high-stakes actions in Marketing Central. The audit log is immutable — records are written and retained, never edited. It is accessible to Admin users and exportable for compliance review.
Fund Events
Every allocation, freeze, freeze release, expiration, and manual adjustment is logged with actor, timestamp, amount, and reason code. 5-year retention.
Claims Events
Submission, every status transition, reviewer actions, amount adjustments, AP routing, and payment confirmation — all logged with actor and timestamp.
Emulation Sessions
Session start, every action taken during emulation, and session end — logged with both the emulating user's identity and the target office context.
Role Changes
Every role assignment, role removal, and access scope change is logged with the admin who made the change and the effective date.
Order Events
Order placement, payment capture, cancellation, vendor status updates, and delivery confirmation — providing a complete chain of custody for every order.
Admin Actions
Vendor onboarding, product approval, catalog changes, user creation, and system configuration changes — all attributable to the admin who performed them.