Bitflags IAM Service (gRPC)
Educational Project: This is an educational implementation of an Identity and Access Management (IAM) service developed in Rust using gRPC and bitflags for high-performance permission management. It demonstrates concepts of permissions systems, bitwise operations, and gRPC service development.
Project Structure
bitflags-iam/
+-- proto/
| +-- iam.proto # Protobuf schema defining the gRPC API
+-- src/
| +-- main.rs # gRPC IAM server
| +-- client.rs # Example client and tests
| +-- iam_manager.rs # Core IAM business logic and permission management
| +-- lib.rs # Library entry point and public exports
| +-- models.rs # Data structures and models
| +-- utils.rs # Utility functions and helpers
+-- build.rs # Protobuf compilation script
+-- Cargo.toml # Dependencies and project configuration
+-- Cargo.lock # Dependency version lock
+-- README.md # This documentation
Features
User Management
- User creation with name, email, and password
- Secure password storage with bcrypt hashing
- In-memory storage via HashMap (no database for now)
- User information retrieval by ID
Permission Management (64-bit)
- Default permissions: READ (1), WRITE (2), EXECUTE (4), DELETE (8)
- Add/remove custom permissions
- Bitwise operations for high-performance verification
- Extensibility up to 64 simultaneous permissions
Permission Checking
- Fast access control based on bitwise operations
- Composite verification: checks if user has ALL required permissions
- Error handling with detailed messages
Permission Modification
- Real-time user permission updates
- Dynamic system permission management
- Thread-safe with RwLock
Build and Run
Prerequisites
- Rust (version 1.70+)
- Cargo
Install dependencies
cargo build
Start the server
cargo run --bin server
The server starts on [::1]:50051 (IPv6 localhost)
Test with example client
# In another terminal
cargo run --bin client
cargo run --bin client
Release build
cargo build --release
Compilation tests
cargo check
API Documentation
Client setup
use iam::iam_service_client::IamServiceClient;
let mut client = IamServiceClient::connect("http://[::1]:50051").await?;
let mut client = IamServiceClient::connect("http://[::1]:50051").await?;
User Management
Create a user
let request = CreateUserRequest {
name: "John Doe".to_string(),
email: "john@example.com".to_string(),
password: "secure_password".to_string(),
permissions: vec!["READ".to_string(), "WRITE".to_string()],
};
let response = client.create_user(Request::new(request)).await?;
name: "John Doe".to_string(),
email: "john@example.com".to_string(),
password: "secure_password".to_string(),
permissions: vec!["READ".to_string(), "WRITE".to_string()],
};
let response = client.create_user(Request::new(request)).await?;
Response:
CreateUserResponse {
success: bool,
message: String,
user: Option<User> // Contains id, name, email, permissions (Vec)
}
success: bool,
message: String,
user: Option<User> // Contains id, name, email, permissions (Vec
}
Get a user
let request = GetUserRequest {
user_id: "user_uuid".to_string(),
};
let response = client.get_user(Request::new(request)).await?;
user_id: "user_uuid".to_string(),
};
let response = client.get_user(Request::new(request)).await?;
Response:
GetUserResponse {
success: bool,
message: String,
user: Option<User> // User.permissions is Vec
}
success: bool,
message: String,
user: Option<User> // User.permissions is Vec
}
Permission Management
List all permissions
let request = ListPermissionsRequest {};
let response = client.list_permissions(Request::new(request)).await?;
let response = client.list_permissions(Request::new(request)).await?;
Response:
ListPermissionsResponse {
success: bool,
message: String,
permissions: Vec<Permission> // Permission { name: String, value: u64 }
}
success: bool,
message: String,
permissions: Vec<Permission> // Permission { name: String, value: u64 }
}
Add a permission
let request = AddPermissionRequest {
permission_name: "ADMIN".to_string(),
};
let response = client.add_permission(Request::new(request)).await?;
permission_name: "ADMIN".to_string(),
};
let response = client.add_permission(Request::new(request)).await?;
Response:
AddPermissionResponse {
success: bool,
message: String,
permission: Option<Permission> // Contains name and auto-assigned bit value
}
success: bool,
message: String,
permission: Option<Permission> // Contains name and auto-assigned bit value
}
Remove a permission
let request = RemovePermissionRequest {
permission_name: "ADMIN".to_string(),
};
let response = client.remove_permission(Request::new(request)).await?;
permission_name: "ADMIN".to_string(),
};
let response = client.remove_permission(Request::new(request)).await?;
Update user permissions
let request = UpdateUserPermissionsRequest {
user_id: "user_uuid".to_string(),
permissions: vec!["READ".to_string(), "WRITE".to_string(), "ADMIN".to_string()],
};
let response = client.update_user_permissions(Request::new(request)).await?;
user_id: "user_uuid".to_string(),
permissions: vec!["READ".to_string(), "WRITE".to_string(), "ADMIN".to_string()],
};
let response = client.update_user_permissions(Request::new(request)).await?;
Permission Checking
Check multiple permissions
let request = CheckPermissionsRequest {
user_id: "user_uuid".to_string(),
required_permissions: vec!["READ".to_string(), "WRITE".to_string()],
};
let response = client.check_permissions(Request::new(request)).await?;
user_id: "user_uuid".to_string(),
required_permissions: vec!["READ".to_string(), "WRITE".to_string()],
};
let response = client.check_permissions(Request::new(request)).await?;
Response:
CheckPermissionsResponse {
success: bool,
has_permissions: bool, // true if user has ALL required permissions
message: String,
missing_permissions: Vec<String> // List of missing permissions if any
}
success: bool,
has_permissions: bool, // true if user has ALL required permissions
message: String,
missing_permissions: Vec<String> // List of missing permissions if any
}
Permission System (Bitflags)
The service uses 64-bit bitflags internally for high-performance permission checking, but clients work with human-readable permission names.
Default permissions
| Permission | Value | Binary |
|---|---|---|
| READ | 1 | 0001 |
| WRITE | 2 | 0010 |
| EXECUTE | 4 | 0100 |
| DELETE | 8 | 1000 |
Client API (Recommended)
// Create user with named permissions
let permissions = vec!["READ".to_string(), "WRITE".to_string()];
// Check multiple permissions at once
let required = vec!["READ".to_string(), "ADMIN".to_string()];
// Add new permission (automatically assigns bit value)
let request = AddPermissionRequest {
permission_name: "ADMIN".to_string(),
};
let permissions = vec!["READ".to_string(), "WRITE".to_string()];
// Check multiple permissions at once
let required = vec!["READ".to_string(), "ADMIN".to_string()];
// Add new permission (automatically assigns bit value)
let request = AddPermissionRequest {
permission_name: "ADMIN".to_string(),
};
Internal bitwise operations
The service automatically handles the conversion between permission names and bit values:
- Permission names - bit values for internal storage
- Bit values - permission names for client responses
- Bitwise AND operations for permission checking
Permission checking logic
// The service verifies that users have ALL required permissions
// Internally: (user_permissions & required_permissions) == required_permissions
// Internally: (user_permissions & required_permissions) == required_permissions
Auto-assigned bit values
When adding new permissions, the service automatically finds the next available bit position:
- First available: 16 (1 << 4)
- Next: 32 (1 << 5)
- Up to: 1 << 63 (64th bit)
Common Error Messages
"User not found"- User ID doesn't exist"Permission already exists"- Attempt to add existing permission"Permission not found"- Attempt to remove non-existent permission"Failed to hash password"- Error during password hashing"Failed to acquire write lock"- Concurrency error (rare)
Development
Modify protobuf schema
- Edit
proto/iam.proto - Rebuild:
cargo build - Rust bindings are generated automatically
Add new features
- gRPC handlers are in
src/main.rs - Business logic is in
IamManager - Thread-safe by design with
Arc
Performance
- In-memory storage: O(1) access for users
- Bitwise operations: O(1) permission checking
- Thread-safe: Concurrency support with RwLock
Complete Example
See src/client.rs for a complete usage example demonstrating:
- Permission listing: View all available permissions
- User creation: Create users with named permissions
- Permission checking: Check multiple permissions with detailed feedback
- Dynamic permissions: Add new permissions at runtime
- Permission updates: Modify user permissions
- Error handling: Handle non-existent permissions gracefully
Key improvements over bit-based API:
- Human-readable: Use
"ADMIN"instead of16 - Multiple permissions: Check
["READ", "WRITE", "ADMIN"]at once - Auto-assignment: Service assigns bit values automatically
- Missing permissions: Get detailed list of what's missing
- Discovery: List all available permissions
Example client usage:
# Start server
cargo run --bin server
# Run example client (in another terminal)
cargo run --bin client
cargo run --bin server
# Run example client (in another terminal)
cargo run --bin client
The client will demonstrate all features including creating a user with ["READ", "WRITE"] permissions, adding an "ADMIN" permission, checking various permission combinations, and showing detailed error messages.