ثبت‌نام/ورود - REST

هدف از این مستند امکان انجام کارهای اولیه با سرویس کاربران بکتوری می‌باشد. شما پس از این مستند باید بتوانید کاربر خود را ثبت نام کرده و با نام‌کاربری و رمز عبور آن ورود کنید.

نکته: در صورتی که با مفهوم REST و سرویس‌های سمت سرور و یا با دستور curl آشنایی ندارید، به آشنایی با REST مراجعه کنید.

پیش‌نیازها

  1. در صورتی که با سرویس کاربران آشنایی ندارید، به معرفی سرویس کاربران مراجعه کنید.
  2. اگر با فرآیند امنیتی ورود کاربران در بکتوری آشنایی ندارید، به فرآیند امنیتی بکتوری مراجعه کنید.

ثبت‌نام کاربران (Register)

با ثبت نام، کاربر می تواند اطلاعات خود را وارد کند و در سیستم ثبت نام کند. معولا کاربر برای ثبت نام لازم است که حداقل نام کاربری و رمز عبور خود را وارد کند. در صورتی که کاربران شما ایمیل خود را نیز وارد می‌کنند، لازم است که برای پروژه خود، تایید ثبت نام از طریق ایمیل را فعال کنید. با این کار کاربرانی که ثبت نام می‌کنند تا زمانی که از طریق ایمیل، ثبت نام خود را تایید نکنند، در سیستم غیر فعال هستند. در پروژه‌هایی که گزینه تایید ایمیل فعال نباشد، همه کاربران به محض ثبت نام (و بدون نیاز به تایید از طریق ایمیل) فعال می‌گردند.

curl -X POST \
    --header "X-Backtory-Authentication-Id: <ID>" \
    --header "Content-Type: application/json" \
    -d '{
        "firstName":"FIRSTNAME",
        "lastName":"LASTNAME",
        "username":"USERNAME",
        "password":"PASSWORD",
        "email":"aaa@bbb.ccc",
        "phoneNumber": "12345678",
        "avatar": "mydomain.com/avatar.png"
    }' https://api.backtory.com/auth/users


انواع پاسخ‌هایی که از این سرویس ممکن است دریافت کنید به صورت جدول زیر است:

Tables Description
200-OK Successful
404-Not Found Your Authentication-Id is wrong
409-Conflict User already exists
500-Internal Server Error Data access was unsuccessful
503-Service Unavailable Your service is disabled

نمونه‌ای از پاسخ موفق دریافت شده از این سرویس عبارت است از:

{
  "instanceId": "AUTHENTICATION-ID",
  "userId": "USER-ID",
  "username": "USERNAME",
  "firstName": "FIRSTNAME",
  "lastName": "LASTNAME",
  "email": "aaa@bbb.ccc",
  "phoneNumber": "12345678",
  "avatar": "mydomain.com/avatar.png",
  "guest": false,
  "active": false
}

می‌توانید برای هر کاربر اطلاعاتی اضافی از قبیل آدرس، سن و … را در هنگام ثبت‌نام ذخیره کنید. بدین منظور کافیست زوج «کلید-مقدار» اضافه‌ای که می‌خواهید، را در هنگام ثبت‌نام در بدنه‌ی درخواست قرار دهید؛ به صورت زیر:

curl -X POST ... \
    -d '{
        "firstName":"FIRSTNAME",
        "lastName":"LASTNAME",
        ...,                                        # Other necessary fields
        "address": "Tehran, First Alley!, No 7"     # additional field
    }' https://api.backtory.com/auth/users

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

ورود

با استفاده از این سرویس، کاربر می‌تواند با استفاده از اطلاعات ثبت نام خود (نام کاربری و کلمه عبور) وارد سیستم شود. با استفاده از این ورود، سطح دسترسی عادی خواهد بود و کاربران تنها به عملیات و اطلاعات خود (عملیات مربوط به سطح دسترسی عادی) دسترسی خواهند داشت. این سطح دسترسی معمولا نیاز کاربر را برآورده می‌کند و نیازی به دسترسی بالاتر نیست.

