☰ فهرست مستندات · SDK مدیریتی Node.js (سرور)
SDK مدیریتی (سرور)
ابرووا احراز هویت برای سرور شما، با همان نام‌های Firebase Admin SDK: setCustomUserClaims، getUser و revokeRefreshTokens. بسته‌ی @abrova/auth-admin برای Node.js، یا همان فراخوانی‌ها به صورت درخواست ساده‌ی HTTPS از هر زبانی.
SDK مدیریتی کاربران اپ شما را از سرور خودتان مدیریت می‌کند: claimهای سفارشی، اطلاعات حساب و نشست‌هایشان. از کلید سرور پروژه استفاده می‌کند، پس هیچ‌وقت در اپ یا مرورگر اجرا نمی‌شود. اپ‌ها کاربران را با SDKهای ابرووا احراز هویت وارد می‌کنند.
مرحله ۱: نصب#
بسته از مرکز ابرووا می‌آید. اسکوپ @abrova را در فایل .npmrc پروژه به رجیستری ابرووا وصل کنید:
@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/
npm install @abrova/auth-admin
Node.js نسخه‌ی ۱۸ یا بالاتر لازم است و وابستگی دیگری ندارد.
مرحله ۲: راه‌اندازی#
سه متغیر محیطی روی سرورتان بگذارید. آن‌ها را در کنسول، بخش تنظیمات پروژه، پیدا می‌کنید:
| متغیر | مقدار |
|---|---|
| ABROVA_PROJECT_ID | شناسه‌ی پروژه. |
| ABROVA_API_KEY | کلید عمومی API (ab_live_...). |
| ABROVA_SERVER_SECRET | کلید سرور (ab_srv_...). فقط روی سرور. |
import { initAdmin } from '@abrova/auth-admin';
const auth = initAdmin();می‌توانید آن‌ها را در کد هم بدهید: initAdmin({ projectId, apiKey, serverSecret }).
setCustomUserClaims#
همه‌ی claimهای سفارشی کاربر را جایگزین می‌کند. null یا {} آن‌ها را پاک می‌کند. برای این‌که claim چه چیزی می‌تواند داشته باشد claimهای سفارشی را ببینید.
await auth.setCustomUserClaims(userId, { plan: 'pro', teams: ['red'] });getUser#
کاربر را با همان نام‌های UserRecord در Firebase برمی‌گرداند:
const user = await auth.getUser(userId);
| فیلد | چیست |
|---|---|
| uid | شناسه‌ی کاربر (ru_...). |
| email، emailVerified | ایمیل، اگر کاربر داشته باشد، و این‌که تأیید شده یا نه. |
| phoneNumber | شماره تلفن ورود با تلگرام، یا null. |
| displayName | نام از ورود با Apple یا Google، یا null. |
| disabled | وقتی کاربر در کنسول غیرفعال شده true است. |
| providerData | روش‌های ورود وصل‌شده، مثلاً [{ providerId: "google" }]. برای کاربر ناشناس خالی است. |
| metadata | creationTime، lastSignInTime و lastRefreshTime (آخرین تمدید نشست). |
| customClaims | claimهای سفارشی؛ وقتی نباشد {} است. |
| tokensValidAfterTime | آخرین باری که همه‌ی نشست‌های کاربر تمام شد، یا null. |
| anonymous | برای کاربر ناشناس true است. |
revokeRefreshTokens#
همه‌ی نشست‌های کاربر را روی همه‌ی دستگاه‌ها تمام می‌کند: دیگر هیچ تمدیدی کار نمی‌کند و کاربر باید دوباره وارد شود. access tokenهایی که قبلاً صادر شده‌اند تا انقضا، حداکثر یک ساعت بعد، کار می‌کنند.
await auth.revokeRefreshTokens(userId);
خطاها#
هر خطا یک AbrovaAuthAdminError با code و status (کد HTTP) است:
| کد | HTTP | معنا |
|---|---|---|
| INVALID_CLAIMS | 400 | claimها یک قاعده را رعایت نمی‌کنند. پیام اولین مشکل را می‌گوید، مثلاً "claims.sub: not an allowed name". |
| USER_NOT_FOUND | 404 | چنین کاربری در این پروژه نیست. |
| UNAUTHENTICATED | 401 | کلید API یا کلید سرور اشتباه است، کلید پروژه‌ی دیگری است، یا آدرسی است که فهرست IPهای مجاز پروژه اجازه نمی‌دهد. |
| RATE_LIMITED | 429 | در یک دقیقه درخواست زیادی فرستاده شده. صبر کنید و دوباره امتحان کنید. |
| NETWORK | - | ابرووا احراز هویت در دسترس نبود. |
بدون Node.js: REST API#
هر فراخوانی یک درخواست HTTPS به https://auth-users.abrova.ir با دو هدر x-api-key و x-server-secret است:
| فراخوانی | درخواست |
|---|---|
| setCustomUserClaims | PUT /v1/projects/{projectId}/users/{userId}/custom-claims با بدنه‌ی { "claims": { ... } } |
| getUser | GET /v1/projects/{projectId}/users/{userId} |
| revokeRefreshTokens | POST /v1/projects/{projectId}/users/{userId}/revoke-refresh-tokens |
// PHP (Laravel)
Http::withHeaders([
'x-api-key' => env('ABROVA_API_KEY'),
'x-server-secret' => env('ABROVA_SERVER_SECRET'),
])->put("https://auth-users.abrova.ir/v1/projects/{$projectId}/users/{$userId}/custom-claims", [
'claims' => ['plan' => 'pro'],
]);خطاها به صورت JSON با همان code و یک message برمی‌گردند.
به‌روزرسانی: ۱۴ آبان ۱۴۰۵