# Wallboard - User Management Deep Dive

> This documentation outlines how Wallboard handles user access, roles, team structures, and UI customization. Optimized for internal AI assistant use.

---

## 1. User Accounts

Each user has:
- **Username / Email**
- **Password or SSO credentials**
- **Assigned Role**
- **Team Memberships**
- **Tenant Scope** (multi-tenant only)

Users can belong to one or more **teams**, which determines access to resources.

---

## 2. Roles (Hierarchical Permissions)

| Role                | Permissions Summary                                                                 |
|---------------------|--------------------------------------------------------------------------------------|
| Administrator        | Full system access: users, content, devices, integrations, settings.                |
| Technical Manager    | Manages integrations, infrastructure, high-level system elements.                   |
| Content Manager      | Full content creation and scheduling capabilities.                                  |
| Content Editor       | Can edit assigned content and playlists.                                            |
| View Only            | Read-only access. No create, edit, or delete rights.                                |
| Device User          | Basic access focused on device operations or diagnostics.                           |

Roles may be extended or customized depending on tenant configuration.

### Content Role Governance

| Role | Current content governance behavior |
|------|--------------------------------------|
| Content Editor | Can create, duplicate, and edit accessible content while it is not assigned to a screen. Cannot save changes to content already assigned as current, next, or emergency content on any screen. Practical review flow: duplicate assigned content, edit the copy, then ask a Content Manager to review and place it on screens. |
| Content Manager | Can save assigned content and can assign content to screens or screen groups. This is the existing lightweight approval boundary: managers decide which content reaches screens. |

This built-in governance has no draft states, review requests, approval queue, or approval notifications. Teams can scope which content each Content Editor or Content Manager can access, so separate review bubbles can be modeled with team membership and resource assignment.

---

## 3. Teams and Access Control

Wallboard uses **team-based access control**: team members receive access to resources assigned to their teams. Account settings govern access to unassigned resources and access for users outside teams. Administrators normally have customer-wide access; selecting a team view can narrow it.

### Key Concepts:
- A **resource** can be assigned to one or more teams.
- **Users** inherit access through team membership.
- **Unassigned resources** may be visible globally (if tenant allows it).

This model allows precise delegation and organizational boundaries.

### Tag Catalog Access

- **Scope:** One customer catalog per type: Device, Device folder, Content, File, Channel and Sub channel. Tags can belong to several teams, without separate team name namespaces. Catalog lists and suggestions follow tag access.
- **Use versus maintenance:** Reachable **Read only** tags can be assigned to or removed from editable items. Catalog comment edits/deletion require the tag-type role and one writable assignment among the user's relevant teams. Item sharing does not automatically share existing tags. Inaccessible attached tags stay locked and are preserved on save.
- **Creation:** Select existing tags in an item's dialog; use **Tag management > Add tag** for type, name, optional comment and teams. Usable item teams seed the picker; otherwise a non-administrator's team list supplies defaults. Direct administrator creation has no preselected teams. Team-scoped non-administrators must select at least one writable team.
- **Administration:** **Settings > Tags > Manage teams** or **Settings > Users > Teams > Manage tags** manages tag access on Business/Enterprise. Inaccessible names remain reserved; an administrator can share the existing tag. Removing its last team follows the account's teamless-access setting.
- **Maintenance limits:** **Edit tag comment** cannot rename a tag or change its type. Deletion is blocked while used, including inherited use.

---

## 4. UI Profiles

UI Profiles simplify Wallboard by hiding or disabling UI controls. They are interface governance, not authorization; use roles and teams for access control.

| Scope | UI surface | Behavior |
|-------|------------|----------|
| System rules | System settings | Base hidden UI rules for the instance |
| Server-wide UI profile | `Administrator > Customers > Server-wide UI profiles` | Super Admin reusable preset assignable to customers; in-use profiles cannot be removed |
| Customer rules | Customer UI profile editor / Customer manager | Customer-specific overrides |
| User Interface Profile | `Settings > Users > UI Profiles` | Customer-owned reusable profile assignable to users |
| User rules | User editor / user UI profile editor | User-specific overrides |

Effective order: System rules -> Server-wide UI profile -> Customer rules -> User Interface Profile -> User rules. Later layers override earlier layers; inherited or unset values keep the previous layer.

Network members: when a Network Owner selects a `User Interface Profile` for a `Network member`, Wallboard copies that profile's current rules as a snapshot onto the member customer. Later source-profile changes do not propagate to existing members.

Import/export: UI profile editors and customer/user modals can import/export hidden UI rules as local JSON files. Import updates the currently edited layer; for Network members, an imported file overrides the selected profile snapshot and disables the selector with a warning.

### View As: Admin, Team and Impersonate

