إنتقل إلى المحتوى الرئيسي

CORS وallowed origins

تحمل مفاتيح Publishable (kld_pk_live_…) قائمة allowed-origins — وهي browser origins المسموح لها باستخدام المفتاح. اضبطها عند mint للمفتاح (مثل https://acme.com, https://app.acme.com)؛ ويتطلب live publishable key واحدًا على الأقل. أما مفاتيح Server (kld_sk_live_…) فلا تحصل على CORS grant، ولذلك لا يمكن للصفحة قراءة response تم إنشاؤه باستخدامها. لاحظ ما يغطيه ذلك وما لا يغطيه: CORS يحجب response وليس request — وبالتالي فإن server key المضمن في page source يكون قد تم كشفه بالفعل. لذلك يرفض SDK kld_sk_… عند mount؛ فـ server keys مخصصة للاتصال server-to-server فقط.

كيفية التطبيق​

  • Preflight (OPTIONS) متساهل — فهو يعكس origin المطلوب لكي يواصل المتصفح العملية (فالمفتاح لا يتم تقديمه في preflight).
  • الـ request الفعلي يحصل فقط على header باسم Access-Control-Allow-Origin عندما يكون Origin الخاص بالطلب موجودًا في allowed list الخاصة بالمفتاح. أما origin غير الموجود في allowlist فلا يحصل على ACAO header، ولذلك يحجب المتصفح response.

لا توجد cookies — تستخدم platform API مصادقة bearer-token، ولذلك لا يوجد Access-Control-Allow-Credentials.

تنتقل Publishable keys داخل URLs إلى tile CDN​

يأخذ tile.kaleidr.com مفتاح publishable الخاص بك كـ query parameter باسم ?key=. وهذا مقصود، وله نتيجة يجب توضيحها: query strings يتم تسجيلها في CDN access logs وbrowser history وأي proxy في المنتصف.

وهذا مقبول لأن publishable key عام بطبيعته — فهو يصل بالفعل ضمن page source. والتحكم الذي يجعله آمنًا هو origin allowlist لكل مفتاح، التي يفرضها edge على كل tile request، بالإضافة إلى تقييد المفتاح بنطاق maps.

وهذا غير مقبول لـ server key. لا تضع kld_sk_… أبدًا داخل URL، وتذكر أن server key المسرب يكون مكشوفًا بالفعل عندما يرفضه API.

في كل مكان آخر — SDK session exchange وplatform API — ينتقل المفتاح كـ header وليس كـ query parameter.

نصائح​

  • استخدم bare origins (scheme://host[:port]) — دون path ودون trailing slash — لكي تتطابق تمامًا مع header Origin الخاص بالمتصفح.
  • https مطلوب باستثناء localhost / 127.0.0.1 (للاختبار المحلي).
  • استدعاءات server-to-server باستخدام مفتاح server (بدون browser Origin) لا تخضع لـ CORS، لكنها تستمر في المصادقة وفحص scope بشكل طبيعي.
  • تدعم server keys أيضًا IP allowlist اختيارية — ويتم رفض أي call من IP خارج القائمة باستخدام 403 ip_not_allowed حتى عندما يكون bearer صالحًا. أدِر ذلك في kaleidr.com/api-keys.