احراز هویت در API

برای ارسال درخواست به API داده‌هات، هر درخواست باید یک توکن API معتبر همراه داشته باشد. در این راهنما نحوه‌ی ارسال توکن، محدوده‌ی دسترسی‌ها و خطاهای مربوط به احراز هویت را بررسی می‌کنیم.

ساخت توکن

توکن‌های API در پنل کاربری داده‌هات، از منوی «امنیت» و بخش «توکن‌ها» ساخته می‌شوند. هنگام ساخت توکن، پروژه، نام و دسترسی‌های آن را تعیین می‌کنید. مراحل کامل در راهنمای توکن‌های API آمده است.

هشدار

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

ارسال توکن در درخواست

توکن را در سرآیند Authorization و با پیشوند Bearer به نشانی api.dadehat.com ارسال کنید:

bash

curl -H "Authorization: Bearer <TOKEN>" \
  "https://api.dadehat.com/api/v1/projects/<PROJECT_ID>"

ویژگی‌های توکن

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

دسترسی‌ها (Scopes)

هر دسترسی به‌شکل <resource>:<verb> نوشته می‌شود که در آن verb یکی از read (خواندن) یا write (مدیریت) است. دسترسی write شامل read نیز می‌شود و نیازی به انتخاب هر دو نیست. دسترسی * به معنای دسترسی کامل به همه‌ی منابع پروژه است.

منبع	شامل
project	اطلاعات پروژه و اعضای آن
vm	سرورها
volume	والیوم‌ها
snapshot	اسنپ‌شات‌ها و زمان‌بندی اسنپ‌شات
container	کانتینرها
network	ابر خصوصی، ساب‌نت، گروه امنیتی، آی‌پی الستیک، اینترنت گیت‌وی و توزیع‌کننده‌ی بار
registry	رجیستری‌های کانتینر
ssh-key	کلیدهای SSH
build	بیلد و دپلوی و اتصال به GitHub و GitLab
app	اپلیکیشن‌های بازارچه
bucket	فضای ابری (باکت‌ها و کلیدهای S3)

چند نمونه:

vm:read: فقط مشاهده‌ی فهرست و جزئیات سرورها.
vm:write: مشاهده، ساخت، تغییر و حذف سرورها.
network:write vm:write: مدیریت کامل شبکه و سرورها، بدون دسترسی به سایر منابع.

یادداشت

توجه داشته باشید که برای ساخت و حذف اسنپ‌شات با توکن، علاوه بر snapshot، دسترسی volume:write نیز لازم است.

دریافت اطلاعات توکن

اسکریپت‌ها و ابزارهای خودکار می‌توانند در ابتدای کار، پروژه و دسترسی‌های توکن را از نشانی زیر دریافت کنند. توجه کنید که این درخواست به نشانی iam.dadehat.com ارسال می‌شود:

bash

curl -H "Authorization: Bearer <TOKEN>" \
  "https://iam.dadehat.com/tokens/self"

json

{
  "success": true,
  "data": {
    "key_id": "b6f1c2a4-9e3d-4a1b-8c7f-2d5e6f7a8b9c",
    "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "scopes": ["container:write", "vm:read", "vm:write"]
  }
}

پیشنهاد می‌شود این درخواست را یک بار در ابتدای اجرا ارسال کنید تا شناسه‌ی پروژه را برای درخواست‌های بعدی داشته باشید و پیش از شروع کار، از کافی بودن دسترسی‌ها مطمئن شوید.

احراز هویت حساب و توکن

برخی عملیات، مانند ساخت منابع و آغاز عملیات‌ها، فقط برای حساب‌هایی مجاز است که احراز هویت آن‌ها کامل شده باشد. در مورد توکن، وضعیت احراز هویت عضو سازنده‌ی توکن ملاک است؛ توکنی که یک عضو احراز هویت‌نشده ساخته است، حتی با دسترسی کامل نمی‌تواند این عملیات را انجام دهد و پاسخ 403 با کد kyc_not_verified دریافت می‌کند.

خطاهای احراز هویت

وضعیت	کد	علت
401	—	توکن ارسال نشده، نامعتبر، منقضی یا باطل شده است، یا مسیر درخواست با توکن در دسترس نیست.
403	insufficient-scope	توکن دسترسی لازم برای این درخواست را ندارد.
403	kyc_not_verified	احراز هویت حساب سازنده‌ی توکن کامل نیست.
404	not-found	منبع وجود ندارد یا متعلق به پروژه‌ای غیر از پروژه‌ی توکن است.
429	—	تعداد درخواست‌ها در بازه‌ی کوتاه بیش از حد مجاز است.

در صورت دریافت خطای 401، با درخواست tokens/self بررسی کنید که توکن هنوز فعال است و به کدام پروژه وابسته است.

چرخش و ابطال توکن

چرخش توکن: با «چرخش توکن» در پنل، یک مقدار محرمانه‌ی جدید برای همان توکن ساخته می‌شود و مقدار قبلی بلافاصله از کار می‌افتد. فقط عضوی که توکن را ساخته است می‌تواند آن را بچرخاند.
ابطال توکن: با «ابطال توکن»، توکن برای همیشه غیرفعال می‌شود. هر عضو با نقش ویرایشگر یا بالاتر می‌تواند توکن‌های پروژه را باطل کند.

هشدار

پس از چرخش توکن، مقدار جدید را بلافاصله در تنظیمات اسکریپت یا ابزار CI/CD خود جایگزین کنید؛ در غیر این صورت درخواست‌های بعدی با خطای 401 مواجه می‌شوند.

توصیه‌های امنیتی

توکن را در کد منبع یا مخزن Git قرار ندهید و آن را در بخش متغیرهای محرمانه‌ی ابزار CI/CD یا یک سامانه‌ی مدیریت اسرار نگه‌داری کنید.
برای هر کاربرد یک توکن جداگانه با کم‌ترین دسترسی لازم بسازید؛ برای نمونه، ابزاری که فقط وضعیت سرورها را می‌خواند به vm:read نیاز دارد.
برای توکن‌ها تاریخ انقضا تعیین کنید و آن‌ها را به‌شکل دوره‌ای بچرخانید.
توکن‌هایی را که دیگر استفاده نمی‌کنید، بلافاصله باطل کنید.