Impersonation (Delegation)

BitzOrcas supports operator impersonation through the Delegation subsystem. Authorized operators can temporarily act on behalf of another user — useful for customer support and administration.

Architecture

Operator (admin) → DelegationTokenService → Generate Token
                                                │
Target User ←──── DelegationTokenMiddleware ←───┘
     │
     ▼
Request executes as target user
     │
     ▼
Audit trail: operator_id + target_user_id

Components

Delegation grant entity

public class DelegationGrantEntity : EntityBase
{
    public string OperatorId { get; set; }
    public string TargetUserId { get; set; }
    public string TenantId { get; set; }
    public DateTimeOffset ExpiresAt { get; set; }
    public string? Scope { get; set; }
    public bool IsRevoked { get; set; }
}

Token lifecycle

1. Grant creation: Operator requests impersonation of a target user
2. Token generation: DelegationTokenService creates a time-limited token
3. Token validation: DelegationTokenMiddleware validates token in each request
4. Context injection: ICurrentUser reflects the target user’s identity
5. Audit: All actions logged with both operator and target user
6. Expiry: Token automatically expires after TTL

Middleware position

ExceptionHandler → CorrelationId → Authentication → DelegationToken
→ TenantResolution → Audit → Authorization → RateLimiter → Endpoints

Delegation validation occurs after authentication but before tenant resolution — the operator must be authenticated first.

Security considerations

• Grants have configurable TTL (default: 1 hour)
• Grants can be revoked immediately
• Scope restrictions limit what the operator can do
• All impersonated actions are audited
• Only operators with delegation.grant permission can create grants

Current limitations

• EF Core path does not support delegation yet (SqlSugar only)
• Background job impersonation uses BeginScope instead of middleware

See also

• Identity module — Permission model
• Multitenancy deep dive — Tenant context