تنظیمات CORS

اشتراک‌گذاری منابع بین دامنه‌ای (CORS) به اپلیکیشن شما اجازه می‌دهد فایل‌ها، تصاویر یا سایر منابع را به‌طور مستقیم از یک صندوقچه‌ی آروان‌کلاد در مرورگر بارگذاری کند، حتا زمانی که اپلیکیشن و صندوقچه روی دامنه‌های مختلف قرار دارند.

برای نمونه، اگر اپلیکیشن شما روی https://myapp.example.com میزبانی شده باشد و فایل‌های‌تان در https://my-bucket.s3.ir-thr-at1.arvanstorage.ir، مرورگر به‌شکل پیش‌فرض آن درخواست را مسدود می‌کند. با تنظیم CORS روی صندوقچه، به مرورگر اعلام می‌کنید که این درخواست بین‌دامنه‌ای مجاز است.

توجه داشته باشید که CORS فقط برای درخواست‌های مرورگر اعمال می‌شود؛ فراخوانی‌های API از کد سمت سرور مشمول CORS نمی‌شوند.

شیوه عملکرد CORS

مرورگرها یک قانون امنیتی به نام same-origin policy اجرا می‌کنند که از دسترسی اسکریپت‌های یک دامنه به منابع دامنه‌ی دیگر جلوگیری می‌کند. CORS مکانیزمی استاندارد است که به سرور (صندوقچه‌ی شما) اجازه می‌دهد اعلام کند به کدام دامنه‌های دیگر اعتماد دارد.

برای درخواست‌های ساده مانند GET، مرورگر هدر Origin را ارسال می‌کند و فضای ابری پاسخ را با هدر Access-Control-Allow-Origin برمی‌گرداند. برای درخواست‌های پیچیده‌تر مانند PUT،DELETE یا ارسال هدرهای سفارشی مرورگر ابتدا یک درخواست مقدماتی OPTIONS ارسال می‌کند (preflight) تا مجوز بگیرد؛ اگر preflight ناموفق باشد، درخواست اصلی مسدود می‌شود.

یک درخواست زمانی Preflight می‌شود که یکی از شرایط زیر برقرار باشد:

• از متدی غیر از GET، HEAD یا POST استفاده کند.
• از POST با Content-Type غیر از text/plain ،application/x-www-form-urlencoded یا multipart/form-data استفاده کند.
• شامل هدرهای سفارشی مانند Authorization یا x-amz-acl باشد.

فیلدهای تنظیمات CORS

هر قانون CORS روی صندوقچه از فیلدهای زیر تشکیل می‌شود:

فیلد	اجباری	توضیح
Allowed Origins (دامنه‌های مجاز)	بله	دامنه‌هایی که مجاز به دسترسی به این صندوقچه هستند. از * برای مجاز کردن همه دامنه‌ها استفاده کنید، یا دامنه‌های مشخص مانند https://myapp.example.com را وارد کنید.
Allowed Methods (متدهای مجاز)	بله	متدهای HTTP مجاز برای درخواست‌های بین‌دامنه‌ای. مقادیر قابل استفاده: GET،PUT ،POST ،DELETE ،HEAD.
Allowed Headers (هدرهای مجاز)	خیر	هدرهایی که مرورگر مجاز به ارسال آن‌هاست. مقادیر رایج: Content-Type، Authorization ،x-amz-acl. از * برای مجاز کردن همه هدرها استفاده کنید.
Max Age (ثانیه)	خیر	مدت زمانی که مرورگر پاسخ preflight را کش می‌کند. در این مدت، درخواست preflight اضافه‌ای برای همان منبع ارسال نمی‌شود. پیش‌فرض: ۳۶۰۰ (یک ساعت).

توجه داشته باشید که استفاده از * برای Allowed Origins برای فایل‌های عمومی مانند تصاویر یا فونت‌ها مناسب است. برای صندوقچه‌هایی که آپلود احراز‌هویت‌شده یا داده‌های حساس دارند، به‌جای wildcard، دامنه‌های دقیق را مشخص کنید. هم‌چنین توجه داشته باشید که تنظیمات CORS روی مجوزهای دسترسی صندوقچه تاثیر نمی‌گذارد؛ یک صندوقچه‌ی Private حتا با وجود قانون CORS باز، هم‌چنان به احراز هویت معتبر نیاز دارد.

تنظیم CORS در فضای ابری

وارد پنل آروان‌کلاد شوید و از منوی سمت چپ Object Storage را انتخاب کنید. در بخش صندوقچه‌ها روی گزینه‌ی عملیات کلیک و گزینه‌ی تنظیمات CORS را انتخاب کنید.

روی دکمه‌ی «قانون جدید» کلیک و سپس فیلدهای جدول را پر کنید.

می‌توانید چند قانون برای یک صندوقچه تعریف کنید. کافی است یک درخواست با یکی از قوانین تطابق داشته باشد تا مجاز شود. در پایان روی تایید کلیک کنید تا تنظیمات اعمال شود.

