مصادقة واجهة API للخرائط

يفصل التصميم الآمن لمصادقة API بيانات الاعتماد بحسب بيئة التشغيل. يحتاج المتصفح إلى بيانات يمكن كشفها بأمان وتقييدها بالأصول والقدرات المعتمدة، بينما تحتاج الواجهة الخلفية إلى سر لا يدخل شيفرة العميل ويصرّح بعمليات خادم إلى خادم. لا ينبغي أن يكونا قابلين للتبادل. قلّل النطاقات، وافصل البيئات، وراقب الاستخدام، ودوّر بيانات الاعتماد، وميّز فشل المصادقة عن فشل التفويض. تنفذ Kaleidr ذلك بمفاتيح قابلة للنشر (kld_pk_live_…) ومفاتيح خادم (kld_sk_live_…).

تتناول الأقسام التالية بيانات المتصفح والخادم والأصول وCORS والنطاقات ودورة الحياة وحدود الثقة متعددة المستأجرين والأخطاء الشائعة. راجع وثائق المطورين، وما حزمة SDK للخرائط بالذكاء الاصطناعي؟، وكيفية تضمين خريطة تفاعلية، ودردشة AI على Mapbox وGoogle Maps وMapLibre.

أساسيات المصادقة

• بيئة التشغيل أولًا: بيانات المتصفح مصممة للكشف، وبيانات الخادم للسرية.
• الأصل ≠ المصادقة: لا يحل CORS والأصول المسموح بها محل فحص بيانات الاعتماد.
• النطاق ≠ المستأجر: نطاقات قدرات API ليست تفويض مستخدم أو صف بيانات.
• دوّر بأمان: انشر البديل قبل إبطال مفتاح نشط.
• احجب السجلات: سجّل معرّفات المفاتيح ورموز الحالة، لا قيم الاعتماد.

لماذا تختلف مصادقة API في المتصفح؟

المتصفح بيئة غير موثوقة. يمكن عادةً فحص كل ما يصل إليه عبر مصدر الصفحة وأدوات المطور وطلبات الشبكة وJavaScript المجمّع والتخزين وكائنات وقت التشغيل. وضع سر خادم طويل الأجل في شيفرة العميل—مصدر React أو متغيرات Next.js NEXT_PUBLIC_* أو Vite VITE_* أو HTML أو WebView أو JSON للواجهة—غير آمن، لأن المتصفح لا يستطيع إخفاءه عن مستخدمه. اسأل عما تسمح به بيانات الاعتماد وأين تعمل، لا أين تخفيها في حزمة الواجهة.

تختلف الأسماء لكن النمط شائع. تستخدم Kaleidr مفاتيح قابلة للنشر وأخرى للخادم (Auth & Scopes). يميز Mapbox نطاقات الرموز العامة والسرية ويطلب إرسال طلبات الرمز السري من الخادم (استخدام Mapbox بأمان). تستخدم Google Maps Platform قيود التطبيق وAPI وتوصي بحماية بيانات خدمات الويب، وبـOAuth 2.0 عند دعمه بين الخوادم (إرشادات الأمان).

كيف تعمل مفاتيح Kaleidr؟

تعرّف الوثائق الحالية نوعين ضمن نظام المؤسسة والقدرات نفسه. يستخدم kld_pk_live_… في HTML وSDK و<kaleidr-map> وتكاملات المتصفح. يستبدله SDK وقت التشغيل بجلسة قصيرة مرتبطة بالأصل بدل استخدام السلسلة كـbearer دائم. يستخدم kld_sk_live_… على خوادم موثوقة فقط، عادةً في Authorization: Bearer … أو X-Api-Key: …. وهو محظور في المتصفح ولا يحصل على تصريح CORS (CORS & Allowed Origins). لا تضع مفتاح خادم في العميل ولا تعامل متغير واجهة عامًا كمخزن أسرار.

