Fuzzball Documentation
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

Impersonating Users for Troubleshooting

Cluster administrators can temporarily assume the identity of any user in any organization to troubleshoot issues, reproduce bugs, or verify permissions. When impersonating a user, all actions are performed as that user, but the administrator’s identity is preserved in audit logs.

Overview

A cluster administrator can obtain a JWT token for any user in the system. The impersonation session includes both the target user’s identity and the admin’s identity (embedded in an RFC 8693 act claim), ensuring full audit trails of privileged actions.

Use Cases

  • Troubleshooting: Reproduce an issue exactly as the user experiences it, with their permissions and context
  • Verification: Confirm that group memberships, volume access, and resource definitions work as intended for a specific user
  • Support: Assist users by directly interacting with their workflows and data
  • Testing: Validate policy changes or new features from the perspective of different user roles

Security and Audit Considerations

Privileged Operation: Impersonation grants full access to another user’s data and resources. Organizations should establish clear policies for when and why impersonation should be used.

All actions taken during an impersonation session are logged with both the target user’s identity (the user being impersonated) and the administrator’s identity (the admin performing the impersonation). This dual-identity audit trail ensures accountability and traceability for all privileged operations.

Audit writes are bounded so that an unavailable audit service cannot stall the platform. If the audit service does not respond within 5 seconds, the action still completes and its audit event is not recorded. Where a complete audit trail is required, monitor the audit service’s availability.

Actions that issue credentials during an impersonation are the exception: each is refused unless its audit record is written, so while the audit service is unavailable they fail. They are:

  • Starting an impersonation, and switching accounts while impersonating.
  • Starting a workflow while impersonating, and refreshing that workflow’s token.

The workflow rules follow the workflow: a job in a workflow you started while impersonating is refused the same way when it starts a workflow of its own or refreshes its token, even after you have stopped impersonating. A workflow already running keeps its current token until it expires, so a short audit outage only delays a refresh; an outage that outlasts the token leaves the job without API access. Returning to your own identity still works.

While impersonating, you cannot generate an endpoint token (fuzzball endpoint generate-token, or the endpoint panel’s token button in the web UI): the request is refused with “an endpoint token cannot be minted while acting as another user”. An endpoint token is a credential in the user’s name alone that can outlive the impersonation session. You can still reach the user’s endpoints directly while impersonating.

Impersonating Users via CLI

The Fuzzball CLI provides the fuzzball context assume-user command for user impersonation.

Prerequisites

  • Active Fuzzball context with cluster administrator credentials
  • Organization ID and User ID (both UUIDs) for the target user

Obtaining User and Organization IDs

You can retrieve the necessary UUIDs from the Web UI by navigating to the organization management panel and viewing user details, or consult your cluster administrator.

Assuming User Identity

To impersonate a user, run:

$ fuzzball context assume-user <organization-id> <user-id>

Example:

$ fuzzball context assume-user 550e8400-e29b-41d4-a716-446655440000 6ba7b810-9dad-11d1-80b4-00c04fd430c8

This command:

  1. Exchanges your cluster-admin credentials for a user JWT
  2. Updates your active context to use the new token
  3. All subsequent CLI commands run as the impersonated user

The command will output:

Now acting as user 6ba7b810-9dad-11d1-80b4-00c04fd430c8 in organization 550e8400-e29b-41d4-a716-446655440000 on context "your-context-name".

Verifying Impersonation

After assuming a user identity, you can verify the active context:

$ fuzzball context show

The output will show the impersonated user’s details and display a message indicating that you are acting as another user.

Returning to Admin Identity

To return to your cluster administrator identity, log in again:

$ fuzzball context login

This will re-authenticate with your admin credentials and restore your original context. If a fuzzball context assume-user command is still waiting for its response when you log in again from another terminal, it stops and asks you to run it again rather than replacing the new login.

Example Workflow

# 1. Start as cluster admin
fuzzball context show
# (shows current context details)

# 2. Assume user identity
fuzzball context assume-user 550e8400-e29b-41d4-a716-446655440000 6ba7b810-9dad-11d1-80b4-00c04fd430c8
# Now acting as user 6ba7b810-9dad-11d1-80b4-00c04fd430c8 in organization 550e8400-e29b-41d4-a716-446655440000 on context "your-context-name".

# 3. Troubleshoot as the user
fuzzball workflow list
fuzzball volume list
# All commands now run with the user's permissions

