Portals App Overview
One umbrella for every public-facing portal in your business — catalog, identity & recovery, audit log, and analytics, without each app reinventing the wheel.
What is the Portals App?
Portals is the cross-cutting surface for the public portals your other apps publish — the Field Service Customer Portal, Recruiting’s Candidate Portal, Offboarding’s Former Employee Document Portal, the AFO visitor surface, eSignature kiosks, public Drive links, and so on. Each owning app keeps its own per-portal enable toggle. Portals reads that catalog, never writes — the source of truth stays where the feature lives — and adds the cross-portal concerns: a unified identity & recovery layer (magic-link / OTP), a searchable audit log, daily analytics rollups, branding defaults, custom domains, and security signals.
Core Value Proposition:
- 🗂️ Single Catalog — Every public portal in your business in one list, with status, owning app, and a one-click preview link.
- 🔐 Unified Identity & Recovery — Configure rate limits, recovery method (magic-link or OTP), and lockout thresholds once; every portal that opts in picks them up.
- 🧾 Compliance-Ready Audit — Every recovery event captured with hashed identifier, IP, user-agent, and configurable retention — never plaintext PII.
- 📊 Cross-Portal Analytics — Visits, recovery requests, success rate, and conversion rolled up nightly across every portal.
At a Glance
| ⏱️ Setup Time | 🔗 Owning Apps | 🔐 Recovery Methods | 📱 Mobile Ready |
|---|---|---|---|
| ~5 minutes | 6+ apps publish portals | Magic-link + OTP | ✅ Yes |
Perfect For:
- 🏢 Businesses with 3+ public portals — The umbrella adds the most value when you have several portals; under that, the owning app’s built-in settings are usually enough.
- 🛡️ Security & compliance teams — One place to set rate limits, review the audit trail, and export evidence for SOC 2 / HIPAA-style review.
- 👤 Admins responding to incidents — Filter the audit log by identifier hash or IP and trace exactly what happened during a recovery anomaly without exposing PII.
How It Works
┌─────────────────────────────────────────────────────────────────────────┐
│ PORTALS UMBRELLA │
├─────────────────────────────────────────────────────────────────────────┤
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ CATALOG │─────▶│ IDENTITY & │─────▶│ AUDIT LOG │ │
│ │ (read-only) │ │ RECOVERY │ │ (browse + │ │
│ │ │ │ (defaults) │ │ CSV) │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ ANALYTICS │ │ SECURITY │ │ BRANDING │ │
│ │ (nightly │ │ SIGNALS │ │ + CUSTOM │ │
│ │ rollup) │ │ │ │ DOMAINS │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
Owning Apps That Publish Portals
┌─────────────────┐
│ PORTALS │
│ (umbrella — │
│ reads only) │
└────────┬────────┘
│
┌──────────┬──────────┬─────────┼─────────┬──────────┬──────────┐
▼ ▼ ▼ ▼ ▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────┐ ┌──────┐ ┌────────┐ ┌────────┐ ┌────────┐
│ Field │ │ Recru- │ │ Off- │ │ AFO │ │ eSig- │ │ Drive │ │ ... │
│Service │ │ iting │ │board. │ │ │ │nature │ │(public │ │ other │
│Customer│ │Candid. │ │Former │ │Visit.│ │ Kiosk │ │ links) │ │ apps │
│Portal │ │Portal │ │Empl. │ │ │ │ │ │ │ │ │
└────────┘ └────────┘ └────────┘ └──────┘ └────────┘ └────────┘ └────────┘
Each owning app keeps its own per-portal enable toggle. Portals catalog reads state from each app — flipping a portal on or off still happens in the owning app’s settings.
Key Features
🗂️ Catalog & Discovery
The Catalog is the single registry of every public portal in your business — sourced from PublicPortalConfiguration records each owning app maintains.
| Feature | Description |
|---|---|
| Cross-app portal registry | Every portal in one list — owning app, slug, public URL, status |
| Status badges | Enabled / disabled / requires-token / public-link |
| One-click preview | Open the portal in a new tab without leaving the catalog |
| Jump to owning app | Direct link to the owning app’s settings to flip the toggle |
Use Case: Open the catalog before a quarterly access review to confirm which public surfaces are actually live, who owns each one, and which need a settings change.
💡 Pro Tip: The catalog is read-only by design. To enable / disable a specific portal, click “Jump to owning app” — that keeps the source of truth in the app that owns the feature.
🔐 Identity & Recovery
Three things live here, all powered by the shared PortalIdentityRecovery concern that any portal can opt into:
| Feature | Description |
|---|---|
| Default recovery method | Magic-link or OTP — applied to portals that support both |
| Per-portal override | Field Service can ship magic-link while Candidate runs OTP, with a one-flag override |
| Rate-limit window | Default 60 minutes (configurable) — sliding window per identifier per portal |
| Max attempts per window | Default 5 (configurable) — drops to lockout when exceeded |
| Identifier hashing | SHA-256 — no plaintext email or phone in the audit |
Use Case: A spike in failed OTP attempts? Drop the rate-limit max from 5 to 3 in Identity & Recovery — every portal using the concern picks up the new limit on the next request.
💡 Pro Tip: Recovery method is per-portal-overridable, not global. If you want to migrate a portal from magic-link to OTP, set the per-portal override — no code change, the concern reads the umbrella config.
🧾 Audit Log
A searchable browser over PortalRecoveryAudit rows — every recovery event your portals emit.
Filters:
- Date range
- Portal (cross-app dropdown)
- Event type (request, send, failure, rate-limited, consume, invalid-token)
- Identifier hash
- IP address
What’s captured per event:
- Timestamp
- Portal slug + owning app
- Event type
- SHA-256 hash of the identifier (never plaintext)
- IP address
- User-agent
- Outcome
| Feature | Description |
|---|---|
| Date / portal / event filters | Narrow to exactly the rows you need |
| CSV export | Filtered results downloadable for compliance review |
| Configurable retention | Default 180 days (configurable) — older rows pruned automatically |
Use Case: A user reports they never got their portal token. Filter the audit log by their identifier hash, see whether the request was rate-limited, dispatched, or actually consumed, and trace the failure mode without exposing plaintext PII.
📊 Analytics
Cross-portal rollups computed nightly by Portals::DailyRollupJob — aggregates PortalRecoveryAudit rows into PortalRecoveryDailyRollup, keyed by (business, portal, day).
Standard Metrics:
- Recovery requests per portal per window (7d / 30d / 90d)
- Sent / consumed / failed / rate-limited counts
- Per-portal recovery success rate
- Unique-identifier counts per portal per window
Trend Charts:
- Requested vs sent vs consumed
- Failed and rate-limited over time
Use Case: Spot a portal whose recovery success rate is dropping week over week — usually a sign the magic-link email is going to spam or the OTP SMS provider is silently failing.
🛡️ Security Signals
Surfaces patterns the audit log alone wouldn’t flag without manual scanning.
| Signal | Description |
|---|---|
| Repeat-failure IPs | Top N IPs by failure count over a tunable window |
| Identifiers near lockout | Most-flagged events per identifier hash |
| Cross-portal patterns | One identifier hitting multiple portals — possible enumeration |
| Recent invalid-token events | Token-tampering attempts surface immediately |
🎨 Branding
Per-business defaults the portals can inherit, stored on PublicPortalBranding.
| Feature | Description |
|---|---|
| Logo | Active Storage attachment, used as the portal header logo |
| Primary + accent color | Portal CTA buttons and accents |
| Font | Portal body font |
| Portal title | Default browser tab title |
| Support email | Visible on portal error / help screens |
| Footer text | Optional footer line for compliance / copyright |
| Live preview | Branding applies to a preview pane while editing |
🌐 Custom Domains
Map your own hostname to a portal — portal.acme.com → MangoApps Field Service Customer Portal, for example. Stored on PortalCustomDomain.
| Feature | Description |
|---|---|
| Hostname → portal mapping | One row per domain, tied to an owning portal |
| Per-domain verification token | DNS TXT record to prove ownership |
| Lifecycle | pending → verified → active (or revoked) |
| DNS / TLS / edge routing | Handled by ops; the model captures intent |
🤖 Portals AI Agent
A read-only help agent (Agents::PortalsHelpAgent) answers questions about portals from the Ask AI sidebar — features, configuration, and how the catalog relates to owning apps. Can be enabled or disabled per business via the agent_enabled setting.
⏰ Scheduled Jobs
| Job | What it does |
|---|---|
Portals::DailyRollupJob |
Nightly aggregation of audit rows into PortalRecoveryDailyRollup |
Portals::PruneAuditJob |
Prunes audit rows older than the configured retention window |
Limits & Specs
| Spec | Default |
|---|---|
| Rate-limit window | 60 minutes (configurable) |
| Max attempts per window per identifier | 5 (configurable) |
| Audit retention | 180 days (configurable) |
| Default recovery method | Magic link (per-portal override possible) |
| Allowed roles | Admin, Super Admin (configurable) |
User Roles & Permissions
| Role | Capabilities |
|---|---|
| Member / Manager | No access by default — Portals is a platform admin surface |
| Admin | Browse catalog, configure identity & recovery, view audit log + analytics, manage branding, manage custom domains, export CSV |
| Super Admin | Same as Admin |
The allowed roles list is configurable per business; defaults to admin and super_admin.
How We Compare
The Portals umbrella sits at an unusual layer — most platforms ship per-app portals without a unified cross-app catalog or shared identity-recovery layer.
| Feature | MangoApps Workforce | Stand-alone portal builders | Custom-built per-app |
|---|---|---|---|
| Cross-app portal catalog | ✅ | ❌ | ❌ |
| Unified identity & recovery layer | ✅ | ⚡ | ❌ |
| PII-safe audit (hashed identifiers) | ✅ | ⚡ | ❌ |
| CSV export of audit events | ✅ | ⚡ | ❌ |
| Cross-portal analytics rollup | ✅ | ❌ | ❌ |
| Per-business branding defaults | ✅ | ✅ | ⚡ |
| Custom domain mapping | ✅ | ✅ | ⚡ |
| Legend: ✅ Included | ❌ Not Available | ⚡ Limited / per-portal only |
Why MangoApps Workforce?
- 🔗 Unified Platform — Portals reads catalog state from each owning app — flipping a portal on or off still happens where the feature lives, not in a separate stack.
- 🧾 PII-safe by Default — SHA-256 hashing of every identifier in the audit log; plaintext email or phone never leaves the request.
- 🤖 AI-Native — Built-in Portals help agent in Ask AI; no extra config or third-party plug-in.
Getting Started
For Administrators
- Enable the app — In Admin → Apps Marketplace, find Portals and toggle it on. Portals is a platform-tier app, so enable only if you have multiple public-facing portals to manage.
- Open the catalog — Admin → Portals → Catalog. Confirm every public surface in your business is listed and the status matches what you expect.
- Configure identity & recovery — Set the default recovery method, rate-limit window, max attempts per window, and audit retention. Per-portal overrides are available where the underlying portal supports both magic-link and OTP.
- Set branding defaults — Upload your logo, set primary / accent colors, support email, and footer text. The preview pane shows how each portal will render.
- (Optional) Add custom domains — If you want portals served from your own hostname, add a custom domain row, copy the verification TXT record into your DNS, and verify. Ops handles the TLS / edge routing.
- Bookmark the audit log — When a recovery anomaly comes in, you’ll want it one click away.
Best Practices
- ✅ Don’t enable Portals if you only have one portal live — the umbrella adds value when there are several public surfaces; under that, the owning app’s settings are enough.
- ✅ Tighten rate limits during incidents — drop the max-attempts-per-window if you see a spike in failed recovery; back off afterwards.
- ✅ Filter the audit log by identifier hash, not IP — the hash is the stable user identity; IPs rotate.
- ✅ Export CSV for SOC 2 / compliance reviews — last-90-days of recovery events is usually what auditors ask for.
- ✅ Treat Portals catalog as read-only — toggle individual portals on or off in the owning app, not here.
- ✅ Start with magic-link as the default — easier UX; flip per-portal to OTP only where you need a stronger factor.
Frequently Asked Questions
Q: Does Portals own the toggles for each individual portal?
A: No. Each owning app keeps its own portal enable toggle (Field Service has its customer-portal toggle, Recruiting has its candidate-portal config, etc.). Portals only reads — the catalog surfaces state from each app, but flipping a portal on or off still happens in the owning app’s settings. This keeps the source of truth where the feature lives.
Q: What does “Identity & Recovery” actually control?
A: Three things — (1) the default recovery method (magic-link vs OTP) for portals that support both, (2) rate-limit thresholds for the PortalIdentityRecovery concern, and (3) audit retention. Per-portal overrides are possible: the umbrella sets defaults, individual portals can override.
Q: Is the audit log enough for compliance?
A: Every recovery event (request, send, failure, rate-limit, consume, invalid-token) is logged with timestamp, IP, user-agent, and SHA-256 hash of the identifier — never plaintext. Configurable retention (default 180 days). CSV export available. For SOC 2 / HIPAA-style audits this is generally sufficient; check with your compliance team for industry specifics.
Q: Why is this a separate marketplace app instead of always-on?
A: Two reasons. First, packaging it as an app gives it real surface area — admins discover it, configure it, see analytics. An invisible “platform feature” gets ignored. Second, it gates behind a license so it ships as part of the platform tier rather than free-with-everything; the value (cross-portal control, audit, analytics) justifies the gate.
Q: What if I only have one portal enabled?
A: You probably don’t need Portals yet. The umbrella adds the most value when you have three or more public-facing portals; under that, the owning app’s built-in settings are usually enough.
Related Resources
- Apps Overview — Browse the full marketplace catalog
- Field Service Suite — Publishes the Customer Portal that Portals catalogs
- Offboarding Hub — Publishes the Former Employee Portal
- Job Board — Publishes the Candidate Portal
One umbrella, every portal — catalog, recovery, audit, and analytics in a single home.