Authentication and JWT

Relevant source files

The following files were used as context for generating this wiki page:

• src/commands.rs
• src/models.rs
• src/lib.rs
• README.md
• examples/tauri-app/src/App.svelte
• permissions/schemas/schema.json

The Tauri Centrifugo plugin utilizes JSON Web Tokens (JWT) as the primary mechanism for securing real-time communication between the client and the Centrifugo server. Authentication is integrated into the connection lifecycle, allowing for both initial secure handshakes and dynamic credential updates during an active session.

The scope of authentication within this plugin covers connection-level identity verification and channel-specific subscription authorization. By leveraging JWTs, the system ensures that only authorized users can establish WebSocket connections and interact with restricted message channels.
Sources: README.md:12-18, src/lib.rs:13-17

Authentication Architecture

The authentication flow is bridged between the Tauri frontend (JavaScript/TypeScript) and the Rust backend. The frontend provides the JWT, which is then passed through Tauri's command system to the tokio-centrifuge based core logic for server-side validation.

Data Structures for Auth

Several key models define how authentication data is structured and transmitted:

Structure	Field	Type	Description
StartConfig	token	Option<String>	The initial JWT used during the connect command.
ChannelConfig	token	Option<String>	A channel-specific JWT for private channel subscriptions.
RefreshRequest	token	String	The new JWT used to update credentials without disconnecting.
SubRefreshRequest	token	String	A new token specifically for renewing a channel subscription.

Sources: src/models.rs:46-73, src/models.rs:135-155

Connection Flow with JWT

When a client initiates a connection, the JWT is included in the StartConfig. The following sequence illustrates the interaction between the Frontend, the Tauri Plugin, and the Centrifugo Server.

The plugin manages the transition from connecting to connected or error based on the validation result of the provided token.
Sources: src/commands.rs:34-53, examples/tauri-app/src/App.svelte:78-112

Token Management Operations

The plugin provides specific commands to manage the lifecycle of a JWT, allowing for initial setup and subsequent updates.

Initial Authentication

Authentication begins with the connect command. If a token is provided in the configuration, the plugin uses it to authenticate the WebSocket connection. If omitted, the connection proceeds as anonymous (if the server allows it).
Sources: src/commands.rs:34-45, src/models.rs:56-58

Dynamic Token Updates

To handle token expiration or permission changes without disrupting the user experience, the plugin supports updating the token on the fly.

1. set_token: Updates the JWT in the current session. This allows the backend to use the new credentials for subsequent operations.
2. refresh: (Interface defined, marked as NotImplemented in command implementation) Intended for refreshing the main connection token.
3. sub_refresh: (Interface defined, marked as NotImplemented in command implementation) Intended for renewing tokens for specific private channels.

Permission and Security Scopes

Security is enforced at the Tauri layer through a permission schema. Access to authentication-related commands must be explicitly granted in the Tauri application's capability configuration.

Auth Command Permissions

The following identifiers in the permission schema control access to authentication features:

• allow-set-token: Enables the frontend to call the set_token command.
• allow-refresh: Enables the refresh command.
• allow-sub-refresh: Enables the sub_refresh command.

Default Security Configuration

The default permission set for the plugin includes these authentication commands by default to ensure standard functionality is available out-of-the-box while maintaining the ability for developers to restrict them if necessary.
Sources: permissions/schemas/schema.json:347-360, permissions/schemas/schema.json:443-460

Implementation Example

In a typical Svelte/Tauri application, the token is managed as part of the connection state.

// Initial connection with token
await connect({
  url: 'ws://localhost:8001/connection/websocket',
  token: 'my.jwt.token',
  channels: ['updates']
});

// Updating token later
async function updateAuth(newToken: string) {
  try {
    await setToken(newToken);
    console.log('Token updated successfully');
  } catch (error) {
    console.error('Failed to update token:', error);
  }
}

Sources: examples/tauri-app/src/App.svelte:202-212, examples/tauri-app/src/App.svelte:222-229

Summary

The "Authentication and JWT" system in tauri-plugin-centrifugo provides a secure pathway for real-time messaging. By integrating JWTs into both the Rust backend commands and the JavaScript frontend API, the plugin facilitates secure handshakes, channel-level authorization, and seamless credential refreshing, all governed by Tauri's granular permission system.