Sidebar **View as** modes for troubleshooting and setup:

| Mode | Behavior |
|------|----------|
| Admin | Shows menus hidden by UI Profiles. Does not elevate the operator's role. |
| Team | Narrows the operator's view to selected teams without changing identity. |
| Impersonate | Frontend preview of another user's role menus, UI Profile, team-scoped lists and preferences in the selected customer. API keeps the operator's token and permissions; customer and language stay the operator's. Not exact effective access and not a globally read-only sandbox. |

Eligibility: **Administrator** / **Super administrator** on **Business** / **Enterprise** (not Essential / `STARTER`). Network ownership alone is insufficient; Super administrator needs a selected eligible customer. Entry via **View as > Impersonate** or **Settings > Users > Impersonate user**; self-selection blocked. Entry, switch and exit go to dashboard home. Banner and sidebar show the active preview and exit.

While impersonating, three preference areas can be saved to the target:

| Saveable area | Stored preference |
|---------------|-------------------|
| Table layouts | `tableConfigs` |
| Quick Access layouts | `quickAccess` |
| Pinned items | `pinnedItems` |

**Save to user** persists; **Keep local** stays in the preview. Other metadata stays local. Read-only operators do not persist (backend skips the metadata update). Metadata-only saves create **no user/audit log entry** and do not notify the target.

---

## 5. Tenant and Super Admin Management

For cloud or shared-hosting setups, a **Super Admin** can:

- Access and manage all tenants
- Create new tenants
- Configure tenant branding and features
- Move devices or users between tenants
- View cross-tenant usage data

This does not apply to fully isolated on-premise instances.

---

### Customer Package Types

Package types define per-customer feature access and system limits, tailoring platform complexity to signage requirements.

#### Package Tiers
- **Essential**: Entry-level, basic signage
- **Business**: Mid-tier, essential features
- **Enterprise**: Full-featured, comprehensive capabilities

#### Essential Package Restrictions
**Disabled Features:**
- **Custom Domain** (includes SSO, branding, login customization)
- **Teams**
- **Notifications**
- **Advertisers**
- **Integrations**
- **Template Folders** (cannot create or convert)
- **Proof of Play** analytics
- **User Interface Profiles**

**Resource limits:** A Super administrator sets count limits for 20 resource types in **Administrator > System Settings > Limits**, grouped as **People and profiles**, **Content and media**, **Delivery and targeting**, and **Data and automation**. Available Essential and Business limits can be changed up to 1,000,000; resources excluded from Essential stay fixed at 0. For these counts, 0 makes a resource unavailable. For an Enterprise customer, a Super administrator can set individual resource overrides by opening the customer in **Administrator > Customers**, then **Limitations > Resource limits**; a blank field inherits the current Business value. Counts cover the whole customer, including resources outside a user's teams. Existing resources remain if usage exceeds a lowered limit, but further creation of that resource is rejected. These count limits are separate from **Storage Space**, the **Concurrent content limit** (where 0 means unlimited), and device licences.

## 6. Authentication

Supported login mechanisms:

- **Username + Password**
- **Single Sign-On (SSO)** - Google, Microsoft, enterprise IdPs
- **Multi-Factor Authentication (MFA)** - May be tenant-configured
- **Password Policies** - Length, complexity, expiry rules are customizable

### SAML SSO User Provisioning

**Prerequisites:**
- Custom Domain with DNS entry configured
- SAML IdP configuration completed (see security.md)

**Attribute Mapping:**

| Attribute | Required | SAML Attribute Name | Behavior |
|-----------|----------|---------------------|----------|
| Email | Yes | Configurable (default: "mail") | User identifier, must be unique |
| Name | No | Configurable (default: "displayName") | Display name (fallback: email) |
| Role | No | Configurable (default: "wallboardRole") | Any role except Super administrator |
| Teams | No | Configurable (default: "groups"), multi-valued | Team ID list |
| UI Profile | No | Configurable (default: "wallboardProfile") | UserInterfaceProfile ID |

**Mapping Features:**
- **Prefix stripping:** Automatic removal of common prefixes
    - Role: configured role prefix is removed before matching
    - Teams: "team-abc123" -> "abc123"
    - UI Profile: "ui-profile-abc123" -> "abc123"
- **Case-insensitive role:** Mapped role names are matched case-insensitively
- **Non-existent teams:** Logged and skipped (user assigned to valid teams only)
- **Invalid role:** Ignored, uses default role

