Kafka Message Stream Viewer Architecture

The Kafka Message Stream Viewer lets an authorized AxonOps user inspect messages from Kafka topics without opening direct Kafka access from the user's workstation.

Message access is controlled in AxonOps, integrated with the user's enterprise identity, and enforced with a short-lived JWT token that carries the list of Kafka topics the user's role is allowed to access. The Kafka data remains in your environment.

Kafka messages are streamed securely over HTTPS between the browser and the axon-agent. Message payloads are not routed through, persisted by, or exported to the AxonOps control plane. They remain within the corporate infrastructure while being inspected by the authorized user.

×

×

Click the diagram to open a larger modal view.

Components

Component	Role
Corporate SSO / identity provider	Authenticates the user and supplies the identity used by AxonOps access control.
AxonOps Dashboard	Provides the Stream and Stream Access pages used by operators.
AxonOps Server	Authorizes stream requests, evaluates stream access grants, and pushes a short-lived JWT containing the approved topic list to the selected axon-agent for the stream operation.
Browser	Opens the stream session and receives approved message data over HTTPS from the selected axon-agent.
axon-agent	Runs in the Kafka environment, receives and validates the JWT from AxonOps, and performs the Kafka read operation only if the requested topic is included in the token's topic allow-list.
Kafka brokers	Store the topic partitions and messages being inspected.
Kafka topics and partitions	The source of messages shown in the stream table.

Enterprise security model

The Message Stream Viewer is designed so message-level access is explicit, time limited, and bound to the user's authenticated identity.

The security model combines the following controls:

Layer	Control
Enterprise authentication	Users authenticate through the configured corporate SSO provider before using AxonOps.
AxonOps authorization	AxonOps stream access grants define which users or groups can stream from which topic scopes.
Short-lived JWT authorization	AxonOps issues a JWT containing the list of Kafka topics approved for the user's role. The token has a limited time span and is not a standing credential.
Agent-side enforcement	AxonOps pushes the JWT to the axon-agent. The agent validates the token and permits reads only for topics included in the encoded allow-list.
Encrypted transport	Message data is streamed over HTTPS between the browser and the axon-agent.
Data residency	Kafka message payloads stay inside the corporate infrastructure and are not routed through or stored by the AxonOps control plane.
Audit logging	AxonOps records security-relevant stream access activity, including stream token creation and RBAC rule changes, so access can be reviewed after the event.

This keeps Kafka message inspection behind both enterprise identity controls and AxonOps topic-level authorization.

Security audit logging

AxonOps records audit events for Message Stream Viewer security activity. These events provide an enterprise audit trail for who was granted message access, who generated stream authorization tokens, and which Kafka cluster or topic scope was involved.

The audit log view can be filtered to Audit events and reviewed by time range. Stream Viewer audit entries include security-relevant actions such as:

• Stream token creation.
• Stream access RBAC rule creation.
• Stream access RBAC rule removal.
• The authenticated AxonOps user associated with the action.
• The Kafka cluster context.
• The topic or access object values involved in the action.

This audit trail supports enterprise governance because the platform records both the authorization configuration changes and the runtime creation of stream tokens. A reviewer can correlate SSO identity, AxonOps Stream Access grants, token issuance, and the Kafka topic scope used for message inspection.

Note

Audit logging complements token enforcement. A valid, short-lived JWT is still required before the axon-agent streams messages, and the audit log records the security activity around issuing those stream authorizations.

SSO and identity

AxonOps uses the authenticated user's identity when evaluating stream access. In an enterprise deployment this identity can come from the organization's SSO provider.

The user's SSO session establishes who the user is. The Stream Access configuration then controls what that user, or a group containing that user, is allowed to inspect.

Note

SSO authentication does not by itself grant Kafka message visibility. A matching Message Stream Viewer access grant is still required.

Stream access grants

Message streaming is not available to every user by default. Access is granted from the Stream Access page.

An access grant defines:

• The topic scope, either a single topic or all topics in the selected Kafka cluster.
• The member type, either a user or a group.
• The AxonOps username or group name that can stream messages.

Users without a matching grant cannot use the stream viewer for that topic scope.

For sensitive topics, prefer topic-specific grants instead of cluster-wide grants.

JWT authorization tokens

When an authorized user starts a stream workflow, AxonOps generates a JWT for the approved message stream request.

The JWT contains the list of Kafka topics the user's role is allowed to access. That topic list is derived from the user's authenticated identity, role or group membership, and the matching Stream Access grants.

The topic list is an allow-list. The axon-agent permits streaming only when the requested topic is present in the JWT. If the user requests a topic that is not encoded in the token, the agent denies the stream request before reading from Kafka.

The token is intentionally time limited. It has a finite validity period, so it cannot be reused indefinitely. When the token expires, a new authorized request must be made through AxonOps before streaming can continue.

The token is used as a delegated authorization artifact:

