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

> Explore rocketmq-auth security features in RocketMQ-Rust. Discover stateless/stateful strategies, bypasses, and unified error handling with AuthConfig for robust message queuing security.

- Repository: [mxsm/rocketmq-rust](https://github.com/mxsm/rocketmq-rust)
- Tags: security-features
- Published: 2026-03-07

---

**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`](https://github.com/mxsm/rocketmq-rust/blob/main/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`](https://github.com/mxsm/rocketmq-rust/blob/main/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`](https://github.com/mxsm/rocketmq-rust/blob/main/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`](https://github.com/mxsm/rocketmq-rust/blob/main/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`](https://github.com/mxsm/rocketmq-rust/blob/main/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`](https://github.com/mxsm/rocketmq-rust/blob/main/rocketmq-auth/src/authorization/provider.rs).

### Policy-Based Access Control

Policies are defined in [`rocketmq-auth/src/authorization/model/policy.rs`](https://github.com/mxsm/rocketmq-rust/blob/main/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`](https://github.com/mxsm/rocketmq-rust/blob/main/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`](https://github.com/mxsm/rocketmq-rust/blob/main/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`](https://github.com/mxsm/rocketmq-rust/blob/main/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`](https://github.com/mxsm/rocketmq-rust/blob/main/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`](https://github.com/mxsm/rocketmq-rust/blob/main/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`](https://github.com/mxsm/rocketmq-rust/blob/main/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`](https://github.com/mxsm/rocketmq-rust/blob/main/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

```rust
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

```rust
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

```rust
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

```rust
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`](https://github.com/mxsm/rocketmq-rust/blob/main/stateless_authentication_strategy.rs) and [`stateless_authorization_strategy.rs`](https://github.com/mxsm/rocketmq-rust/blob/main/stateless_authorization_strategy.rs) provide strict per-request evaluation without caching.
- **Stateful strategies** in [`stateful_authentication_strategy.rs`](https://github.com/mxsm/rocketmq-rust/blob/main/stateful_authentication_strategy.rs) and [`stateful_authorization_strategy.rs`](https://github.com/mxsm/rocketmq-rust/blob/main/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`](https://github.com/mxsm/rocketmq-rust/blob/main/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`](https://github.com/mxsm/rocketmq-rust/blob/main/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`](https://github.com/mxsm/rocketmq-rust/blob/main/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`](https://github.com/mxsm/rocketmq-rust/blob/main/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`](https://github.com/mxsm/rocketmq-rust/blob/main/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.