يجب أن تكون الأصول المسموح بها بلا مسار أو شرطة مائلة ختامية، مثل https://app.example.com لا https://app.example.com/maps. تتطلب Kaleidr HTTPS إلا للاختبار على localhost أو 127.0.0.1. الجذر وwww وapp وadmin والمعاينة أصول مختلفة. تقلل القيود إعادة الاستخدام غير المصرح بها، لكنها لا تعوض إبقاء أسرار الخادم خارج العميل.

كيف تختلف CORS والمصادقة والنطاق والتفويض؟

تحدد CORS هل يستطيع المتصفح قراءة استجابة عبر أصل مختلف. تعرّف المصادقة المتصل، ويحدد النطاق هل يملك قدرة مطلوبة، ويقرر تفويض التطبيق أي مستخدم أو مستأجر يصل إلى السجلات الخاصة. قد تسمح Kaleidr بطلب preflight، لكنها تعيد Access-Control-Allow-Origin للأصل المسموح فقط؛ ولا تمنح مفاتيح الخادم CORS للمتصفح. يعني 401 غالبًا اعتمادًا مفقودًا أو غير صالح أو منتهيًا أو مبطلًا. ويعني 403 اعتمادًا صالحًا بلا إذن؛ تستخدم Kaleidr insufficient_scope عند غياب قدرة المسار. عالجهما كفشلين مختلفين.

كيف تُنشأ بيانات الاعتماد وتُخزن وتُدوّر وتُبطل؟

طبّق أقل صلاحية وامنح كل تكامل نطاقاته اللازمة فقط. يوصي Mapbox بأقل نطاقات وبالنطاقات العامة فقط في المتصفح؛ وتوصي Google بقيود التطبيق وAPI الفعلية. لا تشارك مفتاحًا بين التطوير والمعاينة والإنتاج. يقلل الفصل نطاق الضرر ويسهّل التدوير. يوصي Mapbox برمز لكل بيئة أو عميل، وGoogle بمفتاح لكل تطبيق (إدارة الرموز).

تظهر قيمة مفتاح Kaleidr الجديد مرة واحدة؛ انسخها فورًا إلى مدير أسرار. خزّن مفاتيح الخادم في مدير أو بيئة خادم محمية، لا في مستودع عام أو حزمة متصفح. في CI/CD، احقن الأسرار وقت النشر واحجبها في السجلات ولا تطبع تفريغ البيئة. سجّل المعرّف والحالة والأصل، واحجب ترويسات التفويض والقيم. أنشئ بديلًا وقيّده وانشره وتحقق من الحركة، ثم أبطل القديم—وأسرع عند الاختراق. الحصص ضابط أمان أيضًا: يقاس الاستخدام على مستوى المؤسسة وتحد خدمات البث التزامن (Quota & Rate Limits). عامل 429 بشكل مختلف عن 401 و403 واستخدم التراجع بدل عواصف إعادة المحاولة.

// Unsafe: never ship a server key to the browser
const SERVER_KEY = "YOUR_KALEIDR_SERVER_KEY";

// Safer browser pattern: publishable key + SDK session exchange
Kaleidr.mount("#map", {
  publishableKey: "kld_pk_live_REPLACE_ME"
});

// Safer backend pattern: server key stays on the host
const response = await fetch("https://api.example.com/resource", {
  headers: {
    Authorization: `Bearer ${process.env.KALEIDR_SERVER_KEY}`
  }
});

كيف تفصل تطبيقات الإنتاج مصادقة المنصة عن المضيف؟

يستخدم النمط الموصى به مفتاحًا قابلًا للنشر لوظائف SDK العامة عبر أصل معتمد، بينما تذهب طلبات المنتج المصادق عليها إلى الواجهة الخلفية. تملك الخلفية هوية المستخدم وعضوية المستأجر وتفويض الكائنات وبيانات الموقع الخاصة ومفتاح الخادم في مدير أسرار، ثم تجري مكالمات خادم إلى خادم وتعيد الحقول المعتمدة فقط. المفتاح القابل للنشر ليس مصادقة مستخدم، ومفتاح الخادم ليس تفويض صف قاعدة بيانات. تقول الوثائق إن خريطة Viewer المنشورة محكومة برابط مشاركة ولا تحتاج مفتاح API؛ ومع ذلك عامل الرابط كتحكم وصول ولا ترسل بيانات خاصة عبر عرض عام بلا قيود. تكمل CSP وعرض HTML الآمن ذلك؛ يحذر Mapbox من XSS عند إدخال HTML غير موثوق في النوافذ ويوصي بعرض النص.