# 4. Return to admin identity
fuzzball context login
# (re-authenticates with admin credentials)

Impersonating Users via Web UI

The Fuzzball Web UI provides a graphical interface for user impersonation.

Accessing the Impersonation Feature

Cluster administrators can use the Assume user identity option in the Web UI:

  1. Log in to the Fuzzball Web UI with cluster administrator credentials
  2. Open the user menu (your avatar, top right)
  3. Click Assume user identity
  4. A modal dialog appears

Using the Impersonation Modal

The modal requires the UUIDs of the target organization and user:

  1. Organization ID: Paste the UUID of the target organization
  2. User ID: Paste the UUID of the target user
  3. Confirm: Click Assume user

Both fields validate the input as a UUID before the confirmation button enables. A name-based picker is planned for a future release; for now both fields require raw UUIDs (see Obtaining User and Organization IDs above).

The Web UI will:

  • Exchange your admin credentials for a user JWT
  • Update the session to act as the selected user
  • Reload the page so every subsequent request uses the new token
  • Display a banner at the top of the page showing the assumed identity

Assumed Identity Indicator

When impersonating a user, the Web UI displays a persistent warning banner at the top of every page. The banner shows:

  • The email (or subject UUID) of the target user you are acting as
  • The email (or subject UUID) of the cluster admin the session is attributed to
  • A reminder that “All actions are attributed to this user and audit-logged to you”
  • A Return to admin session button

The banner is rendered outside the route outlet, so it cannot be hidden by navigation.

Exiting Impersonation

To return to your admin identity, click Return to admin session in the banner. Fuzzball ends the impersonation session and restores your cluster administrator context.

An impersonation started before an upgrade that added this check cannot be exited this way. If Return to admin session fails, log out, and log back in with your admin credentials.

Example Web UI Workflow

  1. Start: Logged in as cluster administrator
  2. Look up UUIDs: Note the target organization’s UUID and the target user’s UUID (see Obtaining User and Organization IDs)
  3. Open the modal: Settings → Assume user identity
  4. Paste UUIDs: Organization ID: 550e8400-e29b-41d4-a716-446655440000, User ID: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
  5. Confirm: Click Assume user — the page reloads into the assumed session
  6. Banner appears: Shows the target user’s email and the admin’s email
  7. Troubleshoot: Navigate workflows, volumes, etc. as the assumed user
  8. Exit: Click Return to admin session in the banner to restore your admin session

Programmatic Impersonation (SDK)

For advanced use cases, you can use the Fuzzball SDK to programmatically impersonate users.

The AdminAuthService.AssumeUserIdentity RPC accepts:

  • organization_id (UUID string)
  • user_id (UUID string)

And returns:

  • jwt (string) — a JWT token for the target user

Use the returned JWT as the bearer token for subsequent API calls to act as the impersonated user. Consult your language-specific SDK documentation for the exact client initialization and session management details, and see the SDK Coding Examples section for additional examples.

Best Practices

  1. Document impersonation sessions: Maintain an internal log of when and why impersonation was used
  2. Minimize duration: Exit impersonation as soon as troubleshooting is complete
  3. Communicate with users: Inform users if you need to access their data (per your organization’s policy)
  4. Review audit logs: Regularly audit impersonation events for compliance and security
  5. Restrict admin access: Limit cluster-admin credentials to trusted personnel

Troubleshooting

Error: “Permission Denied”

Ensure you are authenticated as a cluster administrator. Only cluster admins can impersonate users. An impersonation cannot start another: return to your admin session first (in the CLI, run fuzzball context login).

Error: “impersonation is unavailable: its audit record could not be written”

The audit service did not record the start of the impersonation, so no token was returned. Check that the audit service is running and reachable, then try again.

Error: “account selection during impersonation is unavailable: its audit record could not be written”

The audit service did not record an account switch made while impersonating, so no token was returned. Check that the audit service is running and reachable, then try again.

Error: “Invalid Organization ID or User ID”

Verify that both IDs are valid UUIDs and that the user exists in the specified organization. Consult your cluster administrator or use the Web UI to confirm the correct UUIDs.

Indicator Not Appearing (Web UI)

Ensure you have the latest version of the Web UI. If the indicator still does not appear, contact your cluster administrator.

Cannot Exit Impersonation (CLI)

Run fuzzball context login to re-authenticate with your admin credentials. If the context file is corrupted, you may need to delete it and reconfigure. Consult fuzzball context --help for the exact configuration file location on your system.