Auth Push آزمایشی — راهنمای توسعه و اتصال

هر بخش از سیستم چه کاری انجام می‌دهد؟

برای ساده‌ماندن پیاده‌سازی، کارها را میان مرورگر، SDK پوشفا و سرور سایت جدا کنید. مرورگر فقط رابط ورود را نشان می‌دهد. SDK وضعیت درخواست را بررسی می‌کند. سرور سایت کاربر را می‌شناسد و تصمیم نهایی ورود را می‌گیرد.

چند واژه فنی به زبان ساده

۱. گرفتن شناسه دستگاه در مرورگر

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

// این کد فقط بعد از ورود معتبر کاربر اجرا شود.
await window.Pushfa.requestPermission();
const subscriberId = await window.Pushfa.Auth.prepare();

await fetch('/account/trusted-device', {
  method: 'POST',
  credentials: 'same-origin',
  headers: {
    'Content-Type': 'application/json',
    'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]').content
  },
  body: JSON.stringify({ subscriber_id: subscriberId })
});

مسیرهای داخلی مورد نیاز در سایت شما

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

۴. انتظار برای تأیید روی دستگاه دیگر

مرورگر شناسه درخواست، توکن کوتاه‌مدت و زمان پایان را از سرور سایت می‌گیرد. SDK هر چند ثانیه وضعیت را بررسی می‌کند. اگر کاربر درخواست را تأیید کند، یک مجوز یک‌بارمصرف به نام Grant برگردانده می‌شود تا سرور ورود را کامل کند.

async function startAuthPushLogin() {
  const requesterSubscriberId = await window.Pushfa.Auth.prepare();
  const startResponse = await fetch('/auth/push/start', {
    method: 'POST',
    credentials: 'same-origin',
    headers: {
      'Content-Type': 'application/json',
      'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]').content
    },
    body: JSON.stringify({
      username: document.querySelector('#username').value,
      subscriber_id: requesterSubscriberId,
      mode: 'approval'
    })
  });

  if (startResponse.status === 422) {
    return fallbackToSms(null);
  }

  const challenge = await startResponse.json();
  const result = await window.Pushfa.Auth.wait({
    challengeId: challenge.challenge_id,
    clientToken: challenge.client_token,
    expiresAt: challenge.expires_at,
    interval: 2000
  });

  if (result.status === 'approved' && result.grant) {
    return completeLogin(challenge.challenge_id, result.grant);
  }

  return fallbackToSms(challenge);
}

۵. بررسی کد شش‌رقمی Push

در روش otp، یک کد شش‌رقمی در اعلان دستگاه مورد اعتماد نمایش داده می‌شود. کاربر کد را در صفحه ورود جدید وارد می‌کند. اگر کد درست باشد، SDK همان مجوز یک‌بارمصرف لازم برای تکمیل ورود را برمی‌گرداند.

const challenge = await startPushChallenge({ mode: 'otp' });

try {
  const result = await window.Pushfa.Auth.verifyOtp({
    challengeId: challenge.challenge_id,
    clientToken: challenge.client_token
  }, document.querySelector('#push-otp').value);

  if (result.status === 'approved' && result.grant) {
    await completeLogin(challenge.challenge_id, result.grant);
  }
} catch (error) {
  // کد نادرست، Challenge بسته یا تعداد تلاش تمام شده است.
  showOtpError(error.message);
}

وضعیت‌های Challenge

رفتن به روش پیامک و لغو درخواست قبلی

وقتی کاربر منتظر تأیید است، دکمه «ورود با پیامک» را در دسترس نگه دارید. پیش از ارسال پیامک، درخواست Push را با Pushfa.Auth.cancel لغو کنید تا تأیید دیرهنگام باعث ورود هم‌زمان و ناخواسته نشود.

async function fallbackToSms(challenge) {
  if (challenge) {
    try {
      await window.Pushfa.Auth.cancel({
        challengeId: challenge.challenge_id,
        clientToken: challenge.client_token
      });
    } catch (_) {
      // Challenge ممکن است هم‌زمان منقضی یا بسته شده باشد.
    }
  }

  return fetch('/auth/sms/start', { method: 'POST', credentials: 'same-origin' });
}

نکات پیاده‌سازی رابط ورود