ما الأخطاء التي ينبغي تجنبها؟

عند فشل المتصفح تحقق من كتابة الأصل وHTTPS ونوع المفتاح والنطاق وترتيب تبادل الجلسة. وعند فشل الخادم تحقق من النوع والبيئة والنطاق وحقن السر والإبطال العرضي.

الحكم النهائي

يبدأ أمان API بقرار واحد: لا تستخدم نموذج الاعتماد نفسه في المتصفح والخلفية. يحتاج المتصفح بيانات قابلة للكشف ومقيدة بالأصل والنطاق وعمر الجلسة؛ وتحتاج الخلفية أسرارًا في بنية موثوقة. أضف أقل صلاحية وعزل البيئة وتفويض التطبيق والمراقبة والتدوير. تتبع Kaleidr هذا النمط: مفاتيح المتصفح مقيدة بالأصل ويستبدلها SDK بجلسات قصيرة، ومفاتيح الخادم bearer لمكالمات الخادم ومحظورة في المتصفح. هذا الحد أهم من محاولة إخفاء مفتاح في الواجهة.

أمّن API الخرائط باستخدام وثائق Kaleidr

راجع أنواع المفاتيح والنطاقات وقواعد الأصل وسلوك API قبل النشر. اقرأ Kaleidr Auth & Scopes ثم تابع وثائق المطورين لتركيبات SDK ومسارات Platform API.

الأسئلة الشائعة

ما مصادقة API للخرائط؟

هي آلية تعريف تطبيق أو خدمة تطلب الوصول إلى API للخرائط أو الأماكن أو التجانبات أو التوجيه أو البيانات المكانية. تشمل المفاتيح والرموز والجلسات وbearer وOAuth.

هل يمكن استخدام مفتاح API بأمان في المتصفح؟

فقط إذا صممه المزود للعميل. يجب تقييده بالأصول أو النطاقات العامة أو التطبيق أو جلسة قصيرة. لا يوضع سر الخادم في المتصفح.

هل المفتاح القابل للنشر سر؟

لا. يجب ألا يعتمد أمانه على إخفاء السلسلة، لكنه يحتاج قيودًا ومراقبة.

هل مفتاح الخادم سر؟

نعم. يبقى في خلفية موثوقة ولا يظهر في HTML أو حزم JavaScript أو WebView أو المستودعات العامة أو تخزين العميل.

هل CORS مصادقة؟

لا. تتحكم CORS في قراءة الاستجابة، وتعرّف المصادقة المتصل، ويحدد التفويض ما يستطيع فعله.

ما الفرق بين 401 و403؟

يعني 401 غالبًا اعتمادًا مفقودًا أو غير صالح أو منتهيًا أو مبطلًا. ويعني 403 اعتمادًا صالحًا بلا إذن للعملية.

هل أفصل مفاتيح التطوير والإنتاج؟

نعم. يقلل ذلك نطاق الضرر ويبسط قيود الأصل ويحسن رؤية الاستخدام ويجعل التدوير أكثر أمانًا.

كيف أدوّر مفتاح API؟

أنشئ بديلًا واضبط قيوده وانشره وتحقق من حركة الإنتاج، ثم أبطل السابق. أسرع إذا كان القديم مخترقًا.

هل يحتاج Kaleidr Viewer إلى مفتاح API؟

تقول الوثائق الحالية إن خرائط Viewer المنشورة محكومة بروابط مشاركة ولا تحتاج مفتاح API.

كيف تحمي Kaleidr تكاملات المتصفح؟

