claimهای سفارشی (custom claims)

چطور کار می‌کند#

1. سرور شما claimها را برای کاربر می‌گذارد، با کلید سرور پروژه: setCustomUserClaims(userId, { plan: 'pro' }).
2. هر توکن تازه‌ی آن کاربر آن‌ها را دارد، در سطح اول توکن کنار sub و exp. کاربر توکن تازه را در ورود یا تمدید بعدی می‌گیرد (حداکثر تا یک ساعت)، یا همان لحظه وقتی اپ توکن تازه بخواهد.
3. قوانین امنیتی Sync آن‌ها را می‌خوانند، به شکل auth.token.plan، و اپ آن‌ها را می‌خواند با getTokenResult() تا صفحه‌ی درست را نشان دهد.

این‌که کاربر چطور پرداخت کرده یا چرا کارمند است کار خود شماست: ابرووا فقط نتیجه را می‌برد.

مرحله ۱: گذاشتن claimها روی سرور#

با SDK مدیریتی برای Node.js:

import { initAdmin } from '@abrova/auth-admin';

const auth = initAdmin(); // ABROVA_PROJECT_ID، ABROVA_API_KEY و ABROVA_SERVER_SECRET را می‌خواند

// بعد از این‌که سرور شما پرداخت را تأیید کرد:
await auth.setCustomUserClaims(userId, { plan: 'pro', levels: ['L1', 'L2'] });

یا با هر زبانی، با یک درخواست HTTPS:

curl -X PUT "https://auth-users.abrova.ir/v1/projects/$PROJECT_ID/users/$USER_ID/custom-claims" \
  -H "x-api-key: $ABROVA_API_KEY" \
  -H "x-server-secret: $ABROVA_SERVER_SECRET" \
  -H "content-type: application/json" \
  -d '{"claims": {"plan": "pro", "levels": ["L1", "L2"]}}'

userId شناسه‌ی کاربر ابرووا احراز هویت است (ru_...)، همان که اپ بعد از ورود می‌گیرد.

گذاشتن claimها جایگزین می‌کند#

هر فراخوانی همه‌ی claimهای کاربر را جایگزین می‌کند، مثل Firebase. برای اضافه کردن یک claim و نگه داشتن بقیه، اول آن‌ها را بخوانید:

const user = await auth.getUser(userId);
await auth.setCustomUserClaims(userId, { ...user.customClaims, beta: true });

برای پاک کردن همه‌ی claimها null (یا {}) بفرستید:

await auth.setCustomUserClaims(userId, null);

مرحله ۲: استفاده در قوانین امنیتی#

قوانین Sync هر claim را به شکل auth.token.<name> می‌خوانند، مقدارهای تودرتو هم. claim متنی با نام role به شکل auth.role هم در دسترس است:

{
  "rules": {
    "lessons": {
      "$id": {
        ".read": "auth.token.plan === 'pro' || data.free === true"
      }
    },
    "teams": {
      "$team": {
        ".write": "auth.token.teams.includes($team) && auth.token.team.role === 'editor'"
      }
    }
  }
}

کاربری که آن claim را ندارد از بررسی نمی‌گذرد. قوانین امنیتی Sync را ببینید.

مرحله ۳: خواندن در اپ#

getTokenResult() توکن را با فیلدهای بازشده‌اش برمی‌گرداند، مثل getIdTokenResult() در Firebase. با آن صفحه‌ی درست را نشان دهید (نشان «Pro»، درس‌های بازشده). از نسخه‌ی 0.2.0 SDKهای ابرووا احراز هویت:

// Web، React Native
const result = await auth.getTokenResult();
if (result?.claims.plan === 'pro') showProBadge();

// Flutter
final result = await auth.getTokenResult();
if (result?.claims['plan'] == 'pro') showProBadge();

// iOS
let result = try await AbrovaAuth.shared.getTokenResult()
if result?.claims["plan"] as? String == "pro" { showProBadge() }

// Android
val result = AbrovaAuth.shared.getTokenResult()
if (result?.claims?.get("plan") == "pro") showProBadge()

گرفتن claimهای تازه همان لحظه#

claim تغییرکرده با توکن بعدی به اپ می‌رسد، حداکثر تا یک ساعت. برای گرفتن آن همان لحظه، مثلاً با دکمه‌ی «بررسی خرید من» یا وقتی اپ باز می‌شود، توکن تازه بخواهید:

await auth.getTokenResult({ forceRefresh: true });

بعد به ابرووا سینک بگویید از آن استفاده کند: sync.refreshUserToken().

claim چه چیزی می‌تواند داشته باشد#

درخواست ردشده با 400 INVALID_CLAIMS و اولین مشکل جواب می‌گیرد و چیزی عوض نمی‌شود.

خوب است بدانید#

• در همه‌ی طرح‌ها. claimها هزینه‌ی اضافه ندارند: کاربری که claim دارد هنوز یک کاربر فعال ماهانه است.
• نشست‌ها می‌مانند. تغییر claimها هیچ‌وقت کاربر را خارج نمی‌کند. برای قطع دسترسی کاربر از revokeRefreshTokens استفاده کنید یا کاربر را در کنسول غیرفعال کنید.
• کاربران ناشناس هم می‌توانند claim داشته باشند و وقتی به حساب کامل ارتقا پیدا می‌کنند آن‌ها را نگه می‌دارند.
• شنونده‌های باز Sync claimهای قبلی را نگه می‌دارند تا وقتی تمدید شوند، حداکثر ۲۴ ساعت. برای محتوای پولی که کاربر ممکن است از دست بدهد، claim را در یک خواندن معمولی هم بررسی کنید، یا وقتی سرور شما claim را برمی‌دارد شنونده را در اپ ببندید.
• در کنسول، بخش ابرووا احراز هویت › کاربران کاربرانی را که claim دارند علامت می‌زند و claimها را فقط‌خواندنی نشان می‌دهد. هر تغییر در فعالیت‌ها با عنوان «ادعاهای سفارشی تغییر کرد» و بدون مقدارها دیده می‌شود.
• توکن‌هایی که سرور خودتان می‌سازد (POST /users/token با claims) همین قاعده‌ها را دارند و claimها را در همان جای توکن می‌گذارند، پس قوانین آن‌ها را به همان شکل می‌خوانند.