Document
English

Open Authentication

معرفی

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

فعال سازی

برای فعالسازی قابلیت لاگین با گپ باید یک بات با oAuth فعال داشته باشید. بدین منظور وارد پورتال مای گپ خود شوید و از طریق گزینه بات پلتفرم وارد لیست بات ها شوید و گزینه OAuth را برای یکی از بات های موجود فعال کنید یا بات جدیدی با این قابلیت بسازید.

شما باید یک آدرس بازگشت تعیین کنید که برنامه ی احراز هویت گپ کد احراز هویت را به آن ارسال کند. همچنین در این مرحله یک client id برای بات شما تولید می شود که در ادامه به آن نیاز خواهید داشت. همچنین توکن بات مورد نظر حکم client secret را که در مراحل بعد به آن نیاز خواهید داشت دارد.

اعطای مجوز (authorize)

برای گرفتن مجوز از گپ باید آدرس زیر را در لینک لاگین قرار داده و پارامترهای مورد نیاز را به آن ارسال کنید .

https://login.gap.im/oauth/authorize?client_id=your_client_id&grant_type=code

پارامترها

1 client_id id ‌مربوط به کلاینت که در مرحله فعال سازی OAuth برای بات خود دریافت کرده اید.
2 grant_type نوع مجوز که مقدار آن را برابر code قرار دهید.

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

نمونه خروجی موفق :

  http://example.com/?code=445ce0df9d444484e378a3a23571dbc213f9ebde&state=
نمونه خروجی ناموفق :

  http://example.com/?error=access_denied&error_description=the+user+canceled+the+authentication

گرفتن توکن (token)

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

https://login.gap.im/oauth/token?client_id=your_client_id&grant_type=code&code=your_authorize_code&client_secret=your_client_secret

پارامترها

1 client_id id ‌مربوط به کلاینت که در مرحله فعال سازی OAuth برای بات خود دریافت کرده اید.
2 grant_type نوع مجوز که مقدار آن را برابر code قرار دهید. درصورتیکه می خواهید با استفاده از refresh_token؛ access_token جدید دریافت کنید مقدار آن رابرابر refresh_token قرار دهید.
3 code کد احراز هویت که در مرحله قبل دریافت کرده اید.
4 client_secret کد امنیتی که در واقع همان توکن بات شماست که OAuth را برای آن فعال کرده اید.
5 refresh_token در صورتیکه access_token شما منقضی شده است و می خواهید توکن جدید دریافت کنید این پارامتر را به همراه grant_type = refresh_token ارسال نمایید.

اگر پارامترها را به درستی ارسال کرده باشید اطلاعات کاربر به همراه access_token و refresh_token را دریافت خواهید کرد. برای به حداقل رساندن درخواست ها این دو پارامتر را ذخیره کنید. طول عمر این پارامترها از مقادیر expires_in و expires_on که به ترتیب بیانگر طول عمر توکن و زمان انقضای آن می باشند قابل تشخیص است.

نمونه خروجی موفق :

{
  "status": "success",
  "message": "ok",
  "data": {
    "publicInfo": {
      "gap_id": 1114959,
      "nickname": "ali",
      "username": "",
      "avatar": {
        "64": null,
        "128": null,
        "256": null,
        "512": null
      },
      "chat_id": 0
    },
    "token_type": "bearer",
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzZXJ2aWNlX2lkIjp7IiRvaWQiOiI1YWY3ZTE2NzBmYTcyNTA0YmE1NzgyNzUifSwiZ2FwX3VzZXJfaWQiOjExMTQ5NTksImNvbnRlbnRfcHJvdmlkZXJfaWQiOnsiJG9pZCI6IjViMzllMzI0ZTNhZGU5MTc5MjY4NjRlNCJ9LCJpYXQiOjE1MzM4MDAwMjYsImV4cCI6MTUzMzgwMzYyNn0.5fveXG9Ed76nvk3rc1R-oht0UuXlAz3dMXTTGXfwow8",
    "refresh_token": "d89454a16802126888da5b3e53940de6857bd179",
    "expire_in": 3600,
    "expire_on": 1533803626
  },
  "code": 200
}
نمونه خروجی ناموفق :

{
  "status": "error",
  "message": "Invalid Authorization Code ! ",
  "code": 401
}

پس از منقضی شدن access_token با استفاده از refresh_token می توانید access_token جدید دریافت کنید. بدین منظور باید پارامتر grant_type را برابر refresh_token قرار دهید و به همراه refresh_token و client_secret ارسال نمایید.

https://login.gap.im/oauth/token?client_id=your_client_id&grant_type=refresh_token&refresh_token=your_refresh_token&client_secret=your_client_secret
نمونه خروجی موفق :

{
  "status": "success",
  "message": "ok",
  "code": 200,
  "data": {
    "token_type": "bearer",
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzZXJ2aWNlX2lkIjp7IiRvaWQiOiI1YWY3ZTE2NzBmYTcyNTA0YmE1NzgyNzUifSwiZ2FwX3VzZXJfaWQiOjExMTQ5NTksImNvbnRlbnRfcHJvdmlkZXJfaWQiOnsiJG9pZCI6IjViMzllMzI0ZTNhZGU5MTc5MjY4NjRlNCJ9LCJpYXQiOjE1MzQwNjkwODcsImV4cCI6MTUzNDA3MjY4N30.Ud-7tVdYtSZ-M8aHTpAvozDhTuBJ0w2Plug36FsC24c",
    "refresh_token": "7c71ab48d9015c423b228ab0212a7a07f4157214",
    "expire_in": 3600,
    "expire_on": 1534072687
  }
}
نمونه خروجی ناموفق :

{
  "status": "error",
  "message": "invalid request !",
  "code": 400
}