What Security Features Are Provided by rocketmq-auth in RocketMQ-Rust?

rocketmq-auth provides a pluggable authentication and authorization framework for RocketMQ-Rust, featuring stateless and stateful evaluation strategies, configurable whitelist bypasses, and unified error handling through the AuthConfig struct.

The rocketmq-auth crate serves as the security core for the mxsm/rocketmq-rust project, delivering a complete set of security features provided by rocketmq-auth that can be integrated into brokers, clients, and nameservers. This authentication and authorization framework supports both high-performance cached evaluations and strict per-request validation, allowing operators to balance security overhead with throughput requirements.

Authentication Framework

The authentication layer validates the identity of every requestor through a pluggable AuthenticationProvider trait defined in rocketmq-auth/src/authentication/provider/authentication_provider.rs. The framework ships with multiple evaluation strategies that can be selected based on deployment needs.

Stateless and Stateful Strategies

StatelessAuthenticationStrategy (rocketmq-auth/src/authentication/strategy/stateless_authentication_strategy.rs) evaluates every request fresh against the configured provider, ensuring credentials are checked in real-time but incurring full provider overhead per call.

StatefulAuthenticationStrategy (rocketmq-auth/src/authentication/strategy/stateful_authentication_strategy.rs) caches the result of successful and failed authentications per channel and user, reducing load on external providers for high-throughput connections. The cache size and expiration are controlled by stateful_authentication_cache_max_num and stateful_authentication_cache_expired_second in AuthConfig.

Allow-All Strategy for Development

AllowAllAuthenticationStrategy (rocketmq-auth/src/authentication/strategy/allow_all.rs) unconditionally succeeds for every request, making it ideal for local development and unit testing where credential management would impede iteration speed.

Authentication Evaluator Facade

The AuthenticationEvaluator (rocketmq-auth/src/authentication/evaluator.rs) provides a simplified public API that hides strategy-specific details. It receives an AuthenticationContext and forwards it to the configured strategy, returning standardized AuthError types.

Authorization Framework

The authorization layer decides whether an authenticated identity may perform specific actions on resources. It uses a pluggable AuthorizationProvider trait located in rocketmq-auth/src/authorization/provider.rs.

Policy-Based Access Control

Policies are defined in rocketmq-auth/src/authorization/model/policy.rs, which links Subject (users or groups), Resource (topics, consumer groups), and Action (Pub, Sub, etc.) to a Decision (Allow or Deny). The Acl struct in rocketmq-auth/src/authorization/model/acl.rs serves as the container for policy collections used by providers.

Authorization Strategies

StatelessAuthorizationStrategy (rocketmq-auth/src/authorization/strategy/stateless_authorization_strategy.rs) evaluates every request against current policies without caching, ensuring immediate policy updates take effect.

StatefulAuthorizationStrategy (rocketmq-auth/src/authorization/strategy/stateful_authorization_strategy.rs) caches policy look-ups for faster decisions on repeated subject-resource-action combinations.

AllowAllAuthorizationStrategy (implemented within rocketmq-auth/src/authorization/strategy/authorization_strategy.rs) automatically grants every request, useful for rapid prototyping.

Authorization Evaluator

The AuthorizationEvaluator (rocketmq-auth/src/authorization/evaluator.rs) serves as the facade for the authorization pipeline. It accepts an AuthorizationContext (or slice of contexts) and delegates to the chosen strategy, returning AuthorizationError types for denials.

Configuration and Extensibility

AuthConfig

The AuthConfig struct in rocketmq-auth/src/config.rs acts as the single source of truth for all security behavior. Default values disable both authentication and authorization, making the framework opt-in. Key fields include:

• authentication_enabled and authorization_enabled – feature toggles
• stateful_authentication_cache_max_num and stateful_authentication_cache_expired_second – cache tuning
• RPC code whitelists for bypassing checks

Whitelist Support

Both authentication and authorization support configurable whitelists of RPC codes that bypass security checks entirely. This is essential for internal system calls or health checks that must succeed without credentials.

Error Handling

Unified error types (AuthError and AuthorizationError) are re-exported through rocketmq-error/src/auth_error.rs. This enables callers to distinguish between authentication failures, invalid tokens, permission denials, and system errors without importing crate-specific types, ensuring consistent error handling across the entire RocketMQ-Rust ecosystem.

Implementation Examples

Building a Stateless Authentication Strategy

use rocketmq_auth::authentication::strategy::stateless_authentication_strategy::StatelessAuthenticationStrategy;
use rocketmq_auth::config::AuthConfig;
use rocketmq_auth::authentication::provider::DefaultAuthenticationProvider;
use std::sync::Arc;

// Load the default configuration (both auth disabled by default)
let auth_cfg = AuthConfig::default();

// Create a provider (e.g., a simple in‑memory user store)
let provider = Arc::new(DefaultAuthenticationProvider::new());

// Build the strategy – it will honour the `authentication_enabled` flag
let auth_strategy = StatelessAuthenticationStrategy::new(auth_cfg, Some(provider));

// The strategy can now be used directly:
let ctx = DefaultAuthenticationContext::new(); // fill username, password, etc.
match auth_strategy.authenticate(&ctx) {
    Ok(_) => println!("Authenticated"),
    Err(e) => eprintln!("Auth error: {}", e),
}

