ورود یکپارچه (SSO)
خدمتدهنده
بازارچه پادیوم
مقدمه
با استفاده از SSO سرزمین هوشمند پاد، میلیونها کاربر «پادی» میتوانند بدون نیاز به ثبت نام، تنها با چند کلیک به کسبوکار شما وارد شوند.
سامانه ورود یکپارچه (SSO)
این بستر که جز اصلی و مرکزی از پلتفرم پـــاد می باشد به عنوان هسته احراز هویت مرکزی مورد استفاده قرار می گیرد.
اکثر سرویس هایی که در پاد و پادیوم استفاده می شوند باید دارای توکن معتبر از این سرور و سرویس های آن باشند.
همچنین کسب و کارها جهت تعریف کاربران جدید، دریافت و به روزرسانی پروفایل کاربران خود می توانند از این سرویس ها استفاده نمایند و نیازی به نگهداری اطلاعات کاربران در سیستم خود ندارند.
این سامانه بر اساس استاندارد OAuth2.0 پیاده سازی شده است بنابراین جهت استفاده از سرویس های پلتفرم بایستی بر اساس این استاندارد جهت ورود کاربران و دریافت توکن استفاده نمایند.
روش کلی به این صورت است که برای ورود کاربر، وی را به صفحه ورود سرور SSO راهنمایی میکنیم
و پس از ورود کاربر، توکن مربوط به کاربر به آدرس تعریف شده توسط کسب و کار ارسال می گردد.
پس از دریافت توکن، میتوان از آن برای صدازدن سایر سرویس های پلتفرم استفاده نمود و یا اطلاعات پروفایل کاربر را دریافت و ویرایش نمود.
آدرسها
در این مستندات، آدرس سرور SSO به صورت [sso-address] نوشته شده است که لازم است با مقدار زیر جایگزین شود:
در این مستندات آدرس سرور پلتفرم به صورت [platform-address] نوشته شده است که لازم است هنگام تست با آدرس سندباکس جایگزین گردد.
https://api.pod.ir/srv/sc/nzh/doServiceCall
https://sandbox.pod.ir/srv/sc/nzh/doServiceCall
ورود
برای ورود کاربران از طریقSSO پاد از آدرس زیر استفاده کنید. مقدار client_id خود را در آن قرار دهید و آدرسی که می خواهید پاسخ درخواست را در آن دریافت کنید را به عنوان پارامتر redirect_uri ارسال نمایید. مقادیرclient_id و redirect_uri باید منطبق بر کلید اتصال تعریف شده توسط شما باشند.
https://accounts.pod.ir/oauth2/authorize/
?client_id=[CLIENT_ID]
&response_type=[code] or [token]
&redirect_uri=[REDIRECT_URI]
&scope=profile
دقت کنید که اگر به اسکوپ های درخواستی شما به هر دلیل اجازه دسترسی وجود نداشته باشد Code خالی برگردانده می شود.
در صورت ورود موفق کاربر، پاسخ این درخواست در آدرس بازگشت به شکل زیر است:
[redirect_uri]?code=[authorization_code]
* با استفاده از code دریافتی ، میتوانید در سرویسی که در ادامه توضیح داده خواهد شد ، اقدام به دریافت اکسس توکن ، نمایید .
* مقدار کد یک رشته ی 32 کارکتری ، ترکیبی از حروف انگلیسی و اعداد است .
* این کد در مدت کوتاهی منقضی می شود. بنابرین بلافاصله باید نسبت به دریافتaccess_token و refresh_token اقدام شود.
نکته : اگر در کلید اتصال ، گزینه توکن یک مرحله ای فعال باشد ، میتوانید response_type=token قرار دهید ، که در این صورت بعد از ورود کاربر اطلاعات بازگشتی حاوی ، اکسس توکن و سایر موارد خواهد بود . که این خروجی به صورت زیر خواهد بود .
فهرست کامل پارامترهای این درخواست به شرح زیر است:
client_id | شناسه مشتری (اجباری) | دریافت این مقدار از پنل کسب و کار |
response_type | نوع اطلاعات درخواستی | برای احراز هویت در اپلیکیشن های وب، از “code” استفاده نمایید و برای اپلیکیشن های موبایل از “token” ) که امکان ورود یک مرحله ای با فعال کردن این گزینه در کلید اتصال ایجاد شده فراهم خواهد شد .) یا “id_token” استفاده نمایید. |
redirect_uri | آدرس بازگشت | آدرس بازگشت ثبت شده برای وبسایت، متناظر با کلید اتصال ایجاد شده و client_id استفاده شده. |
prompt | عملیات مورد نیاز | می تواند شامل یکی ازمقادیر login ،signup , otp_loginیا null باشد و اگر این پارامتر ارسال نشود، روند عادی login طی میشود =[login / qr_login / otp_login / card_login] - مقدار این پارامتر را میتوانید برابر با otp_login قرار داده تا فرآیند لاگین کاربر توسط پیامک انجام بشود. درصورتارسالمقدار null برای این پارامتر، لاگین در sso پاد برای کاربر انجام می شود. با ارسال مقدار signup برای این پارامتر، فرم ثبت نام به کاربر نشان داده خواهد شد.
|
state | مقدار دلخواه که برنامه می خواهد در آدرس بازگشت، داشته باشد. | در این پارامتر هر مقداری کهنیازداریدمیتوانیدبهصورتهششده و غیر هش شده ارسالنماییدوبعدازلاگینهمانمقداربهکسبوکاربرگرداندهمیشودبرایمثالمیتواندراینپارامترمتوجهشدکاربر کجای سیستم قرار بوده برود ودسترسینداشته، استفادهمیکنیم |
scope | شامل درخواست برنامه برای دسترسی به اطلاعات کاربر است. | می تواند شامل یک یا چند مورد از موارد زیر باشد: profile ، email ، address ، activity ، legal، phone , wallet , wallet_settlement , wallet_withdraw, wallet_balance, wallet_bill , storage مقدار پیش فرض profile:read میباشد و در صورت موافقت کاربر، توکنی که برای این scope صادر میشود فقط برای همان عملیات می تواند استفاده شود. Scope های بالا تنها اجازه خواندن اطلاعات کاربران را به شما می دهد. در صورت نیاز برای ویرایش اطلاعات کاربر :write را به انتهای اسکوپ اضافه نمایید. مثال: email:write * توجــــه : تخصیص اسکوپ های بیشتریا دسترسی اسکوپ ها به Write الزاما توسط تیم فنی پاد انجام خواهد شد و اسکوپ ها باید توسط کسب و کار در سامانه فمس یا از طریق نامه نگاری با تیمPOD - Core - Security درخواست داده شود. * برای مشاهده ی اسکوپهای متناظر با client_id باید به پنل کسب وکار ، در بخش ورود یکپارچه گزینه لیست کلیدها و در جزئیات مربوط به آن کلید اتصال مراجعه کنید. * پنل کسب وکار – ورودیکپارچه – لیست کلیدها – جزئیات کلید |
code_challenge | این پارامتر و پارامتر بعدی برای برنامه های بدون سرور استفاده می شوند. | چنانچه اپلیکیشنی دارید و میخواهید از ان برای لاگین کاربران بدون سرور استفاده نمایید از این روش استفاده کنید |
code_challenge_method | متد رمز نگاری کد | چنانچه اپلیکیشنی دارید و میخواهید از ان برای لاگین کاربران بدون سرور استفاده نمایید از این روش استفاده کنید |
social | جهت لاگین در پاد از طریق پلتفرم های دیگر که با sso پاد در ارتباط می باشد و نام این پلتفرم قابل مذاکره و توافق می باشد . | به عنوان مثال میتواند شامل یکی از مقادیر bpi و dotin و .... باشد. اگر مقدار این پارامتر برابر با bpi قرار بگیرد امکان لاگین کاربر توسط اینترنت بانک پاسارگاد از طریق فشار دادن icon بانک پاسارگاد فراهممیشودبهشرطیکهکاربردربانکپاسارگادحسابداشتهواطلاعات مربوط به اینترنت بانک خود را در اختیار داشته باشد. به عنوان مثال : social=bpi social=dotin *مقدار dotin در حال حاضر غیر فعال است.
|
continue | نشان دهنده ی آدرس صفحه بعدی به کاربر | این پارامتر در صفحات تنظیمرمزعبوروتغییررمزعبورجهتنمایشآدرسصفحهیبعدیبهکاربرارسالمیگردد. |
callbackurl | نشان دهنده آدرس جهت دریافت پاسخ درخواست ارسالی | این پارامتر در صفحات ورود با رمز عبور، تنظیم رمز عبور و تغییر رمز عبور جهت نمایش آدرس دریافت پاسخ درخواست مورد نظر ارسال می گردد. |
ورود با OTP با سرور
جهت ایجاد امکان ورود با رمز یکبار مصرف (OTP) برای کاربران، در حالتی که کسب و کار دارای سرور امن و قابلیت ایجاد ارتباط با SSO پاد از طریق سرور خود باشد، این روش پیشنهاد می گردد.
لازم است از طریق سرور، به ازای هر شماره موبایلیا دستگاهی که می خواهد لاگین شود،
اطلاعات دستگاه را با متد handshake به SSO معرفی نمایید و keyId دریافت کنید.
* قبل از فراخوانی سرویس هندشیکنیاز دارید که یک جفت کلیدعمومی خصوصی با الگوریتم RSA و سایز کلید 2048 ایجاد کرده باشید.
که میتوانید در حین ساخت کلید اتصال ، یک جفت کلید عمومی خصوی ایجاد کنید و کلید خصوصی را نزد خود و کلید عمومی را در کلید اتصال ثبت نمایید (مراجعه شود به بخش ساخت کلید اتصال ) ،
و یا از ابزار زیر استفاده کنید و کلید عمومی/ خصوصی خود را ایجاد کنید و سپس کلید عمومی را از طریق پنل و در کلید اتصال موردنظر ثبت کنید .
* توجه داشته باشید ، که میتوانید از ابزار دلخواه خود جهت تولید کلید عمومی / خصوصی استفاده نمایید .
برای دریافت کلید عمومی و خصوصی مراحل زیر را انجام دهید :
ابتدا وارد لینکhttps://accounts.pod.ir/secTools.html شوید.
بدون وارد کردن مقداری دکمه یGenerate:RSA-2048را بزنید.
3. پس از فشار دادن دکمه ی فوق کلید عمومی و خصوصی نمایش داده می شود.
نکتـــــه مهم : قبل از فراخوانی سرویس هندشیک، کلید عمومی دریافتی از قسمت فوق را در پنل کسب و کاری خودتان بارگذاری نمایید در غیر این صورت خطای مناسب را دریافت خواهید کرد.
پس از دریافت کلید عمومی و خصوصی و ثبت کلید عمومی در کلید اتصال مربوطه ،
سرویسhandshake را به منظور معرفی دستگاه و همچنین تفاهم بر روی پارامترهای امضای دیجیتال (شامل algorithm،keyId) فراخوانی کنید.
برای فراخوانی این سرویس نیاز به api_token و client_id میباشد که از پنل مدیریت کسب و کار قابل دریافت است.
پارامتر device_uid توسط سرور کسب و کار تولید میشود و بایدیک شناسه ی منحصر به فرد و دلخواه باشد.
همچنین دقت نمایید این مقدار باید به ازای هر دستگاه نگهداری شود ، تا نیاز نباشد که هربار برای ورود این سرویس را فراخوانی کنید
زیراKeyid تولید شده توسط این سرویسیکسال اعتبار دارد و برای سرویس های بعدی نیز می توانید برای همان دستگاه این مقدار را نگهداری کنید و استفاده نمایید و هربار handshake انجام ندهید.
پارامترdevice_name جهت فهم کاربر از وسیله ای که در آن وارد شده است مفید خواهد بود. بنابرین توصیه می شود مشخصاتی از برنامه و ابزاری که کاربر وارد آن شده است ارسال گردد.
خروجی فراخوانی سرویس بالا به شکل زیر میباشد.
keyId پارامتر خروجی در سرویس هندشیک فوق می باشد این کلیدیک سال زمان اعتبار دارد به همین خاطر نیاز به فراخوانی چندین بار سرویس هندشیک نیست. در صورت تمایل مقدار keyId نمایش داده شده را نگهداری فرمایید.
خطاهای رایجی که در فراخوانی سرویس فوق، ممکن است با آن روبرو شوید در جدول زیر آورده شده است:
errorCode | دلیل خطا | شرح خطا |
400 | Invalid_device | ارسال بدون مقدار پارامتر device_uid یا عدمارسالپارامتر device_uid |
401 | Invalid token | در صورتی که مقدار توکن اشتباه باشد و یا این مقدار ارسال نگردد، این پیغام را دریافت خواهید کرد. |
403 | Invalid grant | عدم ارسال مقدار client_id درURL |
404 | Not Found | کلید عمومی پیدا نشده است.(عدم بارگذاری کلید عمومی در پنل کسب و کار) |
500 | Internal Server Error | عدم ارسال پارامتر Content-Type |
در مرحله بعد لازم است با keyId دریافتی در سرویس هندشیک فوق و کلید خصوصی کسب و کار
یک امضای دیجیتال تولید شود و همراه شماره موبایلیا ایمیل کاربر به SSO ارسال گردد.
تصویر زیر فرایند کلی را نمایش می دهد.
payLoad=host: accounts.pod.ir;
sign=makeSignBase64(privateKey,payLoad,RSA-Sha256 );
پس از فراخوانی سرویسhandshake، برای ساخت و بدست آوردن signature میتوانید از ابزار زیر استفاده کنید و مراحل زیر را انجام دهید:
وارد لینکhttps://accounts.pod.ir/secTools.html شوید.
در قسمت payload مقدار host: accounts.pod.ir و در قسمت Private Key کلید خصوصی بدست آمده در مراحل ابتدایی را وارد کنید.
در این مرحله دکمه یsign:RSA-256 رابزنید.
* درمتن payload (host: accounts.pod.ir) بعد از کاراکتر : و حرف a حتما بایدیک فاصله وجود داشته باشد.
4. پس از فشار بر روی دکمه ی مذکور در قسمت Signature(base64)، امضای دیجیتال خود را دریافت می کنید.
حال با مقدار پارامترهای دریافتیkeyId،Signature و با host مورد نظر پارامتر Authorization مورد نیاز برای سرویسotp را بدست آورید.
مراحل بدست آوردن Authorization به شرح زیر می باشد:
مقدار پارامتر keyId بدست آمده از سرویس هندشیک و مقدار Signature بدست آمده از جدول sectools را به همراه Host مورد نظر در فرمت زیر جایگذاری نمایید.
Authorization: Signature keyId="",signature="",headers="host"
فرمت بدست آمده را در قسمت هدر در فیلد Authorization سرویسotp در هنگام فراخوانی قرار دهید.
درخواست دریافت کد OTP
نکتــه: چنانچه اطلاعات کاربری که توسط این سرویس در پاد ارسال میشود قبلا تاییده شده باشد یا به عبارتی در پاد وجود داشته باشد با همان تلفن و یا ایمیل تاییده شده قبلی به پاد لاگین می شود و چنانچه شماره تماس یا ایمیل ارسالی در این سرویس در پاد تایید نشده باشد و اطلاعت ارسالی و کاربرجدید باشد برای او پس از پاسخ به سرویس و ارسال کد یکبار مصرف یککاربر جدید ساخته خواهد شد.
همچنین امکان ثبت چند شماره موبایل مختلف با یک کد ملی نیز در این سرویس وجود دارد.
* پس از صدا زدن این سرویس، کد (رمز یکبار مصرف) به تلفن و یا ایمیل داده شده ارسال می گردد.
* توجه داشته باشید کد ارسال شده پس از 120 ثانیه منقضی می گردد.
* در پاسخ این سرویس شماره تلفن و یا ایمیل را در فیلدidentity و شناسه کاربر (SSO_ID) را در فیلدuser_id دریافت خواهید کرد. ( دقت شود که SSO_ID با شناسه کاربری در پلتفرم پاد متفاوت است ) و فیلد user_id ، شناسه کاربر در SSO رو دارا می باشد.
برای بدست آوردن UserId پادی و پادیومی از طریق userId در SSOو خروجی بالا . باید از سرویس زیر استفاده کنید.
میتوانید از طریق شماره موبایل یا کد ملی کاربر نیزUserId پادی و پادیومی وی را بدست آورید .
خروجی سرویس بالا به صورت زیر است:
* در صورتی که کاربر جدید باشد user_id مقدار نخواهد داشت و پس از صدا زدن سرویسverify کاربر ثبت نام خواهد شد.
توجه نمایید که عملیات مراحل otp توسط تلفن کاربر و یا کد ملی کاربر امکان پذیر می شود.
* پارامترidentity می تواند حاوی شماره تلفن و یا ایمیل کاربر باشد.
* پارامترnationalcode: با ارسال این پارامتر ورود بر اساس کاربری که با این کد ملی ثبت شده است انجام می شود و شماره تلفنی که وارد می شود باید متعلق به این کد ملی باشد.
پارامترnationalcodeSerial: شماره سریال کارت ملی کاربر می باشد که می توان در این سرویس دریافت کرد و فیلد اختیاری می باشد.
پارامترbirthdate: بعد از تایید شماره تلفن کاربر، تاریخ تولد در پروفایل کاربر آپدیت می شود و بعد از آن برای تایید ثبت احوال ارسال می شود. اگر خطایی در آپدیت تاریخ تولد رخ دهد خطا نادیده گرفته می شود.
پارامترloginAsUserId : اجازه لاگین در پاد به کاربر دیگر به جای خود
پارامترloginAsRelativeNationalcode : کد ملی ثبت شده فرزند در بانک می تواند در این فیلد ارسال شود و والدین می توانند فرزند خود را با این روش در پلتفرم ثبت نمایند.
پارامترloginAsUsernameChild : این پارامتر یک مقدار به عنوان نام کاربری برای فرزند است که زمانی که به این فیلد مقدار داده شود اگر کاربری با آن نام کاربری موجود باشد و فرزند درخواست دهنده OTP باشد توکن برای فرزند صادر می شود و اگر کاربری با آن نام کاربری موجود نباشد یک کاربر جدید با همان نام کاربری به عنوان فرزند برای درخواست دهنده ایجاد می شود.
نکته مهم: توجه نمایید که فقط یکی از 4 پارامتر loginAsUsernameChild ، loginAsRelativeNationalcode ، loginAsUserId ، nationalcode را می توانید ارسال نمایید.
** نکته مهم: در صورت ارسال کردن این پارامترها و عدم وجود کاربر با کد ملی و شماره تلفن ارسال شده، کاربر جدید ایجاد می شود.
پارامترcodeLength : طول کد OTP تولید شده می باشد که حداقل آن 4 عدد می باشد و به صورت پیش فرض اگر مقداری برای این پارامتر ارسال نشود کد 6 رقمی تولید می شود.
پارامترstate : اختیاری می باشد و در صورت ارسال، در پاسخ سرویس بعدی مقدار آن را دریافت خواهید کرد. و می توانید به عنوان مثال برای برخی چک های امنیتییا ... سمت خودتان از آن استفاده نمایید.
پارامترredirect_uri : آدرس های پذیرنده
پارامترcallback_uri : اگر مقداری برای این پارامتر ارسال شود مقدار tokenیاcode به این آدرس ارسال و نمایش داده خواهد شد و ریسپانس سرویس بعدیverify خالی برگردانده می شود و فقط statuscode 202 را به معنی وریفای شدن دریافت خواهید کرد اما اگر مقدار این پارامتر ارسال نشود در پاسخ سرویس بعدی ریسپانس هم دریافت خواهد شد.
پارامترresponse_type : نوع اطلاعات درخواستی می باشد که شامل codeیاtokenیاid_token می باشد.
پارامترcode_challenge و code_challenge_method برای برنامه های بدون سرور استفاده می شود و به صورت S256 مقداردهی می شود.
پارامترreferrer و referrerType را نیز جهت ثبت معرف می توانید ثبت نمایید که با یکییکی از مشخصه هایid/username/phone_number/email/nationalcode مقداردهی می شود.
پارامترscope : اسکوپ هایی که نیاز است تا مجوز آنها را از کاربر دریافت نمایید در این پارامتر میتوانید ارسال کنید.
" نکته: در صورتی که مایل به دریافت لینک جهت ثبت پسورد و صفحه ی تغییر پسورد هستید پارامتر scope را میبایست بدون مقدار change_password ارسال داشته باشید و لینک در سرویسotp/verify نمایش داده می شود .لازم به ذکر است این لینک برای کاربران سطح مالی 4 و بیشتر ارسال می گردد."
پارامترlinkDeliveryType: این پارامتر مشخص کننده ی نحوه ی دریافت لینک جهت ثبت رمزعبور یا لاگین دو عاملی می باشد و میتواند دو مقدار SMS و ON_RESPONSE داشته باشد .
مقدارSMS برای ارسال مستقیم لینک به کاربر و ON_RESPONSE برای دریافت لینک مورد نظر در پاسخ سرویسotp/verify در فیلدcontent می باشد.
"لازم به ذکر است مقدار پارامتر linkDeliveryType به صورت پیش فرض SMS می باشد ."
نکته مهم : چنانچه لاگین کاربر توسط این سرویس به واسطه شماره موبایل ایشان باشد و پارامتر کد ملی را نیز در سرویس ارسال کنید و کاربر مورد نظر قبلا با شماره دیگری که مربوط به این کد ملی هست وجود داشته باشد اطلاعات و حساب های پادی این کاربر توسط سیستم مرج و کاربر با چند موبایل شناسایی خواهد شد .
توجه داشته باشید در اینجا، مقدار user_id برابر با sso_id واقعی (سمت core) است.
خطای رایج در سرویس فوق:
errorCode | دلیل خطا | شرح خطا |
400 | Invalid_param | اشتباه در وارد کردن مقدار identity ( مقدار identity شمارههمراهیاایمیلمیباشد) |
401 | Invalid_signature | سرویس handshake کلاینت برای تولید پارامتر های مورد نیاز برای بدست آوردن signature باید فراخوانی شود. |
تایید OTP
نحوه تاییدotp دریافت شده از طریق پیامک / ایمیل به با استفاده از سرویس verify و به شکل زیر است:
پارامتر Authorization متشکل از سه بخش Signature keyId و signature و headers است که در سرویس بالا توضیحات ساخت آن داده شد.
در پاسخ سرویس فوق، پارامترهایcode و state (در صورت وجود) را دریافت خواهید نمود.
"نکته: در صورتی که کاربر سطح 4 و بیشتر باشد و رمز عبور ثبت شده ای نداشته باشد لینک جهت ثبت رمز عبور نمایش داده می شود و در صورتی که کاربر رمز عبور ثبت شده داشته باشد لینک جهت تغییر رمز عبور نمایش داده می شود."
پاسخ دریافتی از سرویس فوق به صورت زیر خواهد بود:
در صورتی که کاربر پسوردی ثبت نکرده باشد یا کاربر مایل به بازیابی رمز باشد خروجی دریافتی از سرویس به شکل زیر می باشد :
در صورت ارسال کد اشتباه یا منقضی شده به صورت مکرر، دستگاه مورد نظر برای مدتی مشخص مسدود می گردد .
خروجی دریافتی به شرح زیر می باشد:
در صورت ورود کد تایید درست و یا نادرست پیغام ورود موفق و ناموفق رویidentity(شماره موبایل / آدرس ایمیل ) ارسالی دریافت خواهید نمود.
کد خطاهای رایج در سرویس فوق:
errorCode | دلیل خطا | شرح |
400 | Verification code is either wrong or expired | کد ارسالی، یا منقضی شده است و یا اشتباه است. |
400 | Proper client handshake is needed | پارامتر authorization اشتباهارسالشدهاست. |
403 | Device is locked | با ارسال کد اشتباه تا سه مرتبه، device قفل خواهد شد و تا 15 دقیقه مجوز لاگین نخواهید داشت. |
دریافت توکن دسترسی : Access Token
همچنین برای دریافت توکن دسترسی از درخواست زیر استفاده نمایید. در این درخواست لازم است آدرس برگشت مطابق با client_id و client_secret و درست برابر با مقدار ارسال شده به صفحه ورود کاربران باشد. در غیر این صورت، خطای دسترسی اعلام خواهد شد.
کد خطاهای رایج در سرویس فوق:
errorCode | دلیل خطا | شرح |
400 | Invalid or expired code | کد ارسالی منقضی شده یا معتبر نمی باشد. |
400 | unsupported grant type | مقدار grant_type ارسالشدهپشتیبانینمیشود. |
401 | Invalid client credentials | مقدار client_id یا client_secret اشتباهمیباشد. |
500 | Internal server error | توکن ارسالی نا معتبر است. |
ورود با استفاده از UI POD(با استفاده از autoLogin):
چنانچه کسب و کار نیاز دارد کاربر خود را به صفحه پنل کاربری ( وب ) هدایت کند میبایست ابتدا مطابق فرمت و ترتیب زیر رشته خود را توسط کلید خصوصی و روش RSA-SHA256 ساین و با متد base64 رمزنگاری شود.
اطلاعاتي كه در sign بايد در payload وارد شوند به شکل زیر می باشند و با enter (خط جدید newLine \n) از هم جدا می شوند:
access_token: accesstoken
key_id: keyid
timestamp: currenttimestamp
sign=signBase64(privateKey , payLoad,sha-256);
سپس امضای تولید شده به روش فوق را به شکل زیر تبدیل نمایید:
var finalSign = encodeURIComponent("sign")
در نهایت مقدار finalSign را همانند لینک زیر بسازید:
https://panel.pod.ir/Businesses/?key_id=[yourkeyid]&access_token=[accesstoken]×tamp=[current timestamp]&signature=[sign]
نکته: دقت نمایید اسکوپ مربوط به login در این حالت خاص را میبایست از پــــاد دریافت کنید در غیر این صورت خطای دسترسی غیر مجاز را دریافت خواهید کرد.
همچنین در این بخش از پلتفرم امکان لاگینOTP برای کاربران در UI نیز فراهم شده است که برای این منظور تنها کافیست در آدرس مربوط به لاگین پاد که در بخش زیر آمده است ، prompt=otp_login را قرار داده تا در انتها لاگین در UI همراه با وارد کردن OTP امکان پذیر باشد .
https://accounts.pod.ir/oauth2/authorize/index.html?client_id=9327444a9d4b266a7d6c1c76&response_type=code&redirect_uri=https://panel.pod.ir:443/Auth/UserLoginCallback/&prompt=otp_login
ورود با Auto login
توسط این ویژگی امکان ورود کاربر به سامانه های مختلف در پاد بدون وارد کردن مجدد نام کاربری و کلمه ی عبور و به صورت خودکار در وب داده می شود.
در این ویژگی کسب و کار با استفاده از توکن کاربر(Access Token) امکان ورود بدون وارد کردن نام کاربری و کلمه ی عبور را به کاربر مورد نظر خود می دهد.
زمانی که کسب و کار نیاز دارد کاربر خود را به صفحه پنل کاربریsso (وب) هدایت کند و از این ویژگی استفاده نماید می بایست توکن کاربر را دریافت نماید.
برای استفاده از ویژگی اتولاگین بانکی مراحل زیر را به ترتیب انجام دهید:
در ابتدا کسب و کار می بایست آدرس بازگشتی (redirect_uri) خود را در پنل ثبت و با استفاده از لینک زیر توکن کاربر(Access token)برای کاربر دریافت نماید.
https://accounts.pod.ir/oauth2/authorize/index.html?
client_id=<CLIENTID>
&response_type=token
&redirect_uri=<REDIRECT_URI>
&scope=profile:read+login
"توجه فرمایید برای دریافت اکسس توکن، در ابتدا از طریق پنل کسب و کار دریافت توکن یک مرحله ای را فعال و برایclientId ثبت شده در URL بالا اسکوپ login را از پاد دریافت نمایید در غیر این صورت خطای دسترسی غیرمجاز را دریافت خواهید کرد."
* درصورت نداشتن اسکوپ فوق جهت دریافت آن در داخل سامانه ی فمس به تیمPod-Core-Security درخواست ثبت نمایید .
نکته: مدت اعتبار اکسس توکن دریافتی 15 دقیقه می باشد.
پس از دریافت اکسس توکن کاربر از لینک فوق، سرویسhandshake/users را فراخوانی کنید.
نکته: لازم به ذکر است Authorization در این سرویس همان Access_Token دریافتی از لینک بالا می باشد.
پارامترkeyAlgorithm بر اساس نوع رمزنگاری که مد نظرتان هست مشخص می شود و هرکدام در خروجی نوع متفاوتی از کلیدها را بر می گرداند.
خروجی دریافتی الگوریتم ها به شرح زیر می باشد:
AES: کلیدهایsecretKey و keyId
DES: کلیدهایsecretKey و keyId
RSA: کلیدهایpublicKey، private و keyId
"نکته: در این ویژگی الگوریتم مورد نیاز برای رمزنگاریRSA می باشد."
پارامترkeyFormat نوع فرمت کلید مورد نظر شما را مشخص می کند که می تواند xmlیاpem باشد.
پارامترvalidity زمان منقضی شدن کلید به صورت پیش فرض یک سال میباشد. ولی می توانید مقدار آن را با ارسال این پارامتر تعیین نمایید.(برحسب ثانیه )
پارامترrenew چنانچه برابر با false باشد کلید قبلی کاربر نمایش داده می شود و چنانچه برابر با true باشد کلیدهای قبلی حذف و کلید جدید تولید خواهد شد .
پارامترkeySize نیز سایز کلید تولید شده می باشد که در واحد بیت میبایست ثبت گردد مثلا 1024 یا 2048 کیلوبیت.
توجـــــــه : این سرویس تنها برای کاربران قابل استفاده هست و باید توکن کاربر برای دریافت کلید ارسال شود.
نمونه پاسخ دریافت شده از سرویس فوق، به صورت زیر خواهد بود:
برای استفاده از ویژگی اتولاگین بانکی، کلید هایkeyId ،privateKey و publicKey دریافتی در خروجی مورد نیاز می باشد.
توجه فرماییدprivatekey دریافتی از سرویس هندشیک فوق بر اساس استاندارد PKCS8 می باشد.
" نکته : مدت اعتبار keyId بدست آمده از فراخوانی سرویس هندشیکیک سال می باشد."
در صورت دریافت خطا به جدول زیر مراجعه نمایید:
errorCode دلیل خطا شرح
400 Bad Request invalid_device در این حالت توکن ارسالی شما احتمالا API توکن و یا توکن تینگز بوده است.
415 Unsupported Media Type پارامترها باید در بدنه درخواست و به صورت application/x-www-form-urlencoded ارسال بشوند.
پس از دریافت کلید های موردنیاز، می بایست اقدام به ساختsignature نمایید.
برایساختsignature مراحل زیر را انجام دهید:
در ابتدا payload مورد نیاز برای ساین در جدول sectools را به شرح زیر بدست آورید:
1. برای تولیدpayload، پارامتر های مورد نیاز به شرح زیر می باشد:
access_token: accesstoken دریافتی از لینک مراحل ابتدایی (توجه فرمایید که نباید زمان توکن منقضی شده باشد)
keyId : مقدارkeyId دریافتی از سرویس هندشیکیوزر
currenttimestamp: timestamp زمان جاری (تعداد ارقام قابل قبول برای این پارامتر 10 تا 13 رقم می باشد)
نکته: در payload سطرها با enter از هم جدا می شوند، همچنین بین : و مقادیریکspace گذاشته می شود.
2. بعد ازتولیدpayload جهت ساین وارد لینکhttps://accounts.pod.ir/secTools.html شوید.
3. پس از ورود به لینک فوق در قسمت payload، payload تولید شده در مرحله ی فوق و در قسمت privateKey کلید خصوصی دریافتی از سرویس هندشیکیوزر را ثبت نمایید.
4.در این مرحله دکمه یsign:RSA-256 را بزنید.
5. پس از فشار بر روی دکمه ی مذکور در قسمت Signature(base64)، امضای دیجیتال خود را دریافت کنید.
پس از تولیدsignature به روش بالا از طریقsectools، مقادیر پارامترهایkey_id ،access_Token ،timestamp وsignature را باید به صورت جداگانه رمزنگاری(encode) و سپس وارد نمایید . (بدون رمز نگاری کردن & ها)
سپسیک صفحه لاگین باز کنید، پارامترهایaccess_Token ،key_id ،timestamp ،signature را همانند لینک زیر به آدرس صفحه اضافه کنید.
نمونه لینک ارسالی در صفحه لاگین به شرح زیر می باشد:
http://youraddress/v1/PBC/Payinvoice/?invoiceId=INVOICE_ID&access_token=ACCESS_TOKEN&key_id=KEY_ID×tamp=TIMESTAMP&signature=SIGN
**در صورتی که مقادیر ارسالی صحیح باشد باید با کاربری که access_token برای او می باشد بدون پرسیدن نام کاربری و رمز در صفحه وب لاگین انجام شود.**
سرویس دریافت autoLoginCode
توسط این سرویس کسب و کار می تواند بدون ارسال پارامتر های key_id و access token و timestamp و signature در لینک لاگین پادی ، امکان ورود کاربران خود را به سامانه های مختلف در پاد بدون وارد کردن مجدد نام کاربری و کلمه ی عبور و به صورت خودکار در وب بوجود آورد.
- تفاوت Auto login سرویسی با مابقی روش های Auto login :
امنیت بالای آن در عدم نمایش اطلاعات نظیر signature و key_id و access token و
ارسال تنها یک پارامتر auto_login_code به جای 4 پارامتر key_id و access token و timestamp و signature در لینک لاگین پادی.
- شناسه سرویس: ندارد.
- آدرس سرویس :
https://accounts.pod.ir/oauth2/submit/autoLogin
- پارامترهای ورودی:
پارامتر | نوع | اختیاری/ اجباری | توضیحات |
Header | |||
Content-Type |
|
| application/x-www-form-urlencoded |
Accept-Language |
|
| fa |
Authorization |
|
| Bearer {Api_Token} |
| |||
key_id | Number | اجباری | دریافتی در سرویس هندشیک یوزر می باشد . ( مطابق با فرآیند در مستند Auto login) |
timestamp | String | اجباری | timestamp زمان جاری به صورت تایم استمپ براساس میلی ثانیه می باشد . (تعداد ارقام قابل قبول برای این پارامتر 13 رقم می باشد) مثال : 1681543800000 |
signature | String | اختیاری | signature دریافتی از ساین Payload به همراه کلید خصوصی دریافتی در پاسخ سرویس هندشیک یوزر می باشد. که باید به فرمت base64 انکد شود . |
access_token | String | اختیاری | اکسس توکن کاربر مورد نظر می باشد. (اختیاری) نکته :در صورت انجام فرآیند اتولاگین با اکسس توکن پادی تنها از پارامتر access_token استفاده نمایید.
|
mtn_access_token | String | اختیاری | اکسس توکن کاربر بر روی SSO بیرونی ایرانسل می باشد. :در صورت انجام فرآیند اتولاگین با اکسس توکن ایرانسل تنها از پارامتر mtn_access_token استفاده نمایید. |
bpi_id_token | String | اختیاری | اکسس توکن بانکی کاربر مورد نظر می باشد در صورت انجام فرآیند اتولاگین با اکسس توکن بانکی تنها از پارامتر bpi_id_token استفاده نمایید. |
id_token | String | اختیاری | id_token کاربر مورد نظر می باشد. در صورت انجام فرآیند اتولاگین با id_token کاربر تنها از پارامتر id_token استفاده نمایید |
{نکات سرویس}
پارامترهای فراخوانی این سرویس متفاوت با الگوی سرویسهای پادیوم است .
- خروجی: ساختار کلی پاسخ دریافتی در این لینک به تفصیل شرح داده شده است.
بدنه ی پاسخ دریافتی دارای ساختار زیر است:
پارامتر | نوع | توضیحات |
پارامترهای نهایی در خروجی | ||
access_token | string | اکسس توکن ارسالی کاربر در سرویس مذکور |
auto_login_code | string | کد دریافتی اتولاگین –
|
key_id | string | ارسالی در سرویس مذکور key_id |
signature | string | ارسالی در سرویس مذکور signature |
timestamp | string | زمان جاری ارسالی در سرویس مذکور |
ساخت لینک Login درپاد
فیلد auto_login_code دریافتی در پاسخ سرویس را می توانید جایگزین key_id و access token و timestamp و signature در لینک لاگین پادی برای اتولاگین نمایید و در نهایت لینک اتولاگین را به شکل زیر ایجاد نمایید
https://accounts.pod.ir/oauth2/authorize/?client_id=[CLIENT_ID]
&redirect_uri=[REDIRECT_URI]
&response_type=code
&scope=[SCOPE]
&auto_login_code=[AUTO_LOGIN_CODE]
نکته: در صورتی که کسب و کار مایل به استفاده از امکان لاگین از طرف در اتولاگین می باشد می تواند از لینک اتولاگین به صورت زیر استفاده نماید و پارامتر login_as_user_id را همراه با شناسه SSOID کاربر موردنظر خود ارسال نماید .
https://accounts.pod.ir/oauth2/authorize/?client_id=[CLIENT_ID]
&redirect_uri=[REDIRECT_URI]
&response_type=code
&scope=[SCOPE]
&auto_login_code=[AUTO_LOGIN_CODE]
&login_as_user_id=[ ssoid user]
کدهای ارور (errorCode) معمول در پلتفرم:
برای مشاهدهی سایر کدهای ارور پلتفرم به این لینک مراجعه کنید.
کدهای خطای سرویس دریافت autoLoginCode:
کد خطا | دلیل خطا | شرح خطا |
400 | Bad Request | فیلد signature نمیتواند مقدار خالی داشته باشد. |
400 | Bad Request | فیلد timestamp نمیتواند مقدار خالی داشته باشد. |
400 | Bad Request | فیلد key_id نمیتواند مقدار خالی داشته باشد |
401 | Unauthorized | توکن نا معتبر |
کد خطاهای مربوط به ساخت و استفاده از لینک Login:
متن خطا : شرح خطا
اسکوپ لاگین نیاز می باشد:
در صورت عدم دریافت اکسس توکن اولیه با اسکوپ Login این متن خطا نمایش داده می شود
کلید امضا اشتباه می باشد و یا منقضی شده است:
در صورت عدم ارسال signature صحیح یا منقضی شدن signature این متن خطا نمایش داده می شود
امضا اشتباه می باشد:
در صورت ارسال signature اینکد نشده این متن خطا نمایش داده می شود
ارسال تکراری تایم استمپ برای signature امکان پذیر نمی باشد:
در صورت ارسال timestamp تکراری تصویر زیر نمایش داده می شود .
Auto login با OTP
این سرویس،OTP را از طریق تلفن و یا ایمیل به کاربر ارسال نمی کند و مراحل به صورت اتومات انجام شده و توکن دریافت می شود.
این سرویس 5 مرحله دارد :
مرحله اول: در ابتدا از طریق سرویس دریافت توکن دسترسی کاربر، Id_token مورد نیاز در مراحل بعدی را بدست آورید.
به صورت کلی برای دریافت توکن بایدClient_Id و Client_secret به همراه یک کد که کلاینت آن را از سیستم دریافت می کند، برای سیستم ارسال شود اما روش دیگری تحت عنوان PKCE برای دریافت توکن وجود دارد که در این حالت برای اپلیکیشن های موبایلی و وبی که نمی توانند امنیت ذخیره سازیClient_secret را تضمین کنند قابل استفاده است.
مراحل دریافت توکن به روش PKCE شامل مراحل زیر است: (که در صورت دریافت توکن به این روش فیلدcode_verifier الزاما باید پر شود.)
ابتدا وارد لینکhttps://accounts.pod.ir/secTools.html بخش Base64/Hash tools شوید.
2. یک مقدار(شامل عدد و حروف) را در قسمت Payload وارد کنید و بعد دکمه یSHA256-Base64url را فشار دهید.
3. پس از فشار دادن دکمه یSHA256-Base64url مقدار هش بدست آمده در قسمت Result را نگه داری کنید .
"نکته : مقدار ذکر شده در قسمت Payload را به عنوان مقدار پارامتر code_verifier و مقدار به دست آمده در قسمت Result را به عنوان مقدار پارامتر code_challenge قرار دهید."
4. مقدار کلاینت آی دی و code_challenge بدست آمده در مراحل قبل را در URL زیر جایگزین و لاگین را با کاربری مذکور انجام دهید.
توجه فرمایید در صورتی که کلاینت آی دی قید شده در URL بالا اسکوپ مورد نیاز را نداشته باشد با خطا روبرو می شوید.
درصورت مشاهده خطا جهت دریافت اسکوپ مورد نیاز در داخل سامانه ی فمس به تیمPod-Core-Security درخواست ثبت نمایید .
در صورت داشتن اسکوپ پس از لاگین با URL فوق، کد مورد نیاز را دریافت می کنید.
برای دریافت توکن دسترسی از درخواست زیر استفاده نمایید و علاوه بر client_secret و client_id و آدرس بازگشت، کد کاربر (در صورت استفاده از روش pkce) را نیز در آن قرار دهید.
در این درخواست لازم است آدرس برگشت مطابق با client_id و client_secret و درست برابر با مقدار ارسال شده به صفحه ورود کاربران باشد. در غیر این صورت، خطای دسترسی اعلام خواهد شد به همین خاطر میبایست در ابتدا آدرس بازگشتی قید شده در این سرویس را در پنل کسب وکار ثبت شده باشد.
پارامترgrant_type: مقدار این پارامتر را برابر یکی از حالت هایauthorization_code (كد مجاز)، refresh_token و password قرار دهید .
لازم به ذکر است در این سرویس مقدار پارامتر grant_type میبایست در حالت authorization_code (كد مجاز) باشد.
پارامترredirect_uri: آدرس بازگشتی ثبت شده در پنل کسب و کارو ذکر شده در url لاگین برای دریافت کد می باشد.
پارامترcode_verifier: فقط در صورت استفاده از PKCE برای ورود به سیستم قابل اجرا می باشد. مقدار این پارامتر در مرحله ی دوم روش مذکور بدست آورید.
پارامترcode: فقط در صورت استفاده از PKCE برای ورود به سیستم قابل اجرا می باشد. مقدار این پارامتر پس از لاگین با uri ذکر شده در روش مذکور بدست آورید.
پارامترcallback_uri: آدرسی برای ارسال پاسخ دریافتی سرویس می باشد.
پارامترrefresh_token: مقدار رفرش توکن را در این پارامتر ثبت کنید.
پارامترusername: فقط در صورت استفاده از مقدار password در پارامتر garnt_type برای ورود به سیستم قابل اجرا می باشد و مقداراین پارامتر را برابر با نام کاربری قرار دهید.
پارامترpassword: فقط در صورت استفاده از مقدار password در پارامتر garnt_type برای ورود به سیستم قابل اجرا می باشد و مقداراین پارامتر را برابر با پسورد مورد نظر برای کاربر قرار دهید.
: identityTypeشامل یکی از مشخصه هایid,bpi_customer_number,username,phone_number,email,nationalcode برای انتخاب کاربر می باشد.
: Identityشناسه کاربر که مقدارش بر اساس فیلدidentityTypeمشخص می شود.
"توجه فرمایید برای دریافتId_token ارسال پارامتر هایgrant_type، code_verifier، redirect_uri و code کافی می باشد و نیازی به ارسال همه ی پارامتر های فوق نیست."
پاسخ سرویس حاویrefresh_token، access_token و id_token می باشد که اعتبار access_token به مدت 15 دقیقه می باشد.
در ساختار OAuth برای هر کاربر یکId_token در اختیار کلاینت قرار می گیرد که نوعی توکن محسوب می شود که فقط برای شناسایی اطلاعات کاربر در مواقعی که بین چندین دستگاه جابجا میشود، استفاده میشود و برای دسترسی به api سرویس ها غیرقابل استفاده می باشد.
access_token را به اپلیکیشن ارسال نمایید و توجه نمایید که refresh_token را سمت سرور نگه داری کرده و به اپلیکیشن ارسال ننمایید. ازrefresh_token برای دریافت توکن جدید استفاده نمایید.
"نکته : Id_token دریافتی در خروجی سرویس فوق را برای مراحل بعدی در فایلی نگه داری کنید."
مرحله دوم : حال از طریق فراخوانی سرویس هندشیک کلاینت می بایستkey_id بدست آورید.
قبل از فراخوانی سرویس هندشیک برای دریافت کلید عمومی و خصوصی مراحل زیر را انجام دهید :
ابتدا وارد لینکhttps://accounts.pod.ir/secTools.html شوید.
بدون وارد کردن مقداری دکمه یGenerate:RSA-2048را بزنید.
3. پس از فشار دادن دکمه ی فوق کلید عمومی و خصوصی نمایش داده می شود.
نکتـــــه مهم : قبل از فراخوانی سرویس هندشیک، کلید عمومی دریافتی از قسمت فوق را در پنل کسب و کاری خودتان بارگذاری نمایید در غیر این صورت خطای مناسب را دریافت خواهید کرد.
پس از دریافت کلید عمومی و خصوصی، سرویسhandshake را به منظور معرفی دستگاه و همچنین تفاهم بر روی پارامترهای امضای دیجیتال (شامل algorithm،keyId) فراخوانی کنید. برای فراخوانی این سرویس نیاز به api_token و client_id میباشد که از پنل مدیریت کسب و کار قابل دریافت است.
کپی کد
پارامترdevice_uid توسط سرور کسب و کار تولید میشود و بایدیک شناسه ی منحصر به فرد و دلخواه باشد. همچنین دقت نمایید این مقدار باید به ازای هر دستگاه نگهداری شود و هربار برای ورود این سرویس را فراخوانی نکنید زیراKeyid تولید شده توسط این سرویسیکسال اعتبار دارد و برای سرویس های بعدی نیز می توانید برای همان دستگاه این مقدار را نگهداری کنید و استفاده نمایید و هربار handshake انجام ندهید.
پارامترdevice_name جهت فهم کاربر از وسیله ای که در آن وارد شده است مفید خواهد بود. بنابرین توصیه می شود مشخصاتی از برنامه و ابزاری که کاربر وارد آن شده است ارسال گردد.
"لازم به ذکر است publicKey دریافتی در خروجی سرویس هندشیک بالا همان publicKey بارگذاری شده در پنل کسب و کار می باشد که از طریقsectools دریافت کرده اید."
نمونه پاسخ دریافت شده از سرویس فوق، به صورت زیر است:
keyId پارامتر خروجی در سرویس هندشیک فوق می باشد این کلیدیک سال زمان اعتبار دارد به همین خاطر نیاز به فراخوانی چندین بار سرویس هندشیک نیست. در صورت تمایل مقدار keyId نمایش داده شده را نگهداری فرمایید.
خطاهای رایجی که در فراخوانی سرویس فوق، ممکن است با آن روبرو شوید در جدول زیر آورده شده است:
errorCode دلیل خطا شرح خطا
400 Invalid_device ارسال بدون مقدار پارامتر device_uidیا عدم ارسال پارامتر device_uid
401 Invalid token در صورتی که مقدار توکن اشتباه باشد و یا این مقدار ارسال نگردد، این پیغام را دریافت خواهید کرد.
403 Invalid grant عدم ارسال مقدار client_id در URL
404 Not Found کلید عمومی پیدا نشده است.(عدم بارگذاری کلید عمومی در پنل کسب و کار)
500 Internal Server Error عدم ارسال پارامتر Content-Type
در مرحله بعد لازم است با keyId دریافتی در سرویس هندشیک فوق و کلید خصوصی کسب و کار یک امضای دیجیتال تولید شود و همراه شماره موبایلیا ایمیل کاربر به SSO ارسال گردد. تصویر زیر فرایند کلی را نمایش می دهد.
مرحله سوم : پس از دریافتId_token وکلید های موردنیاز، می بایست اقدام به دریافتsignature نمایید.
برای دریافتsignature مراحل زیر را انجام دهید:
در ابتدا payload مورد نیاز برای ساین در جدول sectools را به شرح زیر بدست آورید:
برای تولیدpayload، پارامتر های مورد نیاز به شرح زیر می باشد:
Id_token: Id_token دریافتی ازسرویس دریافت توکن کاربر ( مرحله ی اول در این سرویس )
keyId : مقدارkeyId دریافتی از سرویس هندشیک کلاینت
timestamp : timestamp زمان جاری (تعداد ارقام قابل قبول برای این پارامتر 10 تا 13 رقم می باشد)
نکته: در payload سطرها با enter از هم جدا می شوند، همچنین بین : و مقادیریکspace گذاشته می شود.
2. بعد ازتولیدpayload جهت ساین وارد لینکhttps://accounts.pod.ir/secTools.html شوید.
3. پس از ورود به لینک فوق در قسمت payload، payload تولید شده در مرحله ی فوق و در قسمت privateKey کلید خصوصی دریافتی از sectools در مرحله ی دوم را ثبت نمایید.
4.در این مرحله دکمه یsign:RSA-256 را بزنید.
5. پس از فشار بر روی دکمه ی مذکور در قسمت Signature(base64)، امضای دیجیتال خود را دریافت کنید.
مرحله چهارم: فرآیند تولید پارامتر Authorization مورد نیاز در فراخوانی سرویسauthorizeWithSign به شرح زیر می باشد :
توجه نمایید که پارامتر Authorization در هدر سرویسauthorizeWithSign متشکل از سه بخش Signature keyId و signature و headers است.
نکته این بخش ها با , از هم جدا می شوند:
(Key_id ایجاد شده در مرحله 2) "مقدار مورد نظر"=Signature keyId
(signature ایجاد شده در مرحله 3) "مقدار مورد نظر"=signature
(نام پارامترها) "headers="id_token key_id timestamp
نکته مهم: توجه فرمایید که در بخش headers فقط نام پارامترهایsign شده وارد می شود که با space از هم جدا می شوند.
مرحله پنجم : سرویس زیر (سرويس authorizeWithSign) توسط کلاینت آی دی که Id_token را دریافت داشتید فراخوانی شود.
کپی کد
پارامترstate: اختیاری می باشد و در صورت ارسال، در پاسخ سرویس بعدی مقدار آن را دریافت خواهید کرد.
پارامترclient_id :client_id در مرحله دریافتId_token
پارامترredirect_uri: آدرس های پذیرنده
پارامترcallback_uri: اگر مقداری برای این پارامتر ارسال شود مقدار tokenیاcode به این آدرس ارسال و نمایش داده خواهد شد و ریسپانس سرویس بعدیverify خالی برگردانده می شود و فقط statuscode 202 را به معنی وریفای شدن دریافت خواهید کرد اما اگر مقدار این پارامتر ارسال نشود در پاسخ سرویس بعدی ریسپانس هم دریافت خواهد شد.
پارامترresponse_type: نوع اطلاعات درخواستی می باشد که شامل codeیاtokenیاid_token می باشد و فيلد اجباري مي باشد.
پارامترscope: اسکوپ هایی که نیاز است تا مجوز آن ها را از کاربر دریافت نمایید در این پارامتر می توانید ارسال کنید که تعداد آن ها با space از هم می شوند.
پارامترcode_challenge و code_challenge_method: برای برنامه های بدون سرور استفاده می شود.
پارامترreferrer و referrerType: را نیز جهت ثبت معرف می توانید ثبت نمایید.
پارامترid_token :id_token دریافت شده از مرحله 1
پارامترkey_id :key_id دریافت شده از مرحله 2
پارامترtimestamp :timestamp که در مرحله 3 برایsign استفاده شده است.
** در نهایت جهت صحت عملکرد سرویس می توانید معتبر بودن توکن دریافت شده در خروجی این سرویس را بررسی نمایید. **
پاسخ دریافتی از سرویس فوق به صورت زیر خواهد بود:
Auto login بانکی
توسط این ویژگی امکان ورود کاربر بانکی به سامانه های مختلف در پاد بدون وارد کردن مجدد نام کاربری و کلمه ی عبور و به صورت خودکار در وب داده می شود.
در این ویژگی کسب و کار با استفاده از توکن کاربر (Access Token) امکان ورود بدون وارد کردن نام کاربری و کلمه ی عبور را به کاربر مورد نظر خود می دهد.
زمانی که کسب و کار نیاز دارد کاربر خود را به صفحه پنل کاربریsso (وب) هدایت کند و از این ویژگی استفاده نماید می بایست توکن کاربر را دریافت نماید.
برای استفاده از ویژگی اتولاگین بانکی مراحل زیر را به ترتیب انجام دهید:
در ابتدا کسب و کار می بایست آدرس بازگشتی (redirect_uri) خود را در پنل ثبت و با استفاده از لینک زیر توکن کاربر(Access token)برای کاربر دریافت نماید.
https://accounts.pod.ir/oauth2/authorize/index.html?
client_id=<CLIENTID>
&response_type=token
&redirect_uri=<REDIRECT_URI>
&scope=profile:read
"توجه فرمایید برای دریافت اکسس توکن، در ابتدا از طریق پنل کسب و کار دریافت توکن یک مرحله ای را فعال و برایclientId ثبت شده در URL بالا اسکوپ login را از پاد دریافت نمایید در غیر این صورت خطای دسترسی غیرمجاز را دریافت خواهید کرد."
درصورت نداشتن اسکوپ فوق جهت دریافت آن در داخل سامانه ی فمس به تیمPod-Core-Security درخواست ثبت نمایید .
نکته: مدت اعتبار اکسس توکن دریافتی 15 دقیقه می باشد.
پس از دریافت اکسس توکن کاربر از لینک فوق، سرویسhandshake/users را فراخوانی کنید.
نکته : لازم به ذکر است Authorization در این سرویس همان Access_Token دریافتی از لینک بالا می باشد.
پارامترkeyAlgorithm بر اساس نوع رمزنگاری که مد نظرتان هست مشخص می شود و هرکدام در خروجی نوع متفاوتی از کلیدها را بر می گرداند.
خروجی دریافتی الگوریتم ها به شرح زیر می باشد:
AES: کلیدهایsecretKey و keyId
DES: کلیدهایsecretKey و keyId
RSA: کلیدهایpublicKey، private و keyId
"نکته: در این ویژگی الگوریتم مورد نیاز برای رمزنگاریRSA می باشد."
پارامترkeyFormat نوع فرمت کلید مورد نظر شما را مشخص می کند که می تواند xmlیاpem باشد.
پارامترvalidity زمان منقضی شدن کلید به صورت پیش فرض یک سال میباشد. ولی می توانید مقدار آن را با ارسال این پارامتر تعیین نمایید.
پارامترrenew چنانچه برابر با false باشد کلید قبلی کاربر نمایش داده می شود و چنانچه برابر با true باشد کلیدهای قبلی حذف و کلید جدید تولید خواهد شد .
پارامترkeySize نیز سایز کلید تولید شده می باشد که در واحد بیت میبایست ثبت گردد مثلا 1024 یا 2048 کیلوبیت
توجـــــــه : این سرویس تنها برای کاربران قابل استفاده هست و باید توکن کاربر برای دریافت کلید ارسال شود.
نمونه پاسخ دریافت شده از سرویس فوق، به صورت زیر خواهد بود:
برای استفاده از ویژگی اتولاگین بانکی، کلید هایkeyId ،privateKey و publicKey دریافتی در خروجی مورد نیاز می باشد.
توجه فرماییدprivatekey دریافتی از سرویس هندشیک فوق بر اساس استاندارد PKCS8 می باشد.
" نکته : مدت اعتبار keyId بدست آمده از فراخوانی سرویس هندشیکیک سال می باشد."
در صورت دریافت خطا به جدول زیر مراجعه نمایید:
errorCode دلیل خطا شرح
400- Bad Request invalid_deviceدر این حالت توکن ارسالی شما احتمالا API توکن و یا توکن تینگز بوده است.
415- Unsupported Media Type پارامترها باید در بدنه درخواست و به صورت application/x-www-form-urlencoded ارسال بشوند.
پس از دریافت کلید های موردنیاز، می بایست اقدام به دریافتsignature نمایید.
برای دریافتsignature مراحل زیر را انجام دهید:
در ابتدا payload مورد نیاز برای ساین در جدول sectools را به شرح زیر بدست آورید:
برای تولیدpayload، پارامتر های مورد نیاز به شرح زیر می باشد:
bpi_id_token: JWT_TOKEN (توکن بانکی دریافتی پس از ورود به اینترنت بانک )
keyId : مقدارkeyId دریافتی از سرویس هندشیکیوزر
timestamp: زمان جاری (تعداد ارقام قابل قبول برای این پارامتر 10 تا 13 رقم می باشد)
نکته: در payload سطرها با enter از هم جدا می شوند، همچنین بین : و مقادیریکspace گذاشته می شود. (طبق عکس زیر)
2. بعد ازتولیدpayload جهت ساین وارد لینکhttps://accounts.pod.ir/secTools.html شوید.
3. پس از ورود به لینک فوق در قسمت payload، payload تولید شده در مرحله ی فوق و در قسمت privateKey کلید خصوصی دریافتی از سرویس هندشیکیوزر را ثبت نمایید.
4.در این مرحله دکمه یsign:RSA-256 را بزنید.
5. پس از فشار بر روی دکمه ی مذکور در قسمت Signature(base64)، امضای دیجیتال خود را دریافت می کنید.
پس از تولیدsignature به روش بالا از طریقsectools، مقادیر پارامتر هایkey_id ،bpi_id_token، timestamp و signature را باید به صورت جداگانه رمزنگاری(encode) و سپس وارد نمایید . (بدون رمز نگاری کردن & ها)
سپسیک صفحه لاگین باز کنید، پارامترهایbpi_id_token ،key_id ،timestamp ،signature را همانند لینک زیر به آدرس صفحه اضافه کنید.
نمونه لینک ارسالی در صفحه لاگین به شرح زیر می باشد:
کپی کد
**در صورتی که مقادیر ارسالی صحیح باشد باید با کاربری که bpi_id_token برای او می باشد بدون پرسیدن نام کاربری و رمز در صفحه وب لاگین انجام شود.**
دریافت توکن دسترسی کاربر
در صورتی که می خواهید کاربران شما از خدمات دیگر پلتفرم پایه مانند کیف پول استفاده نمایند، باید توکن دسترسی آنها را دریافت نمایید و با استفاده از آن، کاربر را در پلتفرم پایه ثبت نمایید. برای دریافت توکن دسترسی از درخواست زیر استفاده نمایید و علاوه بر client_secret و client_id و آدرس بازگشت، کد کاربر را نیز در آن قرار دهید.
در این درخواست لازم است آدرس برگشت مطابق با client_id و client_secret و درست برابر با مقدار ارسال شده به صفحه ورود کاربران باشد. در غیر این صورت، خطای دسترسی اعلام خواهد شد.
پارامترgrant_type: با توجه به نياز بايد در يكي از حالت هاي authorization_code (كد مجاز) يا refresh_token (رفرش كردن كد) باشد.
پارامترidentityType: می تواند بر اساس یکی از مشخصه هایid/bpi_customer_number/username/phone_number/email/nationalcode کاربر باشد.
پارامترcode_verifier: فقط در صورت استفاده از PKCE برای ورود به سیستم قابل اجرا می باشد.
پارامترlinkDeliveryType: این پارامتر مشخص کننده ی نحوه ی دریافت لینک لاگین دو عاملی جهت تخصیص کد می باشد و میتواند دو مقدار SMS و ON_RESPONSE داشته باشد .
مقدارSMS برای ارسال مستقیم لینک لاگین دو عاملی به کاربر و ON_RESPONSE برای دریافت لینک لاگین دو عاملی درهدر پاسخ سرویس مذکور در فیلدContent_Location می باشد.
"لازم به ذکر است مقدار پارامتر linkDeliveryType به صورت پیش فرض SMS می باشد ."
به صورت کلی برای دریافت توکن بایدClient_Id و Client_secret به همراه یک کد که کلاینت آن را از سیستم دریافت می کند، برای سیستم ارسال شود اما روش دیگری تحت عنوان PKCE برای دریافت توکن وجود دارد که در این حالت برای اپلیکیشن های موبایلی و وبی که نمی توانند امنیت ذخیره سازیClient_secret را تضمین کنند قابل استفاده است.
مراحل دریافت توکن به روش PKCE شامل مراحل زیر است: (که در صورت دریافت توکن به این روش فیلدcode_verifier الزاما باید پر شود.)
1. ابتدا بایدیک مقدار(شامل عدد و حروف) را توسط الگوریتمی رمزنگاری کنید و آن را به عنوان code_verifier و مقدار hash بدست آمده را به عنوان code_challenge در نظر بگیرید.
( می توانید با استفاده از https://accounts.pod.ir/secTools.html در بخش HashToolsیک مقدار دلخواده شامل عدد و حروف مانند QUahYC35aGU را در قسمت PayLoad وارد و با SHA256-Base64url مقدار hash را بدست آورید. مقداری که در PayLoad قرار داده اید همان code_verifier است و مقدار hash بدست آمده به عنوان code_challenge در نظر گرفته می شود.)
2. مقدار hash و نوع الگوریتم آنرا در URL سیستم قرار داده و درخواست لاگین انجام می شود که خروجی آن یک کد خواهد بود. (پارامتر code_verifier)
3. code به دست آمده از مرحله قبل را به همراه code_verifier برای سیستم ارسال می کنید تا بر اساس آنها توکن مورد نظر ساخته و ارسال شود. (پارامترcode )
نکته: پس از گذشت زمان expires_in ، توکن دسترسی کاربر منقضی می شود. (expires_in میلی ثانیه می باشد) با استفاده از refresh_token توکن معتبر جدید درخواست دهید.
در صورت موفقیت پاسخ درخواست فوق به این شکل خواهد بود:
پاسخ سرویس حاویrefresh_token، access_token و id_token می باشد که اعتبار access_token به مدت 15 دقیقه می باشد.
Id_tokenیک توکن self_encoded می باشد که فقط جهت شناسایی کاربر در مواقعی که بین چندین دستگاه جابجا میشود، استفاده میشود و برای دسترسی به api سرویس ها غیرقابل استفاده می باشد.
access_token را به اپلیکیشن ارسال نمایید و توجه نمایید که refresh_token را سمت سرور نگه داری کرده و به اپلیکیشن ارسال ننمایید. ازrefresh_token برای دریافت توکن جدید استفاده نمایید.
از متد زیر هم می توانید برای دریافت رفرش توکن استفاده کنید:
کد خطاهای رایج در سرویس فوق:
errorCode دلیل خطا شرح
400 Invalid or expired code کد ارسالی منقضی شده یا معتبر نمی باشد.
400 unsupported grant type مقدار grant_type ارسال شده پشتیبانی نمی شود.
401 Invalid client credentials مقدار client_idیاclient_secret اشتباه می باشد.
500 Internal server error توکن ارسالی نا معتبر است.
دریافت اطلاعات توکن
با استفاده از سرویس زیر می توانید از صحت و اعتبار توکن کاربر خود مطلع شوید.
به پارامتر token_type_hint سه مقدار مختلف قابل ارسال است که نوع توکن مورد نظر را مشخص می کند:
access_token , refresh_token , id_token
توجــه : در صورتی که مقدار پارامتر token_type_hint ارسال نشود به صورت پیش فرض اطلاعات اکسس توکن نمایش داده می شود، بنابراین برای دریافت اطلاعات رفرش توکن یا ای دی توکن باید این پارامتر مقداردهی شود.
پارامترcode_verifier: فقط در صورت استفاده از PKCE برای ورود به سیستم قابل اجرا می باشد. (توضیحاتPKCE در سرویس های قبل داده شده است)
پاسخ درخواست فوق به این شکل خواهد بود:
پارامترهای موجود در پاسخ این سرویس:
active: فعال/غیر فعال بودن توکن مورد نظر
scope: اسکوپ های داده شده به توکن مورد نظر
client_id: client_id صادر کننده توکن مورد نظر
ssoId :sub صاحب توکن
exp: زمان نامعتبر شدن توکن (بر اساس میلی ثانیه)
id:idevice_uid دستگاهی که روی آن برای کاربر توکن صادر شده است.
id :permitted_user_id کاربری است که مجوز لاگین به صورت جایگزین به آن کاربر داده شده است. (در صورت مجوز لاگین به کاربر دیگر)
ssoId :issuer_client کلاینتی که توکن توسط او صادر شده است.
ابطال توکن
ممکن است به هر دلیلی بخواهید دسترسی برنامه به اطلاعات حساب کاربر را از بین ببرید. برای این منظور از درخواست زیر استفاده نمایید:
Authorization در این سرویس باید به صورت Basic Base64 ارسال شود.
به پارامتر token_type_hint سه مقدار مختلف قابل ارسال است که نوع توکن مورد نظر را مشخص می کند:
access_token , refresh_token , id_token
پارامترcode_verifier: فقط در صورت استفاده از PKCE برای ورود به سیستم قابل اجرا می باشد. ( توضیحاتPKCE در سرویس های قبل داده شده است)
توجه فرمایید که فقط کاربر با نقش father مجاز به استفاده از این سرویس می باشد در غیر این صورت در اجرای سرویس خطا رخ می دهد.
در صورتی که پاسخ http status : 200 باشد، توکن با موفقیت از بین رفته است.
و وضعیت توکن در سرویس info به صورت زیر درخواهد آمد :
خطاهایی که در این سرویس ممکن است با آن روبه رو شوید:
errorcodeدلیل خطاشرح خطا
400unauthorized_client مجاز به حذف توکن نمی باشید.
401Invalid_token توکن ارسالی نامعتبر است.
401Invalid_client client_id اشتباه وارد شده است.
نمایش تاریخچه توکن
توسط سرويس زير قادر خواهيد بود تاریخچه کامل دریافت، حذف و تغییرات توکن ها را مشاهده نماييد.
ورودي اين سرويس، توكن مورد نظر اعم از access_token ، refresh_token ، id_token ، api_token مي باشد.
نكته: توجه داشته باشيد كه فقط كاربر با نقش father مي تواند از اين سرويس استفاده كند.
curl --location --request GET 'https://accounts.pod.ir/admin/reports/tokens/{token}' \
--header 'Authorization: Bearer Token'
با اين سرويس مي توانيد وضعيت، نوع، تاريخ ثبت، تاريخ ابطال، طريقه ثبت، صادر كننده و ابطال كننده "توكن" را مشاهده نماييد.
در اين سرويس گزارش تمامي توكن ها در حالت هاي otp ، login ، PKCE قابل مشاهده مي باشد.
مقدارAuthorization را نیز باید برابر Bearer Token ارسال کنید.
پاسخ اين سرويس به شكل زير است:
کد خطاهای رایج در اين سرویس:
errorCode دلیل خطا شرح
400 Invalid_grant توكن ارسالی منقضی شده یا معتبر نمی باشد.
401 invalid_token توکن ارسالی نامعتبر است.
403 forbidden عدم نقش مجاز
دریافت و ویرایش پروفایل کاربر
دریافت پروفایل کاربر
از طریقapi زیر می توانید اطلاعات کاربری که از طریقSSO وارد برنامه شما شده است را بخوانید.
در صورتی که نیاز به دریافتیا ویرایشclient_metadata دارید بایدclient_id و client_secret را به عنوان پارامتر ارسال نمایید.
ویرایش پروفایل با دسترسیهای کاربر
در صورتی که کاربر به برنامه شما اجازه :write برای هر یک از scope ها داده باشد، می توانید، اطلاعات کاربری او را با توجه به scope ویرایش نمایید. دقت نمایید که عدم ارسال هر کدام از متغیرها که قبلاً در پروفایل کاربر موجود بوده، منجر به پاک شدن اطلاعات آن متغیر می گردد.
پارامترهای ارسالی در سرویس ویرایش اطلاعات پروفایل در صورتی که توکن دارایscope نباشد Ignore می شوند.
ویرایش پروفایل با تایید پیامکی کاربر
با توجه به اینکه دسترسی کاربر به ویرایش اطلاعات خودش تنها از طریق پنل رسمی پاد امکانپذیر است، در صورت ضرورت ویرایش اطلاعات از طریق سرویس زیر انجام شود. این سرویس برایscope هایی که دسترسیread (و فقط read) برای آنها دریافت شده باشد قابل اعمال است.
فراخوانی این سرویس منجر به ارسال یک پیامک حاوی کد تایید با اعلام موارد تغییریافته می باشد.
کاربر می تواند کد پیامک شده را در همان پیامک پاسخ دهد، یا با ارائه آن به پذیرنده، از طریق سرویس زیر، تغییرات اطلاعات خود را تایید نماید:
نکته: دقت نمایید در هر دو سرویس ویرایش، مقدار nickName اجباری است، زیرا نمی تواند خالی شود. سایر فیلدها بر اساس سطح احراز هویت مشتری قابل ویرایشیا حذف و یا غیر قابل ویرایش خواهند بود.
خروج کاربر
در صورتی که کاربر می خواهد از SSO خارج شود او را به آدرس زیر هدایت نمایید:
https://accounts.pod.ir/oauth2/logout?
continue=
&client_id=
پارامترcontinue مشخص می کند که کاربر پس از خروج به چه صفحه ای هدایت شود و پارامتر client_id در صورت ارسال، کاربر را فقط از همان client خارج می کند.
دریافت client_secret و client_id
با توجه به اینکه برای صدا زدن سرویس های پلتفرم نیاز به توکن SSO جهت شناسایی کاربر و کنترل دسترسی می باشد برای کار با api ها نیاز به client_id و client_secret و api_token دارید. می توانید با ورود به پنل کسب و کار طبق راهنما، و ایجاد کلیدهای اتصال در پنل، آن ها را دریافت نماییدیا در صورت نیاز از طریقAPI زیر می توانید آن ها را فعالسازی و دریافت نمایید:
توجه داشته باشید که access_token که در هدر وارد می کنید توکن دسترسی شما بعد از لاگین با حساب کسب و کارتان در SSO می باشد که دسترسیclient:write را دریافت نموده و به مدت محدود اعتبار دارد.
دسترسیclient فقط به برخی کسب و کارها اعطا می شود.
پاسخ این درخواست در اولین بار شامل client_id و client_secret و api_token می باشد و client را برای حساب شما فعال می کند.
برای دریافت مجدد از متد GET همینapi استفاده نمایید با این تفاوت که در پاسخ، فقط client_id و client_secret را دریافت می نمایید.
پاسخ این سرویس به شکل زیر است:
ویرایش و جستجوی متادیتای کاربر
ویرایش متادیتا
اطلاعات کاربری شامل فیلدclient_metadata است که بدون اجازه کاربر (بدون داشتن توکن) هم قابل ویرایش است و مقدار آنها برای هر کسب و کار مجزا و اختصاصی است به همین دلیل ویرایش آنها نیاز به client_id و client_secret دارد.
با توجه به اینکه سرویس های زیر برای دریافت و ویرایشclient_metadata توکن کاربر را دریافت نمی کنند،
برای مشخص کردن کاربر بایدیکی از مشخصه هاییکتای کاربر شامل id، نام کاربری، تلفن و یا ایمیل کاربر را در آدرس قرار دهید.
پارامترIdentity: انتخاب کاربر که مقدارش بر اساس فیلد بعدی مشخص می شود.
پارامترidentityType: شامل یکی از مشخصه های [id,bpi_customer_number,username,phone_number,email,nationalcode] برای انتخاب کاربر می باشد.
client_metadata: اطلاعات مربوط به metadata کلاینت، در این پارامتر هر اطلاعات اضافه ای که برای کاربر نیاز به نگهداری دارید را در فرمت JSON می توانید ذخیره کنید. اطلاعات ذخیره شده در این فیلد به صورت محرمانه و فقط با ارسال client_id و client_secret ایجاد کننده و به روز رسانی شده قابل دسترسی می باشد و مابقی کاربران به اطلاعات آن دسترسی نخواهند داشت.
لازم به ذکر است پارامتر client_metadata فقط قابل ویرایش و خواندن توسط همان کسب و کار (که کاربر در آن لاگین شده) است. پیشنهاد می شود مقادیری که کسب و کار می خواهد در مورد کاربر به صورت خصوصی نگهداری کند تا در مراجعات بعدی از آن استفاده کند را در این پارامتر ذخیره کند.
برای دریافت این اطلاعات کافیست درخواست بالا را با متد GET ارسال نمایید.
جستجوی متادیتا
جهت جستجوی اطلاعاتی که در متادیتای کاربران ثبت نموده اید، کافی است با استفاده از metaQuery در سرویس زیر جستجو نمایید.
metaQuery :کوئری در فرمت جیسان که بر روی متادیتا ها اعمال می شود.به عنوان metQuery، بایدیک آبجکت json ارسال شود که مشخص میکند جست و جو بر روی کدام فیلد در متادیتا انجام شود و مقایسهی مقدار آن فیلد توسط چه عملگری انجام شود .
" نکته : مقدار پارامتر metaQuery می بایست به صورت اینکد شده ارسال گردد."
orderBy:پارامتری برای مرتب کردن صعودییا نزولی فیلد
لازم به ذکر است فرمت دریافتی قابل قبول برای پارامتر فوق به صورت [acs|:desc:]fieldName می باشد .
asc: مرتب سازی صعودی فیلد مورد نظر مثال: age:asc:number
desc: مرتب سازی نزولی فیلد مورد نظر مثال: age:desc:number
" نکته :ارسال مقدار پارامتر orderBy هم به صورت اینکد و هم دیکد امکان پذیر می باشد."
به عنوان metaQuery در درخواست بالا، بایدیک آبجکت json ارسال شود که مشخص می کند جستجو بر روی کدام field در متادیتا و همچنین مقایسه مقدار آن فیلد توسط چه عملگری انجام گردد.
metaQuery می تواند شامل ساختار زیر باشد:
عمگرهایis و has باید تنهایی استفاده شوند ولی عملگرهایlt / lte و gt / gte می توانند با یگدیگر برای مشخص کردن یک بازه عددی مورد استفاده قرار گیرند.
یک نمونه از metaQuery به شرح زیر می باشد :
مثال: فرض کنید به دو کاربر با اسامیuserA و userB با سرویس ویرایش اطلاعات کاربر، از طریق پارامتر client_metadata متادیتا مورد نظر تخصیص داده شود.
کد زیر برای ویرایش اطلاعات کاربر با نام userA ارسال گردید:
در صورت موفقیت آمیز بودن سرویس فوق statusCode 200 نمایش داده می شود در غیر این صورت پیام خطا برگردانده می شود.
کد زیر برای ویرایش اطلاعات کاربر با نام userB ارسال گردید:
در صورت موفقیت آمیز بودن سرویس فوق statusCode 200 نمایش داده می شود در غیر این صورت پیام خطا برگردانده می شود.
برای جست و جو کاربران با مشخصات job با مقدار tester به ترتیب سن به صورت صعودی از پارامتر orderBy به صورت دیکد شده همانند کد زیر استفاده کنید.
پاسخ دریافتی سرویس به شرح زیر می باشد :
برای جست و جو کاربران با مشخصات job با مقدار tester به ترتیب سن به صورت صعودی از پارامتر orderBy به صورت اینکد شده همانند کد زیر استفاده کنید.
پاسخ دریافتی سرویس به شرح زیر می باشد :
برای جست و جو کاربران به صورت آرایه ای و براساس user و city به صورت اینکد شده همانند کد زیر استفاده کنید.
پاسخ دریافتی سرویس به شرح زیر می باشد :
دریافت کلید خصوصی برای کاربر
از طریق سرویسhandshake شما می توانید اقدام به دریافتkeyId و privateKey از سرور پاد نمایید.
این کلید برای فراخوانی سرویس های کاربر محور، که نیاز به حصول اطمینان از هویت کاربر دارند استفاده می گردد.
پارامترkeyAlgorithm بر اساس نوع رمزنگاری که مد نظرتان هست مشخص می شود و هرکدام در خروجی نوع متفاوتی از کلیدها را بر می گرداند.
پارامترkeyFormat نوع فرمت کلید مورد نظر شما را مشخص می کند که می تواند xmlیاpem باشد.
پارامترvalidity زمان منقضی شدن کلید به صورت پیش فرض یک سال میباشد. ولی می توانید مقدار آن را با ارسال این پارامتر تعیین نمایید.
پارامترrenew چنانچه برابر با false باشد کلید قبلی کاربر نمایش داده می شود و چنانچه برابر با true باشد کلیدهای قبلی حذف و کلید جدید تولید خواهد شد .
پارامترkeySize نیز سایز کلید تولید شده می باشد که در واحد بیت میبایست ثبت گردد مثلا 1024 یا 2048 کیلوبیت
توجـــــــه : این سرویس تنها برای کاربران قابل استفاده هست و بایداکسس توکن کاربر برای دریافت کلید ارسال شود.
توجـــــــه : این سرویس برای تینگزها قابل استفاده نمی باشد.
نکته : لازم به ذکر است Authorization در این سرویس به صورت Access_Token ارسال می گردد.
توجه فرماییدprivatekey دریافتی از این سرویس بر اساس استاندارد PKCS8 می باشد.
نمونه پاسخ دریافت شده از سرویس فوق، به صورت زیر خواهد بود:
در صورت دریافت خطا به جدول زیر مراجعه نمایید:
errorCode دلیل خطا شرح
415 Unsupported Media Type پارامترها باید در بدنه درخواست و به صورت application/x-www-form-urlencoded ارسال بشوند
400 Bad Requestinvalid_device در این حالت توکن ارسالی شما احتمالا API توکن و یا توکن تینگز بوده است
ورود با دستگاه کش لس
برای ورود کاربران به SSO پاد با دستگاه کش لس از طریق مراحل زیر اقدام نمایید .
مرحله اول دریافت کد
از آدرس زیر برای دریافتcode استفاده کنید. مقدار client_id خود را در آن قرار دهید و آدرسی که می خواهید پاسخ درخواست را در آن دریافت کنید را به عنوان پارامتر redirect_uri ارسال نمایید. مقادیرclient_id و redirect_uri باید منطبق بر کلید اتصال تعریف شده توسط شما باشند.
فهرست کامل پارامترهای مورد نیاز درخواست به شرح زیر است:
client_id : شناسه کسب و کار مشتری می باشد .
" نکته: ارسال این پارامتر اجباری می باشد. "
response_type : نوع اطلاعات درخواستی برای دریافت می باشد. به عنوان مثال: code
redirect_uri: آدرس بازگشتی مورد نظر بابت دریافت کد وتوکن به عنوان مثال: http://google.com
prompt: عملیات مورد نیاز می باشد. مقادیر قابل ارسال برای پارامتر مذکور به شرح زیر می باشد:
login : در صورت ارسال پارامتر prompt با مقدار login صفحه ای جهت وارد کردن نام کاربری و پسورد به کاربر نمایش داده می شود.
otp_login : در صورت ارسال پارامتر prompt با مقدار otp_login صفحه ای جهت دریافت شماره همراه کاربر نمایش داده می شود.
qr_login: در صورت ارسال پارامتر prompt با مقدار qr_login، در ابتدا کاربر از طریق تلفن همراه CODE QR نمایش داده شده را اسکن می کند. سپس لینکی بر روی تلفن همراه کاربر نمایش داده می شود . در صورت فشار دادن لینک صفحه ی لاگین قابل مشاهده می باشد. در صورتی که کاربر قبلا لاگین انجام داده باشد بدون دریافت نام کاربری و کلمه ی عبور لاگین می کند در غیر این صورت نام کاربری و پسورد از کاربر دریافت سپس لاگین صورت می گیرد.
card_login: در ابتدا کارت بانکی در دستگاه کش لس توسط کاربر کشیده می شود. سپس دستگاه کش لس براساس شماره کارت کاربر ترکر (شماره 20 رقمی مختص همان کارت) تولید می کند. دستگاه کش لس شماره ی ترکر تولید شده را به عنوان مقدار پارامتر username قرار می دهد. در نهایت صفحه ای برای دریافت کلمه ی عبور به کاربر نمایش داده می شود.
scope: مقدار ارسالی برای این پارامتر، profileیا هر اسکوپ مورد نیاز می باشد.
بررسی عدم ارسال موارد فوق در آدرس به شرح زیر می باشد :
در صورت عدم ارسال client_id در آدرس فوق، با خطا زیر روبرو می شوید.
در صورت ارسال مقدار نادرست برای پارامتر client_id در آدرس فوق، با خطا زیر روبرو می شوید.
در صورت عدم ارسال پارامتر response_type در آدرس فوق، با خطا زیر روبرو می شوید.
[redirect_uri]/?error=parameter_absent&error_description=parameter%20absent
در صورت عدم ارسال پارامتر redirect_uri در آدرس فوق، به اولین آدرس بازگشتی ثبت شده در پنل کسب و کار کد ارسال می گردد.
در صورت ارسال مقدار نادرست برای پارامتر redirect_uri در آدرس فوق، با خطا زیر روبرو می شوید.
در صورت عدم دسترسی به اسکوپ های درخواستی خطا به شرح زیر در آدرس نمایش داده می شود.
[redirect_uri]/?error=unauthorized_client&error_description=Scope: مجاز نمیباشد.
در صورت ورود موفق کاربر، پاسخ این درخواست در آدرس بازگشت به شکل زیر است:
[redirect_uri]/?code=[code]&state=[state]
این کد در مدت کوتاهی منقضی می شود. بنابرین بلافاصله باید نسبت به دریافتaccess_token و refresh_token از طریق کد زیر اقدام نمایید.
مرحله دوم دریافت توکن دسترسی
برای دریافتaccess_token و refresh_token از طریق کد زیر اقدام نمایید.
توکن در این سرویس باید به صورت Basic Base64(Client_id:Client_secret) ارسال شود.
خروجی دریافتی از سرویس فوق به شرح زیر می باشد :
کد خطاهای رایج در سرویس فوق:
errorCode دلیل خطا شرح
400 Invalid or expired code کد ارسالی منقضی شده یا معتبر نمی باشد.
400 unsupported grant type مقدار grant_type ارسال شده پشتیبانی نمی شود.
401 Unauthorized توکن ارسالی نامعتبر است
نکته: پس از گذشت زمان expires_in ، توکن دسترسی کاربر منقضی می شود. (expires_in) ثانیه می باشد با استفاده از refresh_token توکن معتبر جدید درخواست دهید.
مدت زمان اعتبار اکسس توکن 15 دقیقه می باشد .
کد درخواست مجدد برای رفرش توکن به شرح زیر می باشد :
هنگام ارسال کد فوق، می بایست مقدار قبلی رفرش توکن در مرحله ی قبل را به عنوان مقدار برای پارامتر refresh_token قرار دهید.
کد خطاهای رایج در سرویس فوق:
errorCode دلیل خطا شرح
400 Invalid or expired code کد ارسالی منقضی شده یا معتبر نمی باشد.
400 unsupported grant type مقدار grant_type ارسال شده پشتیبانی نمی شود.
401 Unauthorized مشخصات کلاینت معتبر نمی باشد.
401 Unauthorized توکن ارسالی نامعتبر است
403 Forbidden دستگاه مسدود شده است.
ورود با دستگاه کش لس و کارت پاسارگادی
در این ویژگی لاگین کاربر در SSO پاد با استفاده از دستگاه کش لس و کارت پاسارگادی امکان پذیر می باشد.
مراحل لاگین به شرح زیر انجام میگردد:
در ابتدا کارت بانکی در دستگاه کش لس توسط کاربر کشیده می شود.
دستگاه کش لس براساس شماره کارت کاربر، ترکر (شماره 20 رقمی مختص همان کارت ) تولید می کند.
دستگاه کش لس شماره ی ترکر تولید شده را به عنوان مقدار پارامتر username و مقدارcard_login را به عنوان مقدار پارامتر prompt در URL زیر ارسال می کند.
بعد از ارسال URL فوق با پارامتر های مذکور، صفحه ی لاگینSSO پاد همانند تصویر زیر برای کاربر در صفحه نمایش دستگاه کش لس نمایش داده می شود.
همانطور که در تصویر فوق مشاهده می کنید در قسمت نام کاربری شماره ی ترکر تولید شده توسط دستگاه کش لس ثبت می باشد .
در این مرحله کاربر رمز کارت خود را به عنوان رمز عبور همانند تصویر زیر وارد می کند .
در صورتی که رمز عبور توسط کاربر اشتباه وارد گردد خطا همانند تصویر زیر نمایش داده می شود.
در صورتی که کاربر 3 بار پشت سر هم رمز عبور را اشتباه وارد کند خطا همانند تصویر زیر نمایش داده می شود.
بعد از گذشت مدت زمان 15 دقیقه امکان ورود مجددا رمز عبور وجود دارد .
پس از وارد کردن رمز عبور صحیح لاگین برای کاربر امکان پذیر می باشد. لازم به ذکر است پس از لاگین کاربر، صفحه ی مربوط به redirect_uri (آدرس بازگشتی مشخص شده در URL) نمایش داده می شود.
سایر امکانات
سامانهSSO پاد دارای ویژگی های خاص دیگری نیز هست که نیاز انواع سامانه های متصل را برآورده می سازد:
چند زبانی
در حال حاضر، دو زبان فارسی و انگلیسی در فرم های ثبت نام و ورود قابل مشاهده است.
ورود با مشخصه دلخواه
کاربر می تواند با هر کدام از مشخصه هاییکتای خود که در SSO ثبت نموده است وارد شود. در حال حاضر این امکان برای ورود با نام کاربری، ایمیل و یا شماره موبایل وجود دارد.
محدود سازی ورود روی IP
در صورتی که سامانه یا کسب و کار شما نیاز دارد فقط از IP های خاص مورد دسترس قرار گیرد،SSO برایclient (کلید اتصال) مورد نظر، لیست مجاز از IP ها دریافت می نماید. درصورتی که لیستی تعریف نشود محدودیتی برای ورود وجود ندارد. به این ترتیب اگر کاربر از یکIP بجز IP های تعریف شده بخواهد فرم ورود را مشاهده نماید، خطا دریافت می کند.
اطلاع رسانی ورود اشتباه
در صورتی که کاربر با یک نام کاربرییایک شماره موبایلیایک ایمیل، رمز ورود اشتباه وارد نماید، به صاحب نام کاربرییا شماره موبایلیا ایمیل، تلاش برای ورود با رمز اشتباه اطلاع داده می شود.
مقابله با حملات
در صورتی که یک حساب کاربری با یکی از مشخصه های خود بیش از 3 بار تلاش ناموفق برای ورود داشته باشد، آن مشخصه برای حساب کاربری به مدت زمان محدود قفل خواهد شد. در صورتی که کاربر سهواً رمز خود را اشتباه وارد نموده باشد، می تواند با استفاده از سایر مشخصه های ورود خود وارد شود یا رمز عبور خود را بازیابی نماید.