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.

User impersonation allows a cluster administrator to 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.

• 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

Privileged Operation: User impersonation is a powerful capability that 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.

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

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

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.

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".

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.

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

fuzzball context login

This will re-authenticate with your admin credentials and restore your original context.

# 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)

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

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 Settings menu (gear icon)
3. Click Assume user identity
4. A modal dialog appears

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 the confirmation button

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

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”
• An Exit assumed session button

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

To return to your admin identity, click Exit assumed session in the banner. This logs you out of the impersonation session; log back in with your admin credentials to restore your cluster administrator context.

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 the confirmation button — 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 Exit assumed session in the banner, then log back in as admin

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

The new AdminAuthService.AssumeUserIdentity RPC accepts:

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

And returns:

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

Example (Go SDK pattern):

import "fuzzball/fbapi"

// Initialize the admin auth service
svc := fbapi.NewAdminAuthService(address, dialOptions...)

// Assume user identity
resp, err := svc.AssumeUserIdentity(ctx, &fbapi.AssumeUserIdentityRequest{
    OrganizationId: "550e8400-e29b-41d4-a716-446655440000",
    UserId:         "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
})
if err != nil {
    // handle error
}

userJWT := resp.Jwt
// Use the JWT for subsequent API calls as the impersonated user

Consult your language-specific SDK documentation for the exact client initialization and session management details. See the SDK Coding Examples section for additional language-specific examples.

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

Ensure you are authenticated as a cluster administrator. Only cluster admins can impersonate users.

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.

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

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.