oauth

احراز باز

برخی قابلیت‌های کنار دیوار‌ نیازمند اجازه‌ی کاربرها هستند: مثلا افزودن محتوا به آگهی یا دریافت اطلاعات کاربر نیازمند کسب اجازه از کاربر است. در کنار دیوار، فرآیند کسب اجازه از کاربر طبق استاندارد OAuth 2.0 انجام می‌شود:

۱. 🖐️ اپلیکیشن کاربر را برای کسب اجازه به دیوار هدایت (redirect) می‌کند.
۲. ↪️ کاربر، بعد از صدور یا رد اجازه‌های درخواستی، به آدرس مشخص‌شده توسط اپلیکیشن (redirect URI) هدایت می‌شود.
۳. 🗝️ درصورت صدور اجازه، اپلیکیشن می‌تواند از دیوار توکنی (access token) برای استفاده از قابلیت‌های مدنظر دریافت ‌کند.
۴. 🔮 اپلیکیشن با استفاده از توکن دریافتی، از قابلیت‌های مدنظر استفاده می‌کند.

sequenceDiagram
  app->>+divar: 1. Redirect
  divar->>-app: 2. Redirect to <redirect_uri> with <code>
  app-->>+divar: 3. Request access token with <code>
  divar-->>-app: <access_token>
  app-)divar: 4. Request API with <access_token>

Loading

---

🚀 ابزارهای متنوعی برای کار با استاندارد OAuth 2.0 در زبان‌ها و فریم‌ورک‌های مختلف وجود دارد. برخی از این ابزارها را می‌توانید اینجا ببینید.

---

🖐️ گام اول: درخواست اجازه

برای درخواست اجازه، کاربر را به آدرسی به شکل زیر هدایت (redirect) کنید:

https://open-platform-redirect.divar.ir/oauth?response_type=code
  &client_id=<app-slug>
  &redirect_uri=<redirect-uri>
  &scope=<scopes>
  &state=<state>

• پارامتر client_id: در این پارامتر شناسه‌ی اپلیکیشن (Slug در پنل کنار) را قرار دهید.
• پارامتر redirect_uri: آدرسی از اپلیکیشن که کاربر بعد از صدور (یا رد) اجازه‌های درخواستی به آن هدایت شود.
  • هیچ پارامتری در این آدرس قرار ندهید!
  • مقدار redirect_uri حتما باید URL encode شده باشد.
• پارامتر scope: اجازه‌های مورد نیاز را در این پارامتر لیست و با + از هم جدا کنید. در مورد اجازه‌ها اینجا را بخوانید.
• پارامتر state: یک مقدار دلخواه که در بازگشت کاربر به اپلیکیشن شما مجدد در پارامترهای URL قرار می‌گیرد.
  • با استفاده از پارامتر state می‌توانید منشاء درخواست بازگشته را احراز نمایید.
  • اگر برای redirect_uri نیاز به تنظیم پارامتری دارید، مقادیر این پارامترها را می‌توانید در state ذخیره کنید.
  • دقت کنید که حتما state شامل مقادیری یکتا و تصادفی باشد تا بتوانید درخواست‌های بازگشت دروغین را تشخیص دهید.

🛂 اجازه‌ها (Scope)

قابلیت‌های مختلف، نیازمند کسب اجازه (یا scope)های متفاوت از کاربر هستند. برخی از این اجازه‌ها مربوط به شیء خاصی هستند: مثلا برای افزودن محتوا به یک آگهی خاص، می‌بایست اجازه‌ی ساخت افزونه بر روی همان آگهی را از کاربر دریافت کنید. این نوع اجازه‌ها از شکل کلی SCOPE__IDENTIFIER تبعیت می‌کنند که در آن:

• قسمت SCOPE نمایانگر کلی اجازه‌ی مربوطه (مثلا اضافه کردن افزونه به آگهی) است.
• قسمت IDENTIFIER نمایانگر شیء خاصیست که اجازه مربوط به آنست (مثلا شناسه‌ی آگهی).

💡 مثال
برای دریافت اجازه‌ برای اضافه کردن افزونه به آگهی با شناسه‌ی AZTH74V2، پارامتر scope را به شکل زیر مقدار دهید. شناسه‌ی آگهی را می‌توانید از پارامتر post_token که هنگام فراخوانی اپلیکیشن ارائه شده است بخوانید.

&scope=ADDON_USER_APPROVED__AZTH74V2

برخی اجازه‌های دیگر مربوط به شیء خاصی نیستند و عمومی هستند: برای مثال دریافت شماره‌ی تلفن کاربر (برای یک کاربر خاص) یک اجازه (scope) عمومیست. این نوع اجازه‌ها با شکل ساده‌ی SCOPE نمایانده می‌شوند.

💡 مثال
برای دریافت اجازه‌ی دسترسی به شماره‌ی تلفن کاربر، پارامتر scope را به شکل زیر تنظیم کنید:

&scope=USER_PHONE

پارامتر scope می‌تواند شامل چند اجازه‌ باشد، که در این صورت باید از فرم کلی SCOPE_1+SCOPE_2+SCOPE_3+... تبعیت کند.

