Skip to main content

​
Context

Support cannot debug what it cannot see. Screenshots and screen shares are slow and often impossible, so every serious B2B platform ends up with some form of impersonation. The question is never whether, it is whether it is accountable. Done casually — a superuser flag, no record — it is an undetectable read of every customer’s data by anyone with an internal account. That is a breach waiting for a disgruntled employee, and under Ley 21.719 it is exactly the kind of access an audit asks about. The design turns it from a liability into a trust signal by making it impossible without a reason and a time box, and visible to the tenant in their own audit trail. The tenant is the party with the incentive to notice an unexplained session, so they are the one who gets to see it. This is deliberately the last feature in the module: it should not exist before the audit trail that constrains it does.

​
Scope (normative)

  • identity.impersonations, append-only, with operator, target, reason and time box.
  • A session that is explicitly an impersonation, never indistinguishable from a real one.
  • A persistent visual banner in the console for the whole duration.
  • Automatic expiry and manual end.
  • Full visibility in the tenant’s own audit trail.
  • A restricted action set: read-only by default.

​
Non-scope (normative)

  • Tenant-to-tenant impersonation. Never, under any configuration.
  • Impersonating a specific individual user’s identity. The operator acts as an operator scoped to the organization, not as that person — attributing an operator’s actions to a customer’s employee is falsifying an audit trail.
  • Silent or invisible access. There is no configuration that hides it.

​
Behaviour (normative)

  1. Starting an impersonation requires the identity.impersonation.start permission — Ops only — plus re-authentication, plus a free-text reason of at least 20 characters. The length floor exists because “debugging” is not a reason.
  2. Every impersonation is time-boxed, default 60 minutes, hard maximum 4 hours. It expires automatically; there is no extend, only a new one with a new reason.
  3. The session is marked as an impersonation and every action taken under it is attributed to the operator, never to a user of the tenant. The audit actor is the operator, with the impersonation id attached.
  4. Read-only by default. Write actions require a separate identity.impersonation.write permission and are individually audit-logged with heightened visibility. Most support problems are diagnosed by looking.
  5. Certain data is never visible under impersonation: full national IDs, API key secrets, MFA secrets and recovery codes. An operator seeing a customer’s screen does not need their customers’ identity documents.
  6. The console shows a persistent, unmissable banner for the entire session, naming the organization and the remaining time.
  7. The tenant sees every impersonation in their own audit trail, with operator, reason, duration and actions taken. It is not filtered out, ever.
  8. Starting one notifies the organization’s owners by email. A tenant learning about access only if they go looking is not transparency.
  9. identity.impersonations is append-only. A record cannot be edited or deleted by anyone, including Ops.
  10. An impersonation can never reach another organization, and never the member realm.

​
Data (normative)

​
API (normative)

A tenant owner can end an impersonation of their own organization. If they are uncomfortable with what they see happening, they get to stop it.

​
Events (normative)

identity.impersonation.started and identity.impersonation.ended. The started event drives an immediate notification to the organization’s owners through messaging.

​
Acceptance criteria (normative)

  1. Starting without a reason, with a reason under 20 characters, or without re-authentication is rejected in each case.
  2. An impersonation expires automatically at its time box; requests afterwards are rejected.
  3. Beyond the 4-hour maximum, creation is rejected.
  4. Every action under impersonation is audited with the operator as actor and the impersonation id attached — never with a tenant user as actor.
  5. A write attempt without identity.impersonation.write is rejected.
  6. Full national IDs, key secrets and MFA secrets are unreadable under impersonation, whatever roles the operator holds.
  7. The tenant’s own audit trail shows the impersonation with reason and duration.
  8. Organization owners receive a notification within seconds of the start.
  9. A tenant owner can end an impersonation of their organization.
  10. Negative: no configuration, flag or endpoint hides an impersonation from the tenant, and no impersonation record can be edited or deleted.

​
Execution

Single slice, synchronous command. F1b, and last in the module by design. The banner is a frontend/console concern driven by the session flag; notifications go through messaging.

​
Open questions

​
Changelog

​
Delivery record

Not implemented yet.