کیف پول بیستون
فارسی
دریافت منو

بیستون را با چند نقطهٔ اتصال به سایتتان اضافه کنید

یک ابزارک وب آماده، کد QR و دکمهٔ مخصوص گوشی را نمایش می‌دهد. سرور شما درخواست را امضا می‌کند و یک نتیجهٔ امضاشده و تأییدشده دریافت می‌کند. شما هرگز با اثبات‌ها یا کلیدهای کاربرانتان سروکار ندارید.

راهنمای توسعه‌دهندگان را بخوانیدنسخهٔ نمایشی را امتحان کنید

اجزا

کارت و مورد

کارت مجموعه‌ای امضاشده از موارد اطلاعاتی در کیف پول کاربر است. هر مورد شناسه‌ای دارد، مانند bisotun.main.app.pseudonym (شناسهٔ حساب).

درخواست‌کننده

سرور پشتیبان (back end) شما. با یک نام در بیستون ثبت می‌شود، همراه با کلید عمومی RSA شما (توصیه‌شده) یا یک رمز مشترک HMAC، و فقط برای موارد مشخصی مجوز می‌گیرد.

سرور نشست

https://cert.bisotun.app. هر درخواست را اجرا می‌کند، با کیف پول ارتباط برقرار می‌کند، اثبات را بررسی می‌کند و نتیجه را به شما برمی‌گرداند.

ابزارک

@bisotun/frontend، که در /sdk/bisotun.js ارائه می‌شود. کد QR، دکمهٔ «باز کردن کیف پول بیستون» روی گوشی و مرحلهٔ جفت‌سازی را نمایش می‌دهد؛ به فارسی، عربی و انگلیسی و با پشتیبانی از راست‌به‌چپ.

روند کار

  1. شروع

    مرورگر سرور پشتیبان شما را فرا می‌خواند. سرور پشتیبان یک درخواست ارائهٔ اطلاعات می‌سازد، آن را به شکل JWT امضا می‌کند و به https://cert.bisotun.app/session می‌فرستد.

  2. تحویل

    سرور نشست با یک اشاره‌گر نشست (session pointer)، یک توکن مخفی درخواست‌کننده و یک درخواست سمت کاربر (frontend request) پاسخ می‌دهد. توکن را روی سرور خود نگه می‌دارید و اشاره‌گر و درخواست سمت کاربر را به ابزارک برمی‌گردانید.

  3. تأیید کاربر

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

  4. نتیجه

    سرور نشست اثبات را بررسی می‌کند و نتیجه را، به شکل JWT امضاشده با کلید خودش، به callbackUrl شما روی HTTPS می‌فرستد.

  5. بررسی و ادامه

    سرور پشتیبان شما امضا را بررسی می‌کند، مطمئن می‌شود status برابر DONE، proofStatus برابر VALID و وضعیت هر مورد PRESENT است، و سپس کاربر را وارد می‌کند یا کار را ادامه می‌دهد.

مرورگر هرگز کلید شما یا توکن درخواست‌کننده را نمی‌بیند و نمی‌تواند آنچه درخواست شده را تغییر دهد.

در صفحهٔ شما

<section id="bisotun-form"></section>
<script src="https://wallet.bisotun.app/sdk/bisotun.js"></script>
<script>
  bisotun.newWeb({
    element: '#bisotun-form',
    language: 'fa',
    session: {
      url: '/api/bisotun',                  // YOUR back end
      start: { url: (o) => `${o.url}/start`, method: 'POST' },
      result: { url: (o, { sessionToken }) => `${o.url}/result/${sessionToken}` },
    },
  }).start()
    .then((result) => { /* logged in */ })
    .catch((endState) => { /* Cancelled, TimedOut, ... */ });
</script>

راهنمای توسعه‌دهندگان همهٔ گزینه‌ها را نشان می‌دهد؛ از جمله مسیر نقاط اتصال، نسخهٔ پنجرهٔ بازشو (popup)، تنظیم ظاهر و مدخل‌های لازم برای Content Security Policy. می‌توانید بستهٔ ابزارک و پوشهٔ fonts/ آن را از سایت خودتان هم ارائه کنید.

روی سرور شما

درخواست امضاشده، مواردی را که لازم دارید نام می‌برد:

{
  "iss": "your-requestor-name",
  "iat": 1790640000,
  "sub": "verification_request",
  "sprequest": {
    "callbackUrl": "https://your.site/api/bisotun/callback",
    "request": {
      "@context": "https://wallet.bisotun.app/ld/request/disclosure/v2",
      "disclose": [[["bisotun.main.app.pseudonym"]]]
    }
  }
}

disclose فهرستی از موارد الزامی است؛ هر کدام می‌تواند گزینه‌های جایگزین داشته باشد و هر گزینه می‌تواند چند مورد از یک کارت را با هم ترکیب کند. می‌توانید مقدار مشخصی را هم الزامی کنید. درخواست‌های قدیمی‌تر از ۵ دقیقه رد می‌شوند، پس ساعت سرورتان را همگام نگه دارید.

چه چیزهایی می‌توانید درخواست کنید

مورد وضعیت
bisotun.main.app.pseudonym — شناسهٔ حساب کیف پول؛ تصادفی و برای همهٔ سایت‌ها یکسان در دسترس
bisotun.main.email.address — نشانی ایمیلی که بیستون تأیید کرده است به‌زودی
موارد کارت‌هایی که سازمان‌های دیگر صادر می‌کنند پس از پیوستن آن صادرکننده‌ها

دریافت دسترسی

  1. درخواست ثبت بدهید

    به support@bisotun.app بنویسید. سایت خود و مواردی را که لازم دارید به ما بگویید.

  2. مشخصاتتان را دریافت کنید

    نام درخواست‌کنندهٔ شما، مجوز برای موارد توافق‌شده و کلید عمومی سرور نشست برای بررسی نتیجه‌ها. کلید عمومی RSA خود را برای ما بفرستید یا یک کلید HMAC دریافت کنید.

  3. بسازید و آزمایش کنید

    از راهنمای توسعه‌دهندگان با نمونه‌های کامل Node.js و Python پیروی کنید و کارتان را با نسخهٔ نمایشی مقایسه کنید؛ سناریوی اصلی آن دقیقاً همین ورود بدون رمز عبور با شناسهٔ حساب است.

فهرست بررسی امنیتی

  • درخواست‌ها را فقط روی سرور خود بسازید و امضا کنید. هرگز کلید یا توکن درخواست‌کننده را به مرورگر نفرستید.
  • نتیجه را فقط وقتی بپذیرید که امضا، status، proofStatus و وضعیت همهٔ موارد درست باشد.
  • هر نتیجه را فقط یک بار به کار ببرید. برای نشانی callback از HTTPS استفاده کنید.
  • کمترین تعداد موردی را بخواهید که کارتان را راه می‌اندازد. کاربران دقیقاً می‌بینند چه چیزی درخواست کرده‌اید.
  • از کلیدتان مانند یک رمز عبور محافظت کنید؛ اگر احتمال درز آن وجود دارد، فوراً از طریق security@bisotun.app به ما خبر دهید.

هنوز ارائه نمی‌شود

هر آنچه لازم دارید در راهنما آمده است.

راهنمای توسعه‌دهندگاندانلود ابزارک