Impersonation

The SDK supports partner impersonation — a controlled, accountable mechanism that lets an authorized partner act as a colleague without logging out. Support staff reproduce a colleague's view to diagnose an issue; admins verify what a colleague can see; the acting partner never leaves their own login.

Impersonation is a first-class intent, not a middleware toggle. A principal triggers it by dispatching the built-in partner.impersonate intent; the intent authorizes the switch against a stored delegation grant and, on success, lands the principal on the Launchpad as the new actor.

A delegation is granted in the Partners app and carries its own window. Outside that window it does not exist — nothing has to be revoked.

Principal vs actor

Every request carries two identities on the runtime SdkContext:

• principal — who is really logged in (the person at the keyboard). It never changes during a session.
• actor — whose context the request executes in. It equals the principal normally, and is set to the impersonated partner while impersonating.

Authorization always resolves against the actor's grants — you see exactly what the target sees — while the principal stays the accountable identity. Impersonation never chains: the target is always resolved from the principal, never from an already-impersonated actor.

Delegations — who may impersonate whom

Impersonation is not an open capability; it is granted per pair, ahead of time. A delegation is a time-bound grant that names a delegate partner (who may act) and a target partner (the identity acted as):

• it is time-bound (valid_from / valid_until) and records who granted it,
• a partner cannot be granted a delegation to impersonate itself,
• active windows may not overlap for the same pair,
• grants form an accountable history: an active or elapsed delegation is end-dated (delineated), never erased; only a future, not-yet-started grant may be cancelled outright,
• granting and ending a delegation are #[Act]-gated operations — grantDelegation and delineateDelegation, attached to the LocalAdmin role.

The SDK does not restrict whom a delegation may name. ImpersonationService::grant() checks only the two rules above (no self-delegation, no overlap), and the Partners app offers any partner with a login as a candidate. Who may act as whom is the decision of the administrator who grants it.

Delegations are administered from a partner's record in the Partners app — the Delegations panel (In / Out) — which reads and writes them through the SDK's impersonation service.

The flow

1. The principal opens their impersonation targets (the delegations granted to them) from the shell's identity menu.
2. Selecting a target dispatches the partner.impersonate intent.
3. The intent's authorize() checks for an active delegation from the principal to that target.
4. On success the actor on the SdkContext becomes the target, and the handler answers with a full-page redirect to the named route dashboard. The SDK registers that route itself (GET /ui5/dashboard, web + auth middleware); it redirects to the Launchpad — the mandatory safe-landing, because the target may not have access to the app the principal was in. The same route serves as the default post-login landing.
5. Ending impersonation restores the principal as the actor and re-lands on the Launchpad the same way.

Impersonation is session-scoped: it lives in the session, and ending or leaving it fully restores the principal's own context.

See also

• Domain Model — actor vs principal in the runtime context