معرفی کتابخانه flask-cors در پایتون

کتابخانه flask-cors ابزاری ساده و محبوب برای مدیریت سیاست‌های Cross-Origin Resource Sharing (CORS) در برنامه‌های وب نوشته‌شده با فریمورک Flask است. CORS مکانیزمی است که مرورگرها برای جلوگیری یا اجازه دسترسی درخواست‌های منبع-متقاطع (cross-origin) استفاده می‌کنند. این مقاله به زبان فارسی، کاربردها، پیکربندی‌ها، مثال‌های عملی و نکات امنیتی مرتبط با flask-cors را پوشش می‌دهد.

چرا به flask-cors نیاز داریم؟

• مرورگرها بر اساس سیاست‌های یکسان منبع (Same-Origin Policy) به درخواست‌های ورودی از دامنه‌های دیگر محدودیت می‌گذارند.
• اگر بک‌اند شما در دامنه یا پورت متفاوتی نسبت به فرانت‌اند باشد (مثلاً API روی api.example.com و فرانت‌اند روی example.com)، باید CORS را فعال کنید.
• flask-cors به سادگی هدرهای لازم مانند Access-Control-Allow-Origin را ایجاد و پاسخ‌های پیش‌پرواز (preflight / OPTIONS) را مدیریت می‌کند.

نصب

نصب با pip انجام می‌شود:

pip install flask-cors

این کد به طور خودکار کتابخانه را به محیط پایتون اضافه می‌کند.

مثال پایه: فعال‌سازی سراسری CORS

from flask import Flask, jsonify
from flask_cors import CORS

app = Flask(__name__)
CORS(app)  # Allow all origins by default

@app.route('/api/data')
def data():
    return jsonify({"message": "Hello from Flask with CORS"})

if __name__ == '__main__':
    app.run()

توضیح: در این مثال با فراخوانی CORS(app)، به‌صورت پیش‌فرض به همه منابع اجازه دسترسی از هر مبدا داده می‌شود (*). این روش هنگام توسعه مناسب است اما برای تولید باید محدودیت‌ها را سخت‌تر کنید.

پیکربندی‌های رایج و گزینه‌ها

گزینه‌های مهم flask-cors شامل:

• origins: تعیین لیست مبداهای مجاز (مثلاً دامنه‌ها یا لیست). می‌تواند "*" نیز باشد.
• methods: روش‌های HTTP مجاز (GET, POST, PUT و …).
• allow_headers: هدرهای مجاز که فرانت‌اند می‌تواند ارسال کند.
• expose_headers: هدرهایی که در پاسخ در دسترس اسکریپت کلاینت قرار می‌گیرند.
• supports_credentials: اجازه ارسال کوکی‌ها و موافقت‌نامه‌های اعتبارسنجی (access-control-allow-credentials).
• max_age: مدت زمانی که نتیجه preflight کش می‌شود.

مثال تولیدی با محدودسازی و بهینه‌سازی

from flask import Flask, jsonify, request
from flask_cors import CORS

def dynamic_origin(origin):
    allowed = ['https://app.example.com', 'https://admin.example.com']
    return origin in allowed

app = Flask(__name__)
CORS(app, origins=dynamic_origin, methods=['GET','POST'], supports_credentials=True, max_age=3600)

@app.route('/api/secure-data', methods=['GET','POST'])
def secure_data():
    user = request.cookies.get('session')
    return jsonify({"secure": True, "user": user})

if __name__ == '__main__':
    app.run()

توضیح: در این نسخه از تابعی برای تصمیم‌گیری پویا درباره مبدا استفاده شده است تا فقط دامنه‌های مشخص شده اجازه دسترسی داشته باشند. تنظیم supports_credentials=True امکان ارسال کوکی‌ها را فراهم می‌کند ولی در این حالت نمی‌توان از "*" برای Access-Control-Allow-Origin استفاده کرد؛ باید دامنه صریح مشخص شود.

استفاده از دکوراتور @cross_origin برای روت‌های خاص

from flask import Flask, jsonify
from flask_cors import cross_origin

app = Flask(__name__)

@app.route('/public')
@cross_origin(origins=['https://example.com'])
def public_resource():
    return jsonify({"msg": "Only example.com can access this"})

@app.route('/open')
@cross_origin()  # default allows all origins
def open_resource():
    return jsonify({"msg": "Open to all"})

توضیح: دکوراتور @cross_origin برای اعمال قوانین CORS به صورت محلی روی یک مسیر خاص مفید است. این امکان کنترل دقیق‌تری نسبت به فعال‌سازی سراسری فراهم می‌کند.

مدیریت درخواست‌های پیش‌پرواز (Preflight)

مرورگرها برای درخواست‌هایی که روش یا هدر غیرمعمول دارند، ابتدا یک درخواست OPTIONS ارسال می‌کنند. flask-cors این درخواست‌ها را به طور خودکار پاسخ می‌دهد، مگر در موارد پیچیده که لازم است رفتار سفارشی نوشته شود.

جدول خلاصه‌ی گزینه‌های مهم

نکات امنیتی و بهترین شیوه‌ها

• در محیط توسعه استفاده از * ساده و مفید است، ولی در تولید از لیست دامنه‌های مشخص استفاده کنید.
• اگر supports_credentials=True را فعال می‌کنید، حتماً دامنه‌ها را صریح مشخص کنید و از * استفاده نکنید.
• تنظیم محدودیت روی روش‌ها و هدرها باعث کاهش سطح حمله می‌شود.
• درصورتی‌که API شما حساس است، علاوه بر CORS از مکانیزم‌های احراز هویت قوی (JWT، OAuth) و محدودسازی نرخ (rate limiting) استفاده کنید.

عیب‌یابی (Troubleshooting)

• خطای “No ‘Access-Control-Allow-Origin’ header” یعنی CORS فعال نیست یا برای روت خاص فعال نشده است.
• اگر کوکی ارسال نمی‌شود، بررسی کنید که supports_credentials فعال است و کلاینت با گزینه fetch(..., credentials: 'include') درخواست می‌فرستد.
• پاسخ preflight طولانی‌مدت است؟ مقدار max_age را افزایش دهید تا فرکانس preflight کمتر شود.

مطالب تکمیلی و پیاده‌سازی پیشرفته

برای سناریوهای میکروسرویس یا چندین زیر دامنه می‌توان از توابع پویا برای تصمیم‌گیری درباره مجاز بودن Origin استفاده کرد، یا از سرویس‌های پروکسی و gateway (مثل nginx یا API Gateway) برای مدیریت CORS در سطح آرشیو و مرکزی بهره برد. در بسیاری از معماری‌ها، بهتر است قوانین دقیق CORS در لایه‌ی دروازه یا reverse proxy اعمال شوند تا دسترسی به تنظیمات امنیتی یکپارچه باشد.

خلاصه

کتابخانه flask-cors راه حلی سریع و منعطف برای مدیریت CORS در اپلیکیشن‌های Flask است. با دانش درست از گزینه‌ها، می‌توانید بین سهولت توسعه و امنیت تولید تعادل ایجاد کنید. همیشه در محیط تولید محدودیت دامنه‌ها و هدرها را اعمال کنید و در صورت نیاز از احراز هویت و محافظت لایه‌ای استفاده نمایید.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال