امنیت
هر کدام از دو کلید شما کجا میتواند باشد، چه چیزی از آن محافظت میکند، و چکلیست پیش از راهاندازی.
دانشیار سه نوع اعتبارنامه دارد و هرکدام فقط در یک جا امن است.
کلید سرور و کلید مرورگر
با این جدول تصمیم بگیرید هرکدام کجا برود:
| جایی که میفرستیدش | چه کسی از آن استفاده میکند | قاعده |
|---|---|---|
X-API-Key | سرور شما، وقتی REST API (/v1) را صدا میزند. | محرمانه. در متغیر محیطی سرور یا یک ابزار نگهداری رمزها نگهش دارید. هیچوقت آن را به مرورگر نفرستید. |
data-api-key | ابزارک در صفحههای عمومی شما. | عمومی؛ هر کسی میتواند ببیندش. یک کلید جداگانهٔ ابزارک (pk_…) است که فقط میتواند سؤال بپرسد. |
Authorization: Bearer | کنسول دانشیار، بعد از ورود. | کنسول خودش مدیریتش میکند. با /v1 کار نمیکند و هیچوقت لازم نیست کپیاش کنید. |
امن کردن کلید ابزارک
سایت دیگری نمیتواند از آن استفاده کند: هم مرورگر و هم سرور ما دامنههای مجاز شما را بررسی میکنند. اما اسکریپتی بیرون از مرورگر هنوز میتواند خودش را جای سایت شما جا بزند؛ پس این چهار کار را بکنید:
- محدودیتهایی را که از شما محافظت میکنند بشناسید: تعداد سؤال برای هر بازدیدکننده و هر اپ محدود است، هر سؤال حداکثر ۲٬۰۰۰ نویسه است و هزینهٔ هر پاسخ از کیف پول شما کم میشود. ابزارک را فقط برای همان فضای کاریای روشن کنید که در سایت گذاشتهاید.
- فقط اسنادی را بارگذاری کنید که از انتشارشان مشکلی ندارید. هیچوقت پروندهٔ بیمار یا فایل خصوصی در آن نگذارید.
- فقط سایتهای واقعی خودتان را به دامنههای مجاز اضافه کنید. بقیهٔ سایتها بهطور پیشفرض مسدودند.
- هیچوقت کلید محرمانه (sk_…) را در کد ابزارک یا هیچ کد سمت کاربر نگذارید. اگر از کلید ابزارک سوءاستفاده شد، برای کلید ابزارک «ساخت کلید جدید» را بزنید.
دامنههای مجاز از چه چیزی محافظت میکنند
دامنههای مجاز دو بار بررسی میشوند. مرورگر یک قاعدهٔ frame-ancestors را روی صفحهٔ ابزارک اجرا میکند و سرور ما هم هر سؤال را با فهرست مقایسه میکند. همهٔ سایتها بهطور پیشفرض مسدودند: فهرست خالی به هیچ سایتی اجازه نمیدهد.
- جلوی این را میگیرد: سایت دیگری ابزارک شما را به بازدیدکنندههای خودش نشان دهد یا از صفحههایش API ابزارک را صدا بزند و از کیف پول شما خرج کند.
- بهطور کامل جلوی این را نمیگیرد: اسکریپتی بیرون از مرورگر (مثلاً curl) که کلید ابزارک را کپی کند و نشانی صفحه را جعل کند. هیچ کلید عمومیای نمیتواند جلوی این را بگیرد. محدودیت تعداد درخواست — برای هر بازدیدکننده و هر اپ — هزینهاش را برای شما محدود میکند.
نوشتن دامنهها: دامنههای مجاز.
محدودیت تعداد درخواست
ابزارک سه محدودیت دارد: ۲۰ سؤال در ساعت برای هر نشانی IP، ۵۰۰ سؤال در روز برای هر اپ، و ۶۰ بار بارگذاری در ساعت برای هر نشانی IP. جزئیات در محدودیتها و هزینه آمده است.
REST API (/v1) فقط برای بارگذاری فایل (۶۰ بار در ساعت) و پردازش دوباره (۳۰ بار در ساعت) محدودیت دارد؛ بقیهٔ درخواستها هنوز محدودیتی ندارند. اگر آن را پشت مسیر خودتان گذاشتهاید، همانجا برای هر کاربر محدودیت بگذارید تا یک نفر نتواند همهٔ اعتبارتان را خرج کند.
CORS
CORS یک قاعدهٔ مرورگر است و تعیین میکند کدام سایتها میتوانند با JavaScript یک API را صدا بزنند.
- ابزارک به تنظیم CORS از طرف شما نیازی ندارد؛ داخل iframe و روی سایت خود دانشیار اجرا میشود.
- صدا زدن
/v1با JavaScript سایت خودتان، با CORS مسدود میشود. این عمدی است: آن را از سرورتان صدا بزنید. - اگر سایتتان Content-Security-Policy میفرستد، سایت ابزارک را در
script-srcوframe-srcمجاز کنید؛ وگرنه مرورگر اسکریپت و iframe را مسدود میکند.
عوض کردن و باطل کردن کلیددر نقشهٔ راه: بهزودی
صفحهٔ اپ را در کنسول باز کنید. هر کلید — ابزارک و محرمانه — دکمههای «ساخت کلید جدید» و «حذف» خودش را دارد. کلید قدیمی همان لحظه باطل میشود.
چکلیست پیش از راهاندازی
- کلید محرمانه (sk_…) فقط در متغیرهای محیطی سرور است؛ نه در Git و نه در هیچ کد سمت کاربر.
- ابزارک اپ جداگانهٔ خودش را دارد که فقط اسناد عمومی در آن است.
- فهرست دامنههای مجاز فقط سایتهای واقعی شما را دارد و دامنهٔ آزمایشی جاماندهای در آن نیست.
- مسیر گفتوگوی خودتان، اگر دارید، محدودیت تعداد درخواست دارد و برای هر کاربر یک external_user_id میفرستد.
- Content-Security-Policy سایتتان اسکریپت و iframe ابزارک را مجاز میکند.
- میدانید اگر کلیدی لو رفت با چه کسی تماس بگیرید.