Keycloak User Query

A terminal UI tool to display all attributes for a Keycloak user, including attributes inherited from group memberships.

Installation

pip install -r requirements.txt

Python 3.10 or later is required.

Configuration

Connection details can be provided via environment variables or CLI flags. CLI flags take precedence over environment variables.

Environment variable	CLI flag	Description
KC_BASE_URL	--base-url	Keycloak base URL (no trailing /)
KC_REALM	--realm	Realm name
KC_CLIENT_ID	--client-id	Service account client ID
KC_CLIENT_SECRET	--client-secret	Service account client secret
KC_NO_VERIFY	--no-verify	Disable TLS certificate verification (self-signed certs)

Authentication uses the OAuth2 client credentials grant. The service account associated with KC_CLIENT_ID requires read access to the realm's users and groups.

Usage

# Search by username
python keycloak_user_query.py --username alice

# Search by email
python keycloak_user_query.py --email alice@example.com

# Search by Keycloak user ID
python keycloak_user_query.py --id 550e8400-e29b-41d4-a716-446655440000

# Override connection settings inline
python keycloak_user_query.py --base-url https://keycloak.example.com \
    --realm myrealm --client-id query-client --client-secret s3cr3t \
    --username alice

Interface

The TUI is split into three areas:

• Top bar — user summary: username, email, full name, enabled status, group count, and ID.
• Left pane — rendered attributes: all attributes merged from the user account and all groups, displayed as a tree with expandable multi-value entries.
• Right pane — raw attributes: attributes listed by source in a tree — user attributes first, then each group's attributes under their own node.

Navigation

Key	Action
Tab	Move focus to the next pane
Shift+Tab	Move focus to the previous pane
↑ / ↓	Navigate within the focused pane
Enter	Select item and sync to other pane
Space	Expand/collapse tree nodes
s	Toggle source annotations (left pane)
k	Toggle full/shortened attribute keys
j	Toggle JSON view (left pane)
f	Find in attributes (fuzzy search)
n	Jump to next find match
N	Jump to previous find match
/	Search for a different Keycloak user
Escape	Clear selection and find results
q	Quit

Cross-pane highlighting

Selecting an item in either pane highlights related items in the other pane:

• Select an attribute (left or right pane) → the other pane scrolls to and highlights the matching attribute.
• Select a group node (right pane) → the left pane scrolls to the first attribute sourced from that group.
• Press Escape to clear all highlights and find results.