انجام عملیات بانکی سریع و امن
اضافه شدن خدمات پرتقاضا به نرمافزار
حفاظت از حریم خصوصی کاربران
افتتاح حساب هوشمند، بدون مراجعه به شعبه
صرفهجویی در زمان با حذف اطلاعات غیر ضروری
OAuth چیست؟ توکن دسترسی برای فراخوانی API بانکی
OAuth چیست؟ پروتکل صدور دسترسی زماندار است، نه خود داده بانکی. سرور شما یک توکن دسترسی میگیرد و فقط با همان توکن API را صدا می‌زند. توکن مشخص میکند کدام کار مجاز است و تا کی اعتبار دارد. در فینوتک دو مسیر رایج است: Client Credential برای فراخوانی سمت سرور، و توکن پیامکی وقتی داده متعلق به خود شخص است.
OAuth چیست؟
OAuth 2.0 روش گرفتن اجازه دسترسی است. خروجی آن یک access token است: رشته‌ای زماندار که در فراخوانی‌های بعدی فرستاده میشود. همراه توکن، اسکوپهای مجاز، زمان ساخت، عمر توکن و یک رفرش توکن برمی‌گردد تا چرخه اعتبار سمت سرور مدیریت شود.
رمز کلاینت و خود توکن در اپلیکیشن موبایل یا مرورگر جا نمی‌گیرند. هر دو سمت سرور میمانند. توکن، احراز هویت مشتری هم نیست؛ فقط کلید فراخوانی API در محدوده همان اسکوپ است.
توکن دسترسی چه فرقی با رمز ثابت دارد؟
رمز ثابت یک اعتبار مشترک بین سامانه‌هاست. دامنه هر بخش جدا معلوم نیست، بستن یک سرویس اغلب بقیه را هم قطع میکند، و بعداً سخت است بگویید کدام بخش چه فراخوانی داشته. توکن دسترسی همان اجازه را محدود میکند: فقط اسکوپهای درخواست‌شده، فقط تا پایان عمر، و بدون پخش کردن رمز کلاینت.
اگر توکن لو برود، عمرش کوتاه است و اسکوپش از کل دسترسی کلاینت کوچک‌تر است. تمدید هم با رفرش توکن انجام میشود، نه با دادن دوباره رمز به هر سامانه.
کدام مسیر توکن را انتخاب کنید؟
مسیر را از روی مالک داده انتخاب کنید، نه از روی نام سرویس. اگر فراخوانی به منابع خود کلاینت مربوط است و اجازه کاربر بیرونی لازم نیست، Client Credential کافی است. اگر داده یا حساب متعلق به شخص است، توکن پیامکی لازم است و مرحله اول آن به‌تنهایی توکن نمی‌دهد.
| پرسش | Client Credential | توکن پیامکی |
|---|---|---|
| اجازه کاربر بیرونی | لازم نیست | لازم است |
| داده مربوط به کیست؟ | منابع خود کلاینت | داده یا حساب شخص |
| تا رسیدن به توکن | یک صدور | سه مرحله |
| خروجی گام اول | access token و رفرش توکن | شناسه پیگیری، نه توکن |
| تمدید | با رفرش توکن | با رفرش توکن، بدون پیامک تازه |
| توکن را کجا نگه دارید؟ | سمت سرور | سمت سرور |
Client Credential چه زمانی کافی است؟
برای استعلام‌هایی که به منابع خود کلاینت مربوط‌اند: بخش زیادی از ثبت‌نام، کارهای زمان‌بندی‌شده، و فراخوانی‌هایی که رضایت جداگانه شخص نمی‌خواهند. سرور با اطلاعات کلاینت توکن میگیرد.
در فینوتک این مسیر گرفتن توکن Client Credential است. برای خود این سرویس اسکوپ جدا لازم نیست. اسکوپ سرویس‌هایی را میفرستید که میخواهید با همان توکن صدا بزنید. اسکوپها با کاما جدا می‌شوند و باید از قبل روی کلاینت فعال شده باشند. اسکوپ غیرفعال داخل توکن صادرشده نمیآید. کد ملی داخل درخواست باید ۱۰ رقمی و متعلق به فراخواننده‌ای باشد که به کلاینت دسترسی دارد.
ترتیب کار:
- کلاینت بسازید و فقط اسکوپ سرویس‌های لازم را فعال کنید.
- اطلاعات کلاینت، کد ملی فراخواننده و فهرست اسکوپها را بفرستید.
- توکن، اسکوپهای مجاز، زمان ساخت، عمر توکن و رفرش توکن را سمت سرور ذخیره کنید.
- پیش از پایان عمر، توکن را تمدید کنید.
عمر توکن به میلی‌ثانیه و زمان ساخت آن به تاریخ شمسی برمی‌گردد. منطق انقضا را روی همین دو مقدار بگذارید.
توکن پیامکی چه زمانی لازم است؟
وقتی سرویس به داده یا حساب خود شخص گره خورده است. سابقه اعتباری شخص، یا فراخوانی‌ای که باید به حساب او محدود شود، از این مسیر می‌رود. رضایت کاغذی اینجا به یک تایید پیامکی قابل پیگیری تبدیل میشود.
- درخواست احراز هویت شماره موبایل و اسکوپها را میگیرد، پیامک درخواست دسترسی میفرستد و شناسه پیگیری برمی‌گرداند. این مرحله توکن نیست.
- تایید احراز هویت کد یکبار مصرف کاربر را با همان شناسه پیگیری ثبت میکند.
- درخواست توکن access token، اسکوپهای مجاز و رفرش توکن را برمی‌گرداند.
اسکوپ این مسیر باید از نوع پیامکی باشد. اسکوپ دستههای متفاوت را در یک درخواست با هم نفرستید؛ برای دسته دیگر جریان را جدا اجرا کنید. دامنه آدرس بازگشتی باید با دامنه ثبت‌شده کلاینت یکی باشد، و همان آدرس باید در مرحله درخواست توکن عیناً تکرار شود.
اسکوپ در OAuth یعنی چه؟
اسکوپ محدوده مجاز همان توکن است. کلاینت به کل API دسترسی پیدا نمی‌کند؛ فقط به سرویس‌هایی که در صدور توکن اعلام شده و روی کلاینت فعال بوده‌اند. صفحه هر سرویس اسکوپ خودش را نوشته است. اسکوپی که روی کلاینت فعال نباشد، حتی اگر در درخواست بیاید، داخل توکن صادرشده قرار نمی‌گیرد.
دسته OAuth و توکن صدور و تمدید همین توکن است. داده کسبوکاری — هویت، چک، خودرو، حساب — بعد از داشتن توکن، از دسته همان سرویس خوانده میشود.
تمدید توکن چگونه انجام میشود؟
عمر توکن عمداً کوتاه است تا دسترسی دائمی نماند. اگر وسط کار دسته‌ای یا پرونده چندروزه منقضی شود، فراخوانی‌ها خطا می‌دهند. در جریان پیامکی، صدور دوباره یعنی درخواست کد تازه از کاربر. تمدید این تکرار را حذف میکند و همان اسکوپهای قبلی را روی توکن تازه نگه می‌دارد.
تمدید توکن رفرش توکن ذخیره‌شده را میگیرد و access token تازه، همان اسکوپها، عمر جدید و یک رفرش توکن نو برمی‌گرداند. این سرویس برای نوع Client Credential و نوع Code کار میکند و تایید پیامکی تازه نمی‌خواهد. مقدار قبلی را با پاسخ جدید عوض کنید. اسکوپ تازه درخواست نمی‌شود؛ اسکوپ توکن جدید همان اسکوپ توکن قبلی است.
رمز یکبار مصرف همان توکن OAuth است؟
نه. رمز یکبار مصرف ورود به محصول شما فقط نشان میدهد کسی به آن سیمکارت دسترسی دارد و برای نشست خود محصول است. توکن OAuth اجازه فراخوانی API در محدوده اسکوپ است. این دو کد یکی نیستند. تولید و صحت‌سنجی رمز ورود در دسته پیامک و رمز یکبار مصرف است.
توکن پیامکی OAuth چیز دیگری است: رضایت شخص برای اسکوپهای فینوتک، و خروجی‌اش access token است. کد ورود به اپ را بهجای این جریان نگذارید. تعلق سیمکارت به کد ملی هم کار این توکن نیست.
اگر خود معنای فراخوانی هنوز جدا از دسترسی است، مقاله API چیست همان پرسش را جواب میدهد و این صفحه را تکرار نمی‌کند.
پیاده‌سازی را از کجا شروع کنید؟
اول کلاینت بسازید و اسکوپ واقعی محصول را روی آن فعال کنید. بعد، بسته به مالک داده، یا توکن Client Credential بگیرید یا جریان سه‌مرحله‌ای پیامکی را تا توکن کامل کنید. ساخت کلاینت و تفاوت دو جریان در راهنمای توکن است. قرارداد هر مرحله — ورودی، خروجی، نمونه پاسخ — در مستندات فنی همان سرویس است، نه در این مقاله.
سوالات متداول
OAuth چیست؟
OAuth پروتکل صدور اجازه دسترسی است. خروجی آن یک توکن زماندار است که سرور بهجای رمز ثابت در فراخوانی API میفرستد. توکن مشخص میکند کدام اسکوپ مجاز است و تا کی اعتبار دارد. اطلاعات بانکی داخل خود توکن نیست. یا با اطلاعات کلاینت برای کار سمت سرور صادر میشود، یا پس از تایید پیامکی، وقتی داده متعلق به شخص است.
تفاوت Client Credential و توکن پیامکی چیست؟
Client Credential برای منابع خود کلاینت است و حضور کاربر لازم نیست؛ یک فراخوانی توکن، اسکوپها و رفرش توکن را برمی‌گرداند. توکن پیامکی وقتی لازم است که داده یا حساب متعلق به شخص باشد. آنجا اول پیامک درخواست دسترسی می‌رود و شناسه پیگیری می‌آید، بعد کد کاربر تایید میشود، و تازه در مرحله سوم توکن صادر میشود.
برای هر فراخوانی باید توکن جدید گرفت؟
نه. توکن تا پایان عمرش برای اسکوپهای مجاز قابل استفاده است. پیش از انقضا آن را با رفرش توکن تمدید کنید تا صدور اولیه از نو تکرار نشود. در نوع پیامکی، تمدید به کد جدید کاربر نیاز ندارد. عمر را از مقدار میلیثانیهای که همراه توکن آمده حساب کنید، نه با حدس یک مدت ثابت.
اسکوپ را از کجا بردارم؟
از صفحه همان سرویسی که میخواهید صدا بزنید، و از اسکوپهایی که روی کلاینت شما فعال شدهاند. در Client Credential همان فهرست را با کاما داخل درخواست توکن میفرستید. در مسیر پیامکی فقط اسکوپ نوع پیامکی پذیرفته میشود و اسکوپ دستههای متفاوت با هم جمع نمیشوند. اسکوپ غیرفعال روی کلاینت داخل توکن نمیآید.
توکن را در اپلیکیشن موبایل ذخیره کنم؟
خیر. اطلاعات کلاینت، access token و رفرش توکن سمت سرور میمانند. اپلیکیشن فقط نتیجه کسبوکاری را میبیند، نه خود اعتبار دسترسی. اگر توکن در کد سمت کاربر یا در مخزن کد باشد، هر کسی که به آن فایل برسد تا پایان عمر توکن همان اسکوپها را دارد. تمدید و صدور را هم از سرور انجام دهید.
رمز یکبار مصرف ورود جای توکن OAuth را میگیرد؟
خیر. رمز یکبار مصرف فقط دسترسی کسی به سیمکارت را برای ورود یا تایید نشست محصول نشان میدهد. توکن OAuth اجازه فراخوانی API در محدوده اسکوپ است. تایید پیامکی جریان توکن، رضایت دسترسی به داده است و با کد ورود به اپ یکی نیست. هر دو وقتی لازماند که محصول هم ورود کاربر بخواهد و هم API را صدا بزند.