در زمان وارد شدن به سیستم، توکن دسترسی (access-token) به فرد وارد شده تعلق می‌یابد که به کمک آن می‌تواند دیگر عملیات مربوط به خود را انجام دهد. به عنوان مثال برای ارسال درخواست ثبت رویداد در سرویس مرکز بازی لازم است که توکن دسترسی در header درخواست قرار گیرد. با این کار سرویس مرکز بازی متوجه می‌شود که رویداد را برای کدام بازیکن باید ثبت کند. به طور کلی برای استفاده از بسیاری از سرویس‌های موجود، کاربر نیاز به استفاده از این توکن دارد. به همین دلیل در تعداد زیادی از درخواستها، این توکن به عنوان header گرفته می‌شود. لازم به ذکر است که هر توکن تا یک زمان خاص قابل استفاده است و پس از آن نیاز به ورود مجدد و گرفتن توکن دسترسی جدید می‌باشد. با توجه به این محدودیت و برای مقابله با آن (و در واقع عدم نیاز به وارد کردن مجدد اطلاعات)، در این واسط علاوه بر توکن دسترسی، توکن بازنشانی (refresh-token) نیز به کاربر تعلق می‌گیرد. بدین ترتیب کاربر می‌تواند با استفاده از این توکن، توکن دسترسی جدید را دریافت نماید و دیگر نیازی به وارد کردن دوباره اطلاعات نداشته باشد. توکن بازنشانی نیز زمان انقضا دارد، اما طبعا زمان منقضی شدن آن بیشتر از توکن دسترسی می‌باشد.

توجه: در header این درخواست نیاز به X-Backtory-Authentication-Id و X-Backtory-Authentication-Key وجود دارد که با مراجعه به پنل بکتوری، در قسمت کلیدها قابل مشاهده است.

curl -X POST \
    --header "X-Backtory-Authentication-Id: <ID>" \
    --header "X-Backtory-Authentication-Key: <CLIENT-KEY>" \
    -F "username=USERNAME" \
    -F "password=PASSWORD" \
    https://api.backtory.com/auth/login

انواع پاسخ‌هایی که از این سرویس ممکن است دریافت کنید به صورت جدول زیر است:

Tables Description
200-OK Successful
401-Unauthorized Username or password is incorrect
417-Expectation Failed Either Authentication Id or Authentication key is not correct.
500-Internal Server Error Data access was unsuccessful
503-Service Unavailable Your service is disabled

نمونه‌ای از پاسخ موفق دریافت شده از این سرویس عبارت است از:

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9….",
  "token_type": "bearer",
  "refresh_token": "eyJ1c2VyX2lkIjoiNTcyN…",
  "expires_in": 7199,
  "scope": "client",
  "jti": "485b5da3-e3ec-4139-915b-a2b760cf3153"
}

استفاده از access_token در سرویس‌های دیگر

پس از طی مراحل قبل شما یک access_token دارید که در مثال بالا به مدت حدود دو ساعت (۷۱۹۹ ثانیه) معتبر است. در این مدت هر درخواستی به هر سرویس دیگری دارید، باید این access_token را به همراه درخواست ارسال کنید. نحوه ارسال آن نیز بسیار ساده است. کافیست در درخواست خود یک header به نام Authorization قرار دهید و مقدار آن را به صورت زیر تنظیم کنید: (به کاراکتر فاصله بین token_type و access_token دقت کنید.)

Authorization: {token_type} {access_token}

مثال:

Authorization: bearer eyJhbGciOiJSUzI1NiJ9…

گرفتن توکن دسترسی جدید (get-new-access-token)

زمان منقضی شدن توکن دسترسی (و تبعا نیاز به ورود جدید و گرفتن توکن جدید) محدود است. برای گرفتن توکن دسترسی جدید می‌توانید با استفاده از این سرویس و توکن بازنشانی (refresh-token) گرفته شده در هنگام ورود، توکن دسترسی جدید را بدون نیاز به وارد کردن اطلاعات مجدد توسط کاربر، به وی تعلق دهید. همانطور که گفته شد، زمان منقضی شدن توکن بازنشانی بیشتر از توکن دسترسی است و بنابراین می‌توان از آن برای دریافت توکن دسترسی جدید استفاده نمود.

توجه: در header این درخواست نیاز به X-Backtory-Authentication-Id و X-Backtory-Authentication-Key وجود دارد که با مراجعه به پنل بکتوری، در قسمت کلیدها قابل مشاهده است. همچنین refresh-token درون درخواست، همان refresh-tokenای است که کاربر در هنگام ورود (login) گرفته است.

curl -X POST \
    --header "X-Backtory-Authentication-Id: <ID>" \
    --header "X-Backtory-Authentication-Key: <CLIENT-KEY>" \
    --header "X-Backtory-Authentication-Refresh: 1" \
    --header "Content-Type: multipart/form-data" \
    -F "refresh_token=<REFRESH-TOKEN>" \
    https://api.backtory.com/auth/login