💡مثال
برای دریافت همزمان اجازه‌ی دسترسی به شماره‌ی کاربر و اجازه‌ی اضافه کردن افزونه به آگهی با شناسه‌ی AZTH74V2، پارامتر scope را به شکل زیر مقدار دهید:

&scope=USER_PHONE+ADDON_USER_APPROVED__AZTH74V2

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

قابلیت	اجازه	مثال
ساخت افزونه	ADDON_USER_APPROVED	ADDON_USER_APPROVED__AZTH74V2
ارسال پیام در چت	CHAT_SEND_MESSAGE_OAUTH	CHAT_SEND_MESSAGE_OAUTH__ZTliYThhODEtOTU4M
دریافت شماره‌ی تلفن کاربر	USER_PHONE	USER_PHONE

---

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

---

↪️ گام دوم: بازگشت به اپلیکیشن

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

https://open-platform-redirect.divar.ir/oauth?response_type=code
  &cliend_id=...
  &scope=...
  &state=my-random-string
  &redirect_uri=oauth-redirect.my-app.ir

بعد از اتمام فرآیند، کاربر به آدرسی به شکل زیر هدایت می‌شود:

https://oauth-redirect.my-app.ir
  ?state=my-random-string
  &code=c87sDtaqmWwgis7dYyukMqy6KAArNUFkukAPW8O90GmiEJkdmSTWH4KjSkNUP6FZ

پارامتر state معادل مقدار تنظیم شده توسط اپلیکیشن است. برای آن مقدار تصادفی و یکتایی (برای هر session) تنظیم کنید و هنگام بازگشت این مقدار را چک کنید تا جلوی سوءاستفاده‌های احتمالی را بگیرید.

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

🗝️ گام سوم: دریافت توکن

در صورت دریافت اجازه از جانب کاربر و دریافت code، می‌توانید اقدام به دریافت access token از دیوار نمایید. در این توکن اجازه‌های دریافتی از جانب کاربر ذخیره شده‌اند و با استفاده از آن می‌توانید از قابلیت‌های نیازمند اجازه استفاده کنید.

برای دریافت access token، درخواستی به شکل زیر بفرستید:

POST https://api.divar.ir/v1/open-platform/oauth/access_token
Content-Type: application/json

{
  "code": "c87sDtaqmWwgis7dYyukMqy6KAArNUFkukAPW8O90GmiEJkdmSTWH4KjSkNUP6FZ",
  "client_id": "{{app_slug}}",
  "client_secret": "{{api_key}}",
  "grant_type": "authorization_code",
}

• پارامتر code: مقدار دریافتی در گام قبل را قرار دهید.
• پارامتر client_id: مانند گام اول، شناسه‌ی اپلیکیشن (Slug در پنل کنار) را قرار دهید.
• پارامتر client_secret: یک کلید API متعلق به اپلیکیشن خود را اینجا قرار دهید.
  • کلید را همچنان در هدر x-api-key نیز قرار دهید.

همچنین در صورتی که ترجیح می‌دهید Content-Type درخواست خود را x-www-form-urlencoded قرار دهید،‌ می‌توانید درخواستی به شکل زیر بفرستید:

POST https://api.divar.ir/v1/open-platform/oauth/url_encoded_access_token
Content-Type: application/x-www-form-urlencoded

code: "c87sDtaqmWwgis7dYyukMqy6KAArNUFkukAPW8O90GmiEJkdmSTWH4KjSkNUP6FZ"
client_id: "{{app_slug}}"
client_secret: "{{api_key}}"
grant_type: "authorization_code"

پاسخ به این درخواست‌ها به شکل زیر خواهد بود:

{
  "access_token": "f2mjqwiYDigBwGYg2...",
  "expires": 1692457372
}

• پارامتر access_token: با استفاده از این پارامتر می‌توانید از قابلیت‌های نیازمند اجازه‌ استفاده کنید.
• پارامتر expires: توکن دریافت شده تا این تاریخ معتبر خواهد بود. تاریخ به فرمت unix ارائه شده.

🔮 گام چهارم: استفاده از توکن

پس از دریافت توکن با اجازه‌های مورد نیاز، می‌توانید از قابلیت‌های نیازمند این اجازه‌ها استفاده کنید. توکن دریافتی در گام قبل را در هدر x-access-token قرار دهید و API مربوط به قابلیت مورد نظر را فراخوانی کنید.

💡مثال
برای دریافت شماره‌ی تلفن کاربر، پس از طی مراحل کسب اجازه از کاربر، درخواستی به شکل زیر ارسال نمایید:

POST https://api.divar.ir/v1/open-platform/users
Content-Type: application/json
x-api-key: {{api_key}}
x-access-token: {{access_token}}

پاسخ این درخواست به شکل زیر خواهد بود:

{
  "phone_numbers": ["09990000000"]
}

دقت کنید که هم کلید API (api_key) هم توکن اجازه‌ی کاربر (access_token) هر دو برای فراخوانی این قابلیت‌ها لازم‌اند.