Using the Facade Evaluator

use rocketmq_auth::authentication::{AuthenticationEvaluator, AuthenticationStrategy};
use rocketmq_auth::authentication::strategy::allow_all::AllowAllAuthenticationStrategy;
use rocketmq_auth::authentication::context::default_authentication_context::DefaultAuthenticationContext;

// The Allow‑All strategy is ideal for local testing
let allow_all = AllowAllAuthenticationStrategy::new();
let evaluator = AuthenticationEvaluator::new(allow_all);

// Build a context – even an empty one will succeed
let context = DefaultAuthenticationContext::new();

evaluator.evaluate(&context).expect("Should always succeed");

Stateless Authorization with a Policy

use rocketmq_auth::authorization::{
    AuthorizationEvaluator, AuthorizationStrategy,
    policy::Policy,
    model::{resource::Resource, action::Action, subject::Subject},
};
use rocketmq_auth::authorization::strategy::stateless_authorization_strategy::StatelessAuthorizationStrategy;
use rocketmq_auth::config::AuthConfig;

// Build a simple policy that allows Pub on topic "test"
let resource = Resource::of_topic("test".into());
let policy = Policy::of(vec![resource.clone()], vec![Action::Pub], None, Decision::Allow);

// Initialise the strategy (no external provider here for brevity)
let config = AuthConfig::default();
let authz_strategy = StatelessAuthorizationStrategy::new(config, None).unwrap();

// Wrap it with the evaluator façade
let evaluator = AuthorizationEvaluator::new(authz_strategy);

// Build the authorization context
let subject = Subject::new_user("alice".into());
let authz_ctx = DefaultAuthorizationContext::of(
    subject,
    resource,
    Action::Pub,
    "127.0.0.1".into(),
);

// The evaluator will consult the strategy → provider → policy
evaluator.evaluate(&authz_ctx).expect("Authorization should succeed");

Enabling Stateful Caching

use rocketmq_auth::authentication::strategy::stateful_authentication_strategy::StatefulAuthenticationStrategy;
use rocketmq_auth::config::AuthConfig;
use rocketmq_auth::authentication::provider::DefaultAuthenticationProvider;
use std::sync::Arc;

// Turn on authentication and give the cache a small size for demonstration
let mut cfg = AuthConfig::default();
cfg.authentication_enabled = true;
cfg.stateful_authentication_cache_max_num = 100;
cfg.stateful_authentication_cache_expired_second = 60;

let provider = Arc::new(DefaultAuthenticationProvider::new());
let stateful = StatefulAuthenticationStrategy::new(cfg, Some(provider));

// The first call will hit the provider, subsequent calls (same channel+user)
// will be served from the cache.
let mut ctx = DefaultAuthenticationContext::new();
ctx.base.set_channel_id(Some("chan-1".into()));
ctx.set_username("bob".into());

stateful.authenticate(&ctx).unwrap(); // provider called
stateful.authenticate(&ctx).unwrap(); // cached result

Summary

• rocketmq-auth delivers a complete authentication and authorization framework for the RocketMQ-Rust ecosystem, separating identity validation from permission enforcement.
• Stateless strategies in files like stateless_authentication_strategy.rs and stateless_authorization_strategy.rs provide strict per-request evaluation without caching.
• Stateful strategies in stateful_authentication_strategy.rs and stateful_authorization_strategy.rs cache results to minimize provider load, with configurable limits via AuthConfig.
• Allow-All strategies and RPC whitelists enable rapid prototyping and system-level bypasses for health checks.
• Unified error handling through rocketmq-error/src/auth_error.rs ensures consistent AuthError and AuthorizationError types across the entire stack.

Frequently Asked Questions

What is the difference between stateless and stateful authentication in rocketmq-auth?

Stateless authentication evaluates every request fresh against the configured provider, ensuring credentials are checked in real-time but incurring full provider overhead per call. Stateful authentication caches the result of successful and failed authentications per channel and user, reducing load on external providers for high-throughput connections. The cache size and expiration are controlled by stateful_authentication_cache_max_num and stateful_authentication_cache_expired_second in AuthConfig.

How do I disable authentication for local development?

You can use the AllowAllAuthenticationStrategy found in rocketmq-auth/src/authentication/strategy/allow_all.rs, which unconditionally succeeds for every request. Alternatively, set authentication_enabled = false in your AuthConfig to disable the framework entirely. Both approaches are suitable for unit testing and local prototyping where credential management would impede development velocity.

Where are authorization policies defined in the codebase?

Authorization policies are defined in rocketmq-auth/src/authorization/model/policy.rs, which links Subject (users or groups), Resource (topics, consumer groups), and Action (Pub, Sub, etc.) to a Decision (Allow or Deny). The Acl struct in rocketmq-auth/src/authorization/model/acl.rs serves as the container for policy collections used by providers.

What error types does rocketmq-auth return?

Unified error types (AuthError and AuthorizationError) are re-exported through rocketmq-error/src/auth_error.rs. This enables callers to distinguish between authentication failures, invalid tokens, permission denials, and system errors without importing crate-specific types, ensuring consistent error handling across the entire RocketMQ-Rust ecosystem.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}