احراز هویت
هر درخواست API، به‌جز چند درخواست عمومی که در مرجع مشخص شده‌اند، یک توکن دسترسی در سرآیند Authorization می‌خواهد:
Authorization: Bearer <access_token>
توکن را سرور ورود ابردرایو صادر می‌کند، همان سروری که صفحه‌ی ورود برنامه‌ی وب را نشان می‌دهد. نشانی آن معمولاً https://identity.<domain> است؛ نشانی دقیق را از مدیر سامانه بگیرید. در این بخش هرجا <domain> آمده، دامنه‌ی استقرار خودتان را بگذارید.
روش ورود
در موج اول فقط یک راه برای گرفتن توکن هست: ورود کاربر در صفحه‌ی ورود ابردرایو با استاندارد OpenID Connect، به روش Authorization Code با PKCE. برنامه‌ی وب ابردرایو هم همین کار را می‌کند.
- برنامه‌ی شما کاربر را به نشانی
/connect/authorizeسرور ورود می‌فرستد. - کاربر در صفحه‌ی ورود ابردرایو وارد می‌شود (با رمز، پیامک یا هر روشی که آن استقرار فعال کرده).
- سرور ورود کاربر را با یک کد به نشانی بازگشت برنامه‌ی شما برمی‌گرداند.
- برنامه‌ی شما کد را در
/connect/tokenبا توکن دسترسی و توکن تازه‌سازی عوض می‌کند.
مشخصات سرور ورود:
| مورد | مقدار |
|---|---|
| کشف خودکار | https://identity.<domain>/.well-known/openid-configuration |
| نشانی ورود | https://identity.<domain>/connect/authorize |
| نشانی توکن | https://identity.<domain>/connect/token |
| شناسه‌ی کلاینت | AbrDrive |
| رمز کلاینت | ندارد (کلاینت عمومی) |
| PKCE | الزامی، روش S256 |
| دامنه‌ها (scope) | openid profile email roles offline_access |
ورود بدون کاربر وجود ندارد: کلید API، حساب سرویس و ورود سرویس به سرویس در این موج پشتیبانی نمی‌شوند. اگر سرویس شما باید بدون حضور کاربر کار کند، یک بار با کاربر وارد شوید و از توکن تازه‌سازی برای گرفتن توکن‌های بعدی استفاده کنید.
پیش از اولین استفاده از Postman
سرور ورود فقط به نشانی‌های بازگشتی که از پیش ثبت شده‌اند کد می‌دهد و در نصب پیش‌فرض فقط نشانی‌های برنامه‌ی وب ثبت شده‌اند. از مدیر سامانه بخواهید نشانی بازگشت https://oauth.pstmn.io/v1/callback را برای ورود برنامه‌ی وب ثبت کند. روش کار برای مدیر سامانه در ثبت نشانی بازگشت برای برنامه‌ها آمده است.
اگر ورود از Postman پس از به‌روزرسانی ابردرایو دیگر کار نکرد، این نشانی باید دوباره ثبت شود.
تنظیم Postman
از برنامه‌ی دسکتاپ Postman استفاده کنید. در زبانه‌ی Authorization مجموعه یا درخواست:
| فیلد Postman | مقدار |
|---|---|
| Auth Type | OAuth 2.0 |
| Grant Type | Authorization Code (With PKCE) |
| Callback URL | گزینه‌ی Authorize using browser را روشن کنید (نشانی https://oauth.pstmn.io/v1/callback) |
| Auth URL | https://identity.<domain>/connect/authorize |
| Access Token URL | https://identity.<domain>/connect/token |
| Client ID | AbrDrive |
| Client Secret | خالی |
| Code Challenge Method | SHA-256 |
| Scope | openid profile email roles offline_access |
| Client Authentication | Send client credentials in body |
Get New Access Token را بزنید، در مرورگر وارد شوید و توکن را با Use Token به کار ببرید. پس از آن نشانی گره را بگیرید و x-container را طبق قراردادهای مشترک اضافه کنید.
درون توکن
توکن دسترسی یک JWT امضاشده است (رمزگذاری نشده) و این ادعاها را دارد:
| ادعا | معنا |
|---|---|
sub | شناسه‌ی کاربر |
email | ایمیل کاربر. سرور حساب مشترک کاربر را با همین ایمیل پیدا می‌کند. |
name، preferred_username | نام کاربری |
role | نقش‌ها، مثلاً admin برای مدیر سامانه |
اگر حساب کاربر ایمیل نداشته باشد، توکن او به درخواست‌هایی که فضای کاربر را لازم دارند پاسخ 401 می‌گیرد.
عمر توکن و تازه‌سازی
- عمر توکن دسترسی در نصب پیش‌فرض ۳ روز است.
- با دامنه‌ی
offline_accessیک توکن تازه‌سازی هم می‌گیرید. پیش از پایان عمر توکن دسترسی، آن را باgrant_type=refresh_tokenبه/connect/tokenبفرستید و همیشه آخرین توکن تازه‌سازی‌ای را که سرور برمی‌گرداند نگه دارید. - اگر حساب کاربر قفل یا غیرفعال شود، تازه‌سازی رد می‌شود و کاربر باید دوباره وارد شود.
توکن‌ها را مثل رمز عبور نگه دارید: هر کس توکن را داشته باشد تا پایان عمر آن به جای کاربر کار می‌کند.