**Existing User Login:**
1. User found by email in database
2. Validation: `ssoLoginEnabled` must be true (or null), `customerId` must match domain
3. Updates (if mapping enabled):
    - Name: updated if provided and different
    - Role: updated if `roleMappingEnabled=true`, unless SCIM enabled and User provisioning enabled are both on (cannot set Super administrator)
    - Teams: replaced with mapped teams + `defaultTeams` if `teamMappingEnabled=true`, unless both SCIM switches above are on and Group sync mode is not Disabled
    - UI Profile: updated if `userInterfaceProfileMappingEnabled=true`

**New User Creation:**

Preconditions:
- `automaticUserCreationEnabled=true` on domain
- Email not already registered

User attributes:
- Email: from SAML assertion (required)
- Name: from SAML assertion OR email
- Role: mapped role OR `defaultRoleOnUserCreation` (fails if neither)
- Teams: mapped teams + `defaultTeams`
- UI Profile: mapped profile OR `defaultUserInterfaceProfile`
- Auth Provider: SAML
- SSO Login Enabled: true
- Password: not set (SSO only)

When SCIM suppresses a SAML mapping, SAML auto-create uses SSO defaults (not SCIM defaults) and creates a SAML account - not a SCIM-managed one. Name and UI profile mapping stay independent.

**Security Constraints:**
- **Super administrator restriction:** Cannot create or elevate a Super administrator via SAML
- **Maximum role:** Administrator
- **Role requirement:** Must have either mapped role or default role configured (creation fails if neither)

### SCIM Provisioning

IdP-driven account lifecycle (create/update/deactivate/delete) before or between sign-ins - separate from SAML JIT login. Business/Enterprise; **Settings > Custom Domain > SCIM Provisioning**; Administrators and Super administrators. Requires Custom Domain (domain create = Super administrator). Read-only / UI profile rules can hide management.

**Setup:** Enable **SCIM enabled** + **User provisioning enabled**; set Default role/teams/UI profile; save; copy connector base URL + unique identifier; **Generate token** (shown once). Configure SSO separately for sign-in.

**UI defaults if no saved config:** SCIM and User provisioning off; Default role **View only**; no default teams/UI profile; Group sync **Disabled**; role-from-extension, role-from-group, exclude-role-groups off; no role mappings.

| Area | Behavior |
|---|---|
| Identity | Match on userName = email. Email globally unique; not renameable via SCIM. Existing manual/SAML email = conflict (no auto-adopt). |
| Initial access | Defaults: role, valid teams, optional UI profile. Active unless IdP deactivates. SSO on; password/Magic Code off. Defaults do not continuously reset existing users. |
| Deactivate / delete | Deactivate retains account, revokes tokens, blocks sign-in/refresh. Reactivation does not clear independent restrictions. Delete removes account. |
| User controls | **Managed by identity provider** on disabled edit/team actions; password change hidden; **Deactivated by IdP** when deactivated. Describes UI controls, not every admin API. |
| Team controls | SCIM teams: **SCIM** badge; not renameable via Team card. Resource assignment still required for access. |
| Tokens | Save enabled config before token ops. Customer-scoped, shown once. **Rotate** immediately revokes old; **Revoke** stops that token. |

**Group sync:** Full sync = create/rename/delete SCIM teams + membership. Member sync only = membership on already-SCIM teams (no create/adopt manual teams). Disabled = no group writes. Members must be SCIM users in same customer; full membership replace can drop manual members. Provider-driven schedule (Wallboard does not poll).

**Role mapping:** Extension attribute > group membership (highest matching group). Else new users get Default role; replacements keep existing. Max role Administrator (never Super administrator). **Exclude role groups from team sync** keeps role-only groups out of Teams. Group roles need role-group refs in user create/replace data; membership-only pushes and mapping edits do not retroactively recompute all users.

**SSO coexistence:** SCIM + User provisioning suppress SAML role mapping; team mapping suppressed only when Group sync is not Disabled. SAML may still update name/UI profile. SAML auto-create before SCIM produces an existing-email conflict; no auto-migration.

---

## 7. User Lifecycle Example

1. Admin creates a new user account.
2. Assigns a **role** (e.g. Content Editor).
3. Adds the user to one or more **teams**.
4. Teams already have assigned content, devices, playlists.
5. Optionally apply a **UI profile** to limit complexity.
6. User logs in and sees only what's relevant to their role and teams.

---

## 8. Troubleshooting Access

| Symptom                          | Likely Cause                          | Solution                                             |
|----------------------------------|----------------------------------------|------------------------------------------------------|
| Cannot see content or devices    | Not part of any team with access       | Add user to appropriate team                         |
| Cannot edit content              | Role is View Only or permissions too low | Upgrade to Content Editor or Manager               |
| Button missing from UI           | Hidden via UI profile                  | Adjust or reassign UI profile                        |
| Empty dashboard                  | No resources assigned to any team      | Link content/devices to user's team(s)              |

---