8000 Add API Key Access Restrictions by qdequele · Pull Request #5796 · meilisearch/meilisearch · GitHub
[go: up one dir, main page]
Skip to content

Add API Key Access Restrictions #5796

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

Add API Key Access Restrictions #5796

wants to merge 3 commits into from

Conversation

qdequele
Copy link
Member
@qdequele qdequele commented Aug 2, 2025 •
edited
Loading

Summary

This PR introduces advanced access control features for API keys as part of the Enterprise Edition, allowing administrators to restrict API key usage based on IP addresses, HTTP referrers, and rate limits.

Features Added

  1. IP-based Access Restrictions
  • API keys can now be restricted to specific IP addresses or CIDR subnets
  • Supports both IPv4 and IPv6 addresses
  • Example: "allowed_ips": ["192.168.1.0/24", "10.0.0.1/32"]
  1. Referrer-based Access Restrictions
  • API keys can be limited to requests from specific domains
  • Supports wildcard patterns for flexible domain matching
  • Example: "allowed_referrers": ["*.example.com", "https://trusted.org/*"]
  1. Rate Limiting Configuration
  • Per-API-key rate limiting with configurable request limits and time windows
  • Structure: "rate_limit": { "max_requests": 100, "window_seconds": 3600 }
  • Returns HTTP 429 when rate limit is exceeded
  • Adds rate limit headers to responses: X-RateLimit-Limit,
    X-RateLimit-Remaining, X-RateLimit-Reset

Technical Implementation

Core Components

  • api_key_restrictions.rs: Core validation logic for IP and referrer restrictions with comprehensive wildcard matching and CIDR subnet support
  • Rate Limiter Module: In-memory sliding window rate limiter with automatic cleanup of expired entries. Redis based if the feature redis-rate-limiter is activated and the env variable MEILI_REDIS_RATE_LIMIT_URL is set.
  • Authentication Integration: Extended authentication pipeline to validate restrictions and enforce rate limits

API Changes

  • Extended CreateApiKey and Key structs with optional restriction fields
  • New error codes: rate_limit_exceeded (HTTP 429)
  • Backward compatible - all restriction fields are optional

Testing

  • Unit tests for wildcard matching algorithm
  • Unit tests for CIDR IP matching (IPv4 and IPv6)
  • Integration tests for API key creation with restrictions
  • Comprehensive test coverage for combined restrictions

Example Usage

  POST /keys
  {
    "name": "restricted-api-key",
    "actions": ["search"],
    "indexes": ["products"],
    "allowed_ips": ["192.168.1.0/24", "2001:db8::/32"],
    "allowed_referrers": ["*.mycompany.com", "https://partner.org/*"],
    "rate_limit": {
      "max_requests": 1000,
      "window_seconds": 3600
    }
  }

Migration & Compatibility

  • Fully backward compatible with existing API keys
  • Database migration handled via v5 to v6 compatibility layer
  • No action required for existing deployments

Security Considerations

  • IP restrictions help prevent API key abuse from unauthorized networks
  • Referrer restrictions add an additional layer of protection for
    browser-based applications
  • Rate limiting prevents API abuse and ensures fair resource usage

Performance Impact

  • Minimal overhead for restriction checks (O(n) for n restrictions)
  • In-memory rate limiter with efficient sliding window algorithm
  • Automatic cleanup of expired rate limit entries

Breaking Changes

None - all new fields are optional and backward compatible.

Dependencies Added

  • ipnet: For efficient IP subnet matching

Enterprise Edition Notice

This feature is part of Meilisearch Enterprise Edition and is governed by the Business Source License 1.1.

Check

  • Cargo check, test, fmt, clippy
  • Api changes: None
  • Storage changes: Dump Implemented
  • Env/CLI changes: Yes and documented

@qdequele qdequele added the db change A database was modified label Aug 6, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
db change A database was modified
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
1 participant
@qdequele
0