تستخدم مفتاحًا قابلًا للنشر مع قائمة أصول؛ يستبدله SDK بجلسة قصيرة مرتبطة بالأصل. مفاتيح الخادم محظورة في المتصفح ومخصصة لمكالمات الخوادم.

المراجع

• IETF. HTTP Semantics (RFC 9110). RFC Editor. اطلع عليه في 17 أغسطس 2026. https://www.rfc-editor.org/rfc/rfc9110

• IETF. The OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750). RFC Editor. اطلع عليه في 17 أغسطس 2026. https://www.rfc-editor.org/rfc/rfc6750

• WHATWG. Fetch Standard. اطلع عليه في 17 أغسطس 2026. https://fetch.spec.whatwg.org/#http-cors-protocol

• Google. إرشادات أمان Google Maps Platform. تم الاطلاع في 17 أغسطس 2026. https://developers.google.com/maps/api-security-best-practices

• Kaleidr. Auth & Scopes. وثائق المطورين. تم الاطلاع في 17 أغسطس 2026. https://docs.kaleidr.com/platform-api/auth-and-scopes

• Kaleidr. CORS & Allowed Origins. وثائق المطورين. تم الاطلاع في 17 أغسطس 2026. https://docs.kaleidr.com/platform-api/cors-and-allowed-origins

• Kaleidr. Quota & Rate Limits. وثائق المطورين. تم الاطلاع في 17 أغسطس 2026. https://docs.kaleidr.com/platform-api/quota-and-rate-limits

• Mapbox. استخدام Mapbox بأمان. تم الاطلاع في 17 أغسطس 2026. https://docs.mapbox.com/help/dive-deeper/how-to-use-mapbox-securely/

• Mapbox. إدارة الرموز. تم الاطلاع في 17 أغسطس 2026. https://docs.mapbox.com/accounts/guides/tokens/

@misc{ietf_rfc9110_2026,
  title  = {HTTP Semantics (RFC 9110)},
  author = {{IETF}},
  note   = {Accessed 17 August 2026},
  url    = {https://www.rfc-editor.org/rfc/rfc9110}
}

@misc{ietf_rfc6750_2026,
  title  = {The OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750)},
  author = {{IETF}},
  note   = {Accessed 17 August 2026},
  url    = {https://www.rfc-editor.org/rfc/rfc6750}
}

@misc{whatwg_fetch_cors_2026,
  title  = {Fetch Standard},
  author = {{WHATWG}},
  note   = {CORS protocol; accessed 17 August 2026},
  url    = {https://fetch.spec.whatwg.org/#http-cors-protocol}
}

@misc{kaleidr_auth_scopes_2026,
  title  = {Auth and Scopes},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 17 August 2026},
  url    = {https://docs.kaleidr.com/platform-api/auth-and-scopes}
}

@misc{kaleidr_cors_origins_2026,
  title  = {CORS and Allowed Origins},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 17 August 2026},
  url    = {https://docs.kaleidr.com/platform-api/cors-and-allowed-origins}
}

@misc{kaleidr_quota_2026,
  title  = {Quota and Rate Limits},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 17 August 2026},
  url    = {https://docs.kaleidr.com/platform-api/quota-and-rate-limits}
}

@misc{mapbox_token_management_2026,
  title  = {Token Management},
  author = {{Mapbox}},
  note   = {Accessed 17 August 2026},
  url    = {https://docs.mapbox.com/accounts/guides/tokens/}
}

@misc{mapbox_secure_2026,
  title  = {How to Use Mapbox Securely},
  author = {{Mapbox}},
  note   = {Accessed 17 August 2026},
  url    = {https://docs.mapbox.com/help/dive-deeper/how-to-use-mapbox-securely/}
}

@misc{google_maps_security_2026,
  title  = {Google Maps Platform Security Guidance},
  author = {{Google}},
  note   = {Accessed 17 August 2026},
  url    = {https://developers.google.com/maps/api-security-best-practices}
}