انواع پاسخ‌هایی که از این سرویس ممکن است دریافت کنید به صورت جدول زیر است:

Tables Description
200-OK Successful
401-Unauthorized Refresh token is incorrect
417-Expectation Failed Either Authentication Id or Authentication key is not correct.
500-Internal Server Error Data access was unsuccessful
503-Service Unavailable Your service is disabled

نمونه‌ای از پاسخ موفق دریافت شده از این سرویس عبارت است از:

{
  "access_token": "eyJhbGciOi…",
  "token_type": "bearer",
  "refresh_token": "eyJhbGciOiJSU…",
  "expires_in": 7199,
  "scope": "client",
  "jti": "bece49d9-ab82-494a-ab06-f0ee0afd5c23"
}

ورود مدیر (login-master)

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

توجه: در header این درخواست نیاز به X-Backtory-Authentication-Id و X-Backtory-Authentication-Key وجود دارد که با مراجعه به پنل بکتوری، در قسمت کلیدها قابل مشاهده می‌باشد.

curl -X POST \
    --header "X-Backtory-Authentication-Id: <ID>" \
    --header "X-Backtory-Authentication-Key: <MASTER-KEY>" \
    https://api.backtory.com/auth/login

انواع پاسخ‌هایی که از این سرویس ممکن است دریافت کنید به صورت جدول زیر است:

Tables Description
200-OK Successful
417-Expectation Failed Either Authentication Id or Authentication key is not correct.
500-Internal Server Error Data access was unsuccessful
503-Service Unavailable Your service is disabled

نمونه‌ای از پاسخ دریافت شده از این سرویس عبارت است از:

{
  "access_token": "eyJhbGciOiJSUzI1Ni….",
  "token_type": "bearer",
  "expires_in": 7199,
  "scope": "master",
  "jti": "243848f1-8a56-4b79-9556-7926e0c5b988"
}

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

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

در header این درخواست نیاز به X-Backtory-Authentication-Id وجود دارد که با مراجعه به پنل بکتوری، در قسمت کلیدها قابل مشاهده است.

curl -X PUT \
    --header "X-Backtory-Authentication-Id: <ID>" \
    --header "Authorization: Bearer <USER-ACCESS-TOKEN>" \
    --header "Content-Type: application/json" \
    -d '{
        "username": "NEW-USERNAME",
        "firstName": "NEW-FIRSTNAME",
        "lastName": "NEW-LASTNAME"
    }' https://api.backtory.com/auth/users/me

انواع پاسخ‌هایی که از این سرویس ممکن است دریافت کنید به صورت جدول زیر است:

Tables Description
200-OK Successful
400-Bad Request Invalid email address. Or firstname, lastname, or username length is more than 40 characters.
401-Unauthorized Incorrect access token
404-Not Found Your Authentication-Id is wrong
500-Internal Server Error Data access was unsuccessful
503-Service Unavailable Your service is disabled

نمونه‌ای از پاسخ دریافت شده از این سرویس عبارت است از:

{
  "instanceId": "AUTHENTICATION-ID",
  "userId": "USER-ID",
  "username": "NEW-USERNAME",
  "firstName": "NEW-FIRSTNAME",
  "lastName": "NEW-LASTNAME",
  "email": "aaa@bbb.ccc",
  "phoneNumber": "12345678",
  "guest": false,
  "active": true
}

منقضی کردن توکن بازنشانی (logout)

به وسیله این سرویس، می‌توانید توکن‌های بازنشانی (refresh-token) را منقضی کنید. همانطور که گفته شد با توجه به مدت انقضای طولانی این نوع توکن‌ها، امکان گرفتن توکن دسترسی جدید (بدون نیاز به وارد کردن مجدد اطلاعات توسط کاربر)، با استفاده از این توکن‌ها وجود دارد. اما پس از منقضی کردن آن (logout) کاربر نمی‌تواند توکن دسترسی جدید را با استفاده از توکن بازنشانی منقضی شده درخواست نماید.

curl -X DELETE \
    --header "X-Backtory-Authentication-Id: <ID>" \
    --header "X-Backtory-Authentication-Key: <CLIENT-KEY>" \
    'https://api.backtory.com/auth/logout?refresh-token=REFRESH-TOKEN'

گام بعدی