• AxonOps issues it after checking the user's authenticated identity, role or group membership, and stream access grants.
• AxonOps pushes it to the selected axon-agent for the stream session.
• The browser connects to the selected axon-agent for message streaming, but does not need direct Kafka credentials.
• The axon-agent validates the token before reading from Kafka.
• The agent enforces the topic allow-list encoded in the token.

The token should be treated as sensitive for its lifetime. It authorizes message access only for the encoded topic allow-list and is delivered from AxonOps to the axon-agent for enforcement.

Secure message access flow

1. An administrator grants stream access to a user or group.
2. The user authenticates to AxonOps through the configured enterprise SSO flow.
3. The authorized user opens the Stream page.
4. The user selects a topic and configures the stream position.
5. AxonOps evaluates the user's Stream Access grants.
6. If access is allowed, AxonOps generates a short-lived JWT containing the topic allow-list approved for the user's role.
7. AxonOps pushes the JWT to the selected axon-agent.
8. The axon-agent validates the JWT and checks that the requested topic is included in the token's topic allow-list.
9. The agent reads from Kafka using its access inside the Kafka environment.
10. Messages are streamed from the agent to the browser over encrypted HTTPS and displayed in the stream table.
11. The user stops the stream or disconnects when inspection is complete.

Agent-side enforcement

The axon-agent is the enforcement point closest to Kafka.

Before reading from Kafka, the agent checks that the JWT pushed by AxonOps is valid for the request. The token must still be within its allowed time span and must include the requested topic in its encoded topic allow-list.

If the token is missing, expired, invalid, or does not include the requested topic, the agent does not stream messages.

This design prevents the browser from gaining direct Kafka credentials. Authorization is represented by the time-limited JWT pushed from AxonOps to the axon-agent for the approved stream operation.

The message stream itself is encrypted in transit over HTTPS between the browser and the axon-agent. The agent reads from Kafka inside the corporate environment and streams the approved messages directly to the authorized browser session. Kafka message payloads do not leave the corporate infrastructure through the AxonOps control plane.

Transport and data boundary

The Message Stream Viewer separates the control plane from the data path.

AxonOps controls identity, access grants, token issuance, token delivery to the axon-agent, and audit logging. The Kafka message payloads are streamed by the axon-agent directly to the browser over HTTPS after the agent validates the short-lived JWT.

This means:

• Kafka messages are encrypted in transit between the browser and the axon-agent.
• Kafka broker credentials and stream JWTs are not distributed to the browser.
• The AxonOps control plane authorizes the stream but does not proxy or persist message payloads.
• Message contents remain within the corporate infrastructure during inspection.

Stream position

The stream viewer supports several ways to choose where message reading begins:

Partition mode	Use when
Earliest	You want to start from the earliest available retained messages.
Latest	You only want messages produced after the stream starts.
Specify Partition Offsets	You need exact control of the starting offset for selected partitions.
Specify Partition Timestamps	You want to start from messages at or after a timestamp.

The offset and timestamp modes expose partition-specific controls so you can select which partitions are included.

Optional processing

The stream viewer can also apply optional processing before messages are displayed:

• Schema encoded: use when topic values are encoded and require a schema-aware display path.
• Filter stream: apply a regular expression filter to limit the displayed messages.
• Limit returned rows: cap the number of messages returned to the UI.

Security controls and recommendations

Least privilege

Grant access only to the exact users and groups that require message-level visibility.

Use topic-specific grants for sensitive topics. Use all-topic grants only for trusted operational roles that need broad inspection access.

Time-limited authorization

JWT tokens generated for stream access have a limited time span. This reduces exposure if a token is captured and ensures long-running or later stream activity must be re-authorized.

Do not treat a stream token as a permanent credential. It is valid only for the encoded topic allow-list and validity period.

Separation from Kafka credentials

Users do not need direct Kafka broker credentials on their workstation to inspect messages through the viewer.

The agent reads from Kafka from within the Kafka environment. The user's authorization is represented by the JWT issued by AxonOps and pushed to the axon-agent, not by distributing Kafka credentials to the browser.

Data handling

Streamed messages are application data. They may include personally identifiable information, credentials, secrets, or regulated records.

Use these controls together:

• Grant stream access only to users and groups that need message-level visibility.
• Prefer topic-specific grants for sensitive topics.
• Limit returned rows when inspecting high-volume or sensitive topics.
• Filter streams to the narrowest practical message set.
• Avoid copying message contents into tickets, chats, or logs unless the data handling policy allows it.
• Revoke grants when the investigation or operational task is complete.

Operational governance

Review Stream Access grants regularly. Remove grants that are no longer required, especially broad all-topic grants.

Align Message Stream Viewer access with the same operational controls used for production data access:

• SSO group membership reviews.
• Joiner, mover, and leaver processes.
• Incident response and break-glass procedures.
• Audit and compliance review of users with message-level access.

Failure and expiry behavior

If the JWT expires during or before a streaming operation, the stream must be re-authorized through AxonOps.

If a user's group membership or Stream Access grant changes, newly issued tokens reflect the updated access state. Existing tokens remain bounded by their short validity period.

If the selected topic is not included in the token's topic allow-list, the agent denies the stream request.