توجه داشته باشید که تغییرات CORS برای درخواست‌های جدید به‌شکل آنی اعمال می‌شود. مرورگرهایی که پاسخ preflight را از قبل کش کرده‌اند، تا پایان مدت Max Age از نسخه‌ی کش‌شده استفاده می‌کنند.

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

برای بارگذاری تصاویر، فونت‌ها یا فایل‌های استاتیک از صندوقچه در فرانت‌اند:

فیلد	مقدار
Allowed Origins	https://myapp.example.com
Allowed Methods	GET، HEAD
Allowed Headers	Content-Type
Max Age	86400

برای زمانی که کاربران فایل‌ها را به‌طور مستقیم با استفاده از presigned URL به صندوقچه آپلود می‌کنند:

فیلد	مقدار
Allowed Origins	https://myapp.example.com
Allowed Methods	GET ،PUT ،POST ،DELETE ،HEAD
Allowed Headers	*
Max Age	3600

برای صندوقچه‌هایی که شامل محتوای عمومی و غیرحساس هستند، مانند فایل‌های رسانه‌ای یا دارایی‌های اشتراکی:

فیلد	مقدار
Allowed Origins	*
Allowed Methods	GET ،HEAD
Allowed Headers	*
Max Age	3600

تنظیم CORS از طریق API

می‌توانید قوانین CORS را از طریق API سازگار با S3 نیز تنظیم کنید. نمونه‌ی زیر از AWS SDK در Python برای اعمال تنظیمات CORS روی یک صندوقچه‌ی آروان‌کلاد استفاده می‌کند.

import boto3

s3_client = boto3.client(
    's3',
    endpoint_url='https://s3.ir-thr-at1.arvanstorage.ir',
    aws_access_key_id='<ACCESS-KEY>',
    aws_secret_access_key='<SECRET-KEY>',
)

cors_configuration = {
    'CORSRules': [
        {
            'AllowedOrigins': ['https://myapp.example.com'],
            'AllowedMethods': ['GET', 'PUT', 'POST', 'DELETE', 'HEAD'],
            'AllowedHeaders': ['*'],
            'ExposeHeaders': ['ETag', 'Content-Length'],
            'MaxAgeSeconds': 3600
        }
    ]
}

s3_client.put_bucket_cors(
    Bucket='my-bucket-name',
    CORSConfiguration=cors_configuration
)

print("تنظیمات CORS با موفقیت اعمال شد.")

برای دریافت تنظیمات CORS فعلی یک صندوقچه:

response = s3_client.get_bucket_cors(Bucket='my-bucket-name')
print(response['CORSRules'])

برای حذف کامل تنظیمات CORS از یک صندوقچه:

s3_client.delete_bucket_cors(Bucket='my-bucket-name')
print("تنظیمات CORS حذف شد.")

عیب‌یابی

• اگر مرورگر خطای CORS نشان می‌دهد با اینکه قانون را تنظیم کرده‌اید:

  • origin در درخواست باید دقیقن با مقداری که در پنل وارد کرده‌اید یکسان باشد، از جمله پروتکل (//:https) و زیر‌دامنه؛ آدرس‌های https://myapp.example.com و http://myapp.example.com دو origin متفاوت محسوب می‌شوند.
  • متد HTTP مورد استفاده باید در لیست Allowed Methods باشد. اگر درخواست شامل هدر Authorization یا هدر سفارشی دیگری است، آن هدر باید در Allowed Headers نوشته شده باشد. برای بررسی دقیق‌تر، در Developer Tools مرورگر (تب Network) روی درخواست ناموفق کلیک کنید و هدرهای پاسخ را بررسی کنید.

• اگر درخواست OPTIONS برای preflight شکست می‌خورد: مطمین شوید قانون CORS شما شامل تمام متدها و هدرهایی است که درخواست واقعی از آن‌ها استفاده می‌کند. هم‌چنین مقدار Max Age را بررسی کنید؛ اگر روی ۰ تنظیم شده باشد، مرورگر قبل از هر درخواست یک preflight جدید ارسال می‌کند.

• اگر CORS در محیط توسعه کار می‌کند اما در Production کار نمی‌کند: احتمالن دامنه‌ی Production با دامنه‌ای که در مرحله‌ی توسعه تست کرده‌اید متفاوت است. مطمین شوید دامنه‌ی دقیق Production در لیست Allowed Origins وجود دارد، یا یک قانون CORS جداگانه برای آن تعریف کنید.

• اگر از Custom Domain برای صندوقچه استفاده می‌کنید: تنظیمات CORS هم‌چنان کار می‌کند. تنظیمات CORS در سطح صندوقچه اعمال می‌شود و فارغ از این‌که از طریق دامنه‌ی پیش‌فرض آروان یا یک Custom Domain به صندوقچه دسترسی دارید، کار می‌کند.