تایید هویت و ورود مخصوص اپ‌های کانکت
سلام و درود بر دوستداران علم و ادب
امروز قصد داریم نحوه ورود به اهراز هویت در اپ های کانکت را با هم مرور کنیم. دلیل اینکه به اپ های کانکت اشاره می شه اینه که با اپ دیسکاوری قاطی نشه. چون نحوه ورود و اهراز هویت برای اپ دیسکاوری متفاوت تر از اپ های کانکت که مختص هر برگزار کننده ساخته می شه خواهد بود.
برای ورود به اپ تصمیم بر این شد که کاربر موبایل خود را وارد کرد، تایید کند، سپس وارد اپ شود.
در نتیجه برای اهراز هویت نیاز به کد تاییده هست که به موبایل کاربر ارسال می‌شود.
سپس با استفاده از کد دریافتی توسط کاربر، درخواست دیگری برای گرفتن توکن خواهیم داشت.
درخواست و دریافت کد تاییدیه
برای دریافت کد تاییدیه نیازه هست شماره موبایل کاربر به ریسورس ای ارسال شود تا اینکه کدی دارای اعتبار ۲ دقیقه ای ساخته و برای کاربر ارسال گردد.
برای درخواست کد تاییدیه به این شکل عمل می کنیم:
POST https://connect.evand.com/api/mobile/verification-codes
{
"mobile": "09XXXXXXXXX"
}
در صورت معتبر بودن شماره موبایل، کد تاییدیه ای برای کاربر ارسال خواهد شد که در مراحل بعدی برای ایجاد توکن جهت دسترسی به ریسورس هایی، استفاده می شه.
برای تایید صحبت موبایل از این پترن استفاده می شه که در صورت نیاز می تونید استفاده کنید:
Regular expression: /^(\+98|0098|0)?(9[0-9]{9})$/
در این مرحله، بررسی نمی شه که موبایل ارسال شده، در سیستم دارای اکانتی می باشد و برای سیستم شناخته شده است یا نه. احتمال اینکه این رویه بعد ها تغییر کند تا سیستم الکی درگیر شماره های ناشناخته نشده وجود دارد که در آن صورت ممکن هست خطا های متنوع ای هم از سیستم بروز کند.
مورد بعدی اینکه ممکنه بعد ها نیاز باشه، هر شماره موبایل، در X دقیقه، به تعداد n تا بتونه درخواست کد تاییدیه بگیره و در صورت رسیدن به این محدودیت خطای متفاوتی هم کاربر می تونه دریافت کنه مبنی بر اینکه ساعاتی یا دقایقی دیگر سعی کنه.
البته این دو مورد در موردشون هنوز بحث نشده و اینکه اجرا بشه یا نه مشخص نیست.
اهراز هویت و دریافت توکن
بعد از درخواست و دریافت کد تاییدیه برای شماره موبایل مورد نظر، نوبت درخواست Access Token به همراه Refresh Token می رسه.
ریسورس ای برای دریافت توکن های مربوط هست که نیازه اطلاعات مربوط به کلایت، به همراه شماره موبایل و کد تاییدیه موبایل ارسال شود.
برای ارسال درخواست به این صورت عمل می کنیم:
مقدار فیلد grant_type در صورتی که بخواهیم کاربر را با موبایل اهراز هویت کنیم، نیازه مقدارش user_mobile باشه.
دو فیلد client_id و client_secret مقدارشان برای هر اپ کانکت جداگانه در سیستم تعریف و در اختیار توسعه دهنده قرار می گیره که ثابت هست و برای اینه که بفهمیم از چه اپی درخواست می فرسته و بعد از اینکه توکن برای کاربر تهیه شد هم بشه درخواست هاشو ردیابی کرد که از چه اپی (کلاینت ای) درخواست می فرسته. اینطوریمی شه برخی ریسورس ها رو که نسبت به کلاینت (اپ‌های کانکت) خروجی شون می تونه فرق کنه رو هندل کنیم. مثلا هر اپ کانکت به یه رویدادی متثل هست که می تونیم ریسورس رویداد مورد نظر رو در اختیار کاربر قرار بدیم که طبیعتا نسبت به هر اپ کانکت متفاوت خواهد بود.
برای فیلد mobile باید شماره موبایل ای که در مرحله قبل برای گرفتن کد تاییدیه براش درخواست فرستاده بودید رو تعیین کنید، و برای mobile_verification_code هم کد تاییدیه ای که به شماره موبایل مربوطه ارسال شده بود را.
در صورت موفقیت آمیز بودن عملیان، خروجی مانند این دریافت خواهید کرد:
فیلد token_type نوع توکن رو تعیین می کنه. مثلا اینجا Bearer هست و برای ریسورس هایی که نیاز به احراز هویت هست، نیازه در هدر Authorization مقدار "Bearer ACCESS_TOKEN" را بفرستید.
فیلد expires_in مدت زمانی هست که توکن اعتبار داره و بعد از آن توکن اعتبارش را از دست می ده.
زمان توکن بر حسب ثانیه است و زمان فعلی که برای توکن ها در نظر گرفته می شه یک روزه هستش.
فیلد access_token هم توکن مون هست که همانطوری که توضیح داده شد نیازه از هدر Authorization ارسال بشه که مقدارش هم به این شکل خواهد بود: "Bearer ACCESS_TOKEN"
فیلد refresh_token برای این هست که بعد از منقضی شدن توکن، با استفاده از refresh token ، درخواستی برای گرفتن توکن جدید ارسال بشه. البته این عمل توسط کلاینت (اپ و برنامه نویس) انجام می شه تا کاربر نیازی نباشه دوباره مراحل احراز هویت رو بگذرونه.
البته توجه کنید که refresh_token همیشگی نیست و زمان منقضی داره که زمان پیش فرضش یک ماه هست و بعد از ۱ ماه اگر از اعتبار بیفته و access_token هم از اعتبار بیفته، نیاز خواهد بود تا کاربر دوباره لاگین کنه.
نکته ای که در مورد refresh token وجود داره اینه که وقتی با استفاده ازش درخواست توکن جدید می دید، علاوه بر access_token جدید، یه refresh_token جدید هم ساخته می شه که می تونید با قبلیه جایگزین کنید که زمان ۱ ماه مربوط به refresh_token اینطوری آپدیت می شه و نیاز نمی شه دوباره کاربر رو از مراحل احراز هویت بگذرونین.
البته هر دو refresh_token و access_token جدید درخواستی متفاوت از قبلی خواهند بود.
نحوه استفاده از Refresh Token در مطلب جداگانه ای بهش اشاره شده که می تونید ازش استفاده کنید.
خطاهای برگشتی
در صورتی که اقدام به دریافت توکن نمایید، ممکن است با دیوار بتنی مواجه شوید و عملیات با موفقیت انجام نپذیرد. در این صورت به ناچار مجبور به انجام اقداماتی نسب به شدت شرایط موجود خواهیم بود که نوع خطا های برگشتی این امکان رو به ما می دن که بتونیم تصمیم درستی در زمان و مکان درست بگیریم.
-خطا که وقتی grant_type رو اشتباه وارد می کنید: (Status Code: 400)
- هنگام نامعتبر بودن client_id و client_secret هست: (Status Code: 422)
- خطا در صورت نامعتبر بودن شماره موبایل (ساختار شماره موبایل):
- خطای ناصحیح بودن کد تاییدیه نسبت به شماره موبایل وارده:
- خطا در صورتی که شماره موبایل وارده، به هیچ اکانتی در سیستم تعلق نداره و یه کاربر جهت کنجکاوری شماره ای رو وارد کرده. البته برای این منظور شاید بعد ها نیاز باشه بزاریم کاربره بره تو ولی با دسترسی محدودتر. حتی می شه اشتراکی هم از این افراد گرفته بشه برای مشاهده برخی بخش‌ها ولی با این عنوان که شرکت کننده رویداد نیست و صرفا اشتراک داره:
ریسورس ای برای دریافت توکن های مربوط هست که نیازه اطلاعات مربوط به کلایت، به همراه شماره موبایل و کد تاییدیه موبایل ارسال شود.
برای ارسال درخواست به این صورت عمل می کنیم:
POST https://connect.evand.com/api/oauth2/token
{
"grant_type": "user_mobile",
"client_id": "client_test",
"client_secret": "test",
"mobile": "+989147834280",
"mobile_verification_code": 33096
}
مقدار فیلد grant_type در صورتی که بخواهیم کاربر را با موبایل اهراز هویت کنیم، نیازه مقدارش user_mobile باشه.
{
"grant_type": "user_mobile",
"client_id": "client_test",
"client_secret": "test",
"mobile": "+989147834280",
"mobile_verification_code": 33096
}
دو فیلد client_id و client_secret مقدارشان برای هر اپ کانکت جداگانه در سیستم تعریف و در اختیار توسعه دهنده قرار می گیره که ثابت هست و برای اینه که بفهمیم از چه اپی درخواست می فرسته و بعد از اینکه توکن برای کاربر تهیه شد هم بشه درخواست هاشو ردیابی کرد که از چه اپی (کلاینت ای) درخواست می فرسته. اینطوریمی شه برخی ریسورس ها رو که نسبت به کلاینت (اپ‌های کانکت) خروجی شون می تونه فرق کنه رو هندل کنیم. مثلا هر اپ کانکت به یه رویدادی متثل هست که می تونیم ریسورس رویداد مورد نظر رو در اختیار کاربر قرار بدیم که طبیعتا نسبت به هر اپ کانکت متفاوت خواهد بود.
{
"grant_type": "user_mobile",
"client_id": "client_test",
"client_secret": "test",
"mobile": "+989147834280",
"mobile_verification_code": 33096
}
برای فیلد mobile باید شماره موبایل ای که در مرحله قبل برای گرفتن کد تاییدیه براش درخواست فرستاده بودید رو تعیین کنید، و برای mobile_verification_code هم کد تاییدیه ای که به شماره موبایل مربوطه ارسال شده بود را.
در صورت موفقیت آمیز بودن عملیان، خروجی مانند این دریافت خواهید کرد:
{
"token_type": "Bearer",
"expires_in": 86400,
"access_token": "eyJ0e…….",
"refresh_token": "def502002…...."
}
فیلد token_type نوع توکن رو تعیین می کنه. مثلا اینجا Bearer هست و برای ریسورس هایی که نیاز به احراز هویت هست، نیازه در هدر Authorization مقدار "Bearer ACCESS_TOKEN" را بفرستید.
فیلد expires_in مدت زمانی هست که توکن اعتبار داره و بعد از آن توکن اعتبارش را از دست می ده.
زمان توکن بر حسب ثانیه است و زمان فعلی که برای توکن ها در نظر گرفته می شه یک روزه هستش.
فیلد access_token هم توکن مون هست که همانطوری که توضیح داده شد نیازه از هدر Authorization ارسال بشه که مقدارش هم به این شکل خواهد بود: "Bearer ACCESS_TOKEN"
فیلد refresh_token برای این هست که بعد از منقضی شدن توکن، با استفاده از refresh token ، درخواستی برای گرفتن توکن جدید ارسال بشه. البته این عمل توسط کلاینت (اپ و برنامه نویس) انجام می شه تا کاربر نیازی نباشه دوباره مراحل احراز هویت رو بگذرونه.
البته توجه کنید که refresh_token همیشگی نیست و زمان منقضی داره که زمان پیش فرضش یک ماه هست و بعد از ۱ ماه اگر از اعتبار بیفته و access_token هم از اعتبار بیفته، نیاز خواهد بود تا کاربر دوباره لاگین کنه.
نکته ای که در مورد refresh token وجود داره اینه که وقتی با استفاده ازش درخواست توکن جدید می دید، علاوه بر access_token جدید، یه refresh_token جدید هم ساخته می شه که می تونید با قبلیه جایگزین کنید که زمان ۱ ماه مربوط به refresh_token اینطوری آپدیت می شه و نیاز نمی شه دوباره کاربر رو از مراحل احراز هویت بگذرونین.
البته هر دو refresh_token و access_token جدید درخواستی متفاوت از قبلی خواهند بود.
نحوه استفاده از Refresh Token در مطلب جداگانه ای بهش اشاره شده که می تونید ازش استفاده کنید.
خطاهای برگشتی
در صورتی که اقدام به دریافت توکن نمایید، ممکن است با دیوار بتنی مواجه شوید و عملیات با موفقیت انجام نپذیرد. در این صورت به ناچار مجبور به انجام اقداماتی نسب به شدت شرایط موجود خواهیم بود که نوع خطا های برگشتی این امکان رو به ما می دن که بتونیم تصمیم درستی در زمان و مکان درست بگیریم.
-خطا که وقتی grant_type رو اشتباه وارد می کنید: (Status Code: 400)
{
"error": "unsupported_grant_type",
"message": "The authorization grant type is not supported by the authorization server.",
"hint": "Check that all required parameters have been provided"
}
- هنگام نامعتبر بودن client_id و client_secret هست: (Status Code: 422)
{
"title": "authentication_error",
"type": "invalid_client",
"status": 422,
"detail": "Client authentication failed"
}
"title": "authentication_error",
"type": "invalid_client",
"status": 422,
"detail": "Client authentication failed"
}
- خطا در صورت نامعتبر بودن شماره موبایل (ساختار شماره موبایل):
{
"errors": {
"mobile": {
"invalid": "invalid mobile phone number"
}
},
"title": "validation_error",
"type": "validation_error",
"status": 422,
"detail": "hello"
}
- خطای ناصحیح بودن کد تاییدیه نسبت به شماره موبایل وارده:
{
"errors": {
"mobile": {
"mobile_ownership_failed": "mobile and it's verification code (mobile_verification_code) does not match up or is expired!"
}
},
"title": "validation_error",
"type": "validation_error",
"status": 422,
"detail": "hello"
}
"errors": {
"mobile": {
"mobile_ownership_failed": "mobile and it's verification code (mobile_verification_code) does not match up or is expired!"
}
},
"title": "validation_error",
"type": "validation_error",
"status": 422,
"detail": "hello"
}
- خطا در صورتی که شماره موبایل وارده، به هیچ اکانتی در سیستم تعلق نداره و یه کاربر جهت کنجکاوری شماره ای رو وارد کرده. البته برای این منظور شاید بعد ها نیاز باشه بزاریم کاربره بره تو ولی با دسترسی محدودتر. حتی می شه اشتراکی هم از این افراد گرفته بشه برای مشاهده برخی بخش‌ها ولی با این عنوان که شرکت کننده رویداد نیست و صرفا اشتراک داره:
{
"errors": {
"mobile": {
"associated_user_not_found": "Could not find any user associated with the given mobile phone number!"
}
},
"title": "validation_error",
"type": "validation_error",
"status": 422,
"detail": "hello"
}
نظرات