پرش به مطلب اصلی

گرفتن یک توکن دسترسی

هدف​

گرفتن یک توکن دسترسی OAuth2 از Parsware Identity Service تا بتوانید در حین توسعه API‌های پلتفرم را فراخوانی کنید.

پیش‌نیازها​

  • Identity Service در حال اجرا و در دسترس باشد (در توسعهٔ محلی روی http://localhost:5000 گوش می‌دهد).
  • دادهٔ اولیهٔ توسعه ساخته شده باشد (این داده در نخستین راه‌اندازی به‌طور خودکار ساخته می‌شود): یک مستأجر توسعه و یک حساب مدیر (admin@parsware.local).
  • یک کلاینت REST مانند curl.

گام‌ها​

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

    curl -X POST http://localhost:5000/connect/token \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d "grant_type=password" \
      -d "username=admin@parsware.local" \
      -d "password=Passw0rd!" \
      -d "scope=profile roles parsware.api offline_access" \
      -d "client_id=parsware-dev-cli" \
      -d "client_secret=dev-cli-secret"

  2. مقدار access_token را از پاسخ JSON بخوانید. پاسخ همچنین شامل یک refresh_token (چون offline_access درخواست شده بود) و یک مقدار expires_in بر حسب ثانیه است.

  3. یک API را با توکن در سرآیند Authorization فراخوانی کنید. برای اطمینان از کار کردن توکن، نقطهٔ پایانی userinfo را فراخوانی کنید:

    curl http://localhost:5000/connect/userinfo \
      -H "Authorization: Bearer <access_token>"

    پاسخ کاربر واردشده را معرفی می‌کند (subject، نام، ایمیل، مستأجر).

پشت صحنه چه می‌گذرد​

Identity Service گذرواژهٔ مدیر را وارسی می‌کند و سپس یک توکن دسترسی JWT امضاشده صادر می‌کند. این توکن امضا می‌شود (نه رمزنگاری)، بنابراین هر سرویس پلتفرم آن را مستقیماً با کلیدهای امضای منتشرشدهٔ Identity Service اعتبارسنجی می‌کند — در هر درخواست هیچ فراخوانی برگشتی به Identity Service وجود ندارد.

رفع اشکال​

  • invalid_grant — نام کاربری یا گذرواژه نادرست است، یا حساب پس از چند شکست پیاپی قفل شده است. کمی صبر و دوباره تلاش کنید، یا گذرواژه را بازنشانی کنید.

  • invalid_client — مقدار client_id/client_secret با هیچ کلاینت ثبت‌شده‌ای همخوانی ندارد. در محیط توسعه از parsware-dev-cli / dev-cli-secret استفاده کنید.

  • invalid_scope — یکی از اسکوپ‌های درخواست‌شده برای این کلاینت مجاز نیست. تنها profile، roles، offline_access و parsware.api را درخواست کنید.

  • Connection refused — Identity Service در حال اجرا نیست یا روی درگاه دیگری است.

  • توکن فقط mfa.enrol را حمل می‌کند (aud آن parsware-mfa-enrolment است) — حساب، حساب کارکنان است و هنوز برنامهٔ احراز هویت ندارد. احراز هویت دومرحله‌ای برای کارکنان اجباری است: یکی ثبت کنید (از پروفایل، یا POST /connect/mfa/enrolment با همین توکن)، سپس دوباره با -d "mfa_code=<شش رقم>" درخواست کنید. روی یک استقرار، مدیر همان کسی است که PLATFORM_ADMIN_EMAIL استقرار نام می‌برد، نه admin@parsware.local.

سناریوهای مرتبط​

  • بازبینی کلیدهای JWKS که Identity Service منتشر می‌کند.

اعطای password که در اینجا نشان داده شد یک تسهیل توسعه برای گرفتن توکن از خط فرمان است. ورود تعاملی واقعی از جریان authorization code همراه با PKCE از طریق Platform Shell استفاده می‌کند.