استفاده از توکن های OAuth شخص ثالث

شما در حال مشاهده مستندات Apigee Edge هستید.
به مستندات Apigee X مراجعه کنید . اطلاعات

در این مبحث، ما در مورد نحوه وارد کردن توکن‌های دسترسی تولید شده خارجی، توکن‌های تازه‌سازی یا کدهای احراز هویت به مخزن توکن Edge بحث خواهیم کرد. اگر می‌خواهید Apigee Edge را برای اعتبارسنجی توکن‌هایی که خارج از Apigee Edge تولید می‌شوند پیکربندی کنید، می‌توانید از این تکنیک استفاده کنید.

در حالت معمول، Apigee Edge یک توکن OAuth تولید و ذخیره می‌کند و آن را به برنامه فراخوانی برمی‌گرداند. سپس برنامه فراخوانی کننده هنگام درخواست سرویس، آن توکن را به Apigee Edge ارائه می‌دهد و Apigee Edge - از طریق سیاست OAuthV2 با Operation = VerifyAccessToken - اعتبار توکن را تأیید می‌کند. این مبحث توضیح می‌دهد که چگونه می‌توانید Apigee Edge را پیکربندی کنید تا یک توکن OAuth که در جای دیگری تولید شده است را ذخیره کند، در حالی که بخش تأیید توکن را همانطور که گویی توکن توسط Edge تولید شده است، نگه دارد.

مثال

اگر می‌خواهید یک مثال کاربردی ببینید که تکنیک شرح داده شده در این مبحث را نشان می‌دهد، به نمونه Apigee Delegated Token Management نگاهی بیندازید.

این چیست؟

فرض کنید یک سیستم احراز هویت از قبل دارید و می‌خواهید از مقادیر توکن یا کد تولید شده توسط آن سیستم به جای مقادیر توکن یا کد OAuth2 که Edge تولید می‌کند، استفاده کنید. سپس می‌توانید درخواست‌های پروکسی API امن را با توکن یا کد جایگزین ارسال کنید و Edge آنها را طوری اعتبارسنجی می‌کند که انگار توسط Edge تولید شده‌اند.

برخی از پیشینه‌ها

در حالت معمول، Apigee Edge با تولید یک رشته تصادفی از حروف و اعداد، یک توکن تولید می‌کند. Apigee Edge داده‌های دیگری مانند زمان صدور توکن، تاریخ انقضا، لیست محصولات API که توکن برای آنها معتبر است و دامنه را به آن توکن مرتبط می‌کند. همه این اطلاعات را می‌توان در پاسخی که به طور خودکار توسط سیاست OAuthV2 پیکربندی شده با Operation = GenerateAccessToken تولید می‌شود، برگرداند. پاسخ به این شکل است:

{
  "issued_at": "1469735625687",
  "application_name": "06947a86-919e-4ca3-ac72-036723b18231",
  "scope": "urn://example.com/read",
  "status": "approved",
  "api_product_list": "[implicit-test]",
  "api_product_list_json": ["implicit-test"],
  "expires_in": "1799", //--in seconds
  "developer.email": "joe@weathersample.com",
  "token_type": "BearerToken",
  "client_id": "U9AC66e9YFyI1yqaXgUF8H6b9wUN1TLk",
  "access_token": "zBC90HhCGmGlaMBWeZAai2s3za5j",
  "organization_name": "wwitman",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

مقدار ویژگی access_token در واقع کلید جستجو برای داده‌های پاسخ است. یک برنامه می‌تواند درخواستی را به یک پروکسی API میزبانی شده در Edge ارسال کند که حامل توکن zBC90HhCGmGlaMBWeZAai2s3za5j است و Edge - با سیاست OAuthV2 با Operation = VerifyAccessToken - توکن را جستجو می‌کند، تمام اطلاعات را بازیابی می‌کند و از آن اطلاعات برای تعیین معتبر بودن یا نبودن توکن برای پروکسی API درخواستی استفاده می‌کند. به این کار اعتبارسنجی توکن می‌گویند. تمام اطلاعات فوق شامل توکن است. مقدار access_token فقط راهی برای جستجوی آن اطلاعات است.

از سوی دیگر، با دنبال کردن مراحل شرح داده شده در اینجا، می‌توانید Edge را طوری پیکربندی کنید که یک توکن را ذخیره کند، به طوری که مقدار access_token آن چیزی باشد که توسط یک سرویس خارجی تولید شده است. سایر فراداده‌ها نیز ممکن است یکسان باشند. به عنوان مثال، فرض کنید سیستمی خارجی برای Apigee Edge دارید که توکن‌هایی به شکل "TOKEN-< 16 random numbers >" تولید می‌کند. در این صورت، فراداده کامل توکن ذخیره شده توسط Apigee Edge ممکن است به صورت زیر باشد:

{
  "issued_at": "1469735625687",
  "application_name": "06947a86-919e-4ca3-ac72-036723b18231",
  "scope": "urn://example.com/read",
  "status": "approved",
  "api_product_list": "[implicit-test]",
  "api_product_list_json": ["implicit-test"],
  "expires_in": "1799", //--in seconds
  "developer.email": "joe@weathersample.com",
  "token_type": "BearerToken",
  "client_id": "U9AC66e9YFyI1yqaXgUF8H6b9wUN1TLk",
  "access_token": "TOKEN-1092837373654221",
  "organization_name": "wwitman",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

در این حالت، یک برنامه می‌تواند درخواستی را به یک پروکسی API میزبانی شده در Edge ارسال کند که حامل توکن TOKEN-1092837373654221 است و Edge - از طریق سیاست OAuthV2 با Operation = VerifyAccessToken - قادر به اعتبارسنجی آن خواهد بود. می‌توانید الگوی واردات مشابهی را برای کدهای مجوز و توکن‌های تازه‌سازی اعمال کنید.

بیایید در مورد اعتبارسنجی اعتبارنامه‌های مشتری صحبت کنیم

یکی از پیش‌نیازهای تولید توکن، اعتبارسنجی کلاینت درخواست‌کننده است. به‌طور پیش‌فرض، سیاست OAuthV2/GenerateAccessToken در Apigee Edge به‌طور ضمنی اعتبارنامه‌های کلاینت را تأیید می‌کند. به‌طور معمول در درخواستی برای توکن OAuthV2، client_id و client_secret در هدر Authorization ارسال می‌شوند و از طریق HTTP Basic Authorization (با الحاق دو نقطه، سپس با کدگذاری base64) کدگذاری می‌شوند. سیاست OAuthV2/GenerateAccessToken در Apigee Edge آن هدر را رمزگشایی کرده و client_id را جستجو می‌کند و تأیید می‌کند که client_secret ارسالی برای آن client_id معتبر است. این در صورتی کار می‌کند که اعتبارنامه‌ها برای Apigee Edge شناخته شده باشند - به عبارت دیگر، یک برنامه توسعه‌دهنده در Apigee Edge ذخیره شده باشد که حاوی یک اعتبارنامه باشد، که خود شامل client_id و client_secret داده شده است.

در صورتی که اعتبارنامه‌های کلاینت توسط Apigee Edge اعتبارسنجی نشوند، شما باید API Proxy خود را قبل از تولید توکن، طوری طراحی کنید که کلاینت را از طریق روش‌های دیگری به صراحت اعتبارسنجی کند. این کار اغلب از طریق یک سیاست ServiceCallout انجام می‌شود که به یک نقطه پایانی از راه دور در شبکه شما متصل می‌شود.

به هر حال، چه به صورت ضمنی و چه به صورت صریح، باید مطمئن شوید که API Proxy که توکن‌ها را تولید می‌کند، ابتدا اعتبارنامه‌های کلاینت را اعتبارسنجی می‌کند. به خاطر داشته باشید که اعتبارسنجی کلاینت مستقل از تولید توکن دسترسی است. می‌توانید Apigee Edge را طوری پیکربندی کنید که هر دو کار را انجام دهد، یا یکی از این دو کار را انجام دهد، یا هیچ‌کدام را.

اگر می‌خواهید سیاست OAuthV2/GenerateAccessToken در Apigee Edge اعتبارسنجی اعتبارنامه‌های کلاینت را در برابر فروشگاه Edge انجام دهد، عنصر <ExternalAuthorization> را در پیکربندی سیاست روی false تنظیم کنید یا آن را کاملاً حذف کنید. اگر می‌خواهید از یک سرویس مجوز خارجی برای اعتبارسنجی صریح اعتبارنامه‌های کلاینت استفاده کنید، <ExternalAuthorization> را روی true تنظیم کنید.

اگرچه ممکن است Apigee Edge اعتبارنامه‌های کلاینت را اعتبارسنجی نکند، اما همچنان لازم است که client_id توسط Apigee Edge شناخته و مدیریت شود. هر access_token در Apigee Edge، چه توسط Apigee Edge تولید شده باشد و چه توسط یک سیستم خارجی تولید شده و سپس به Apigee Edge وارد شده باشد، باید به یک برنامه کلاینت مرتبط باشد - که با client_id مشخص می‌شود. بنابراین حتی در مواردی که سیاست OAuthV2/GenerateAccessToken در Apigee Edge مطابقت client_id و client_secret را اعتبارسنجی نکند، این سیاست اعتبارسنجی می‌کند که client_id معتبر، موجود و لغو نشده است. بنابراین به عنوان یک مرحله راه‌اندازی پیش‌نیاز، ممکن است مجبور شوید client_idها را از طریق API اداری Edge وارد کنید.

جریان سیاست برای OAuth شخص ثالث در Apigee

برای استفاده از توکن‌های سیستم‌های OAuth شخص ثالث در Apigee Edge، روند تولید توکن‌های دسترسی باید از یکی از الگوهای زیر پیروی کند.

اعتبارسنجی خارجی اعتبارنامه‌های مشتری

  1. ServiceCallout برای تأیید اعتبارنامه‌های کلاینت ورودی و دریافت یک توکن خارجی.
  2. ExtractVariables یا یک مرحله جاوا اسکریپت برای استخراج توکن تولید شده خارجی از پاسخ.
  3. AssignMessage برای تنظیم متغیر خاص و شناخته‌شده‌ای به نام oauth_external_authorization_status استفاده می‌شود. مقدار آن باید درست باشد تا نشان دهد که اعتبارنامه‌های کلاینت معتبر هستند.
  4. OAuthV2 /GenerateAccessToken با عنصر <ExternalAuthorization> که روی true تنظیم شده است، و حداقل یکی از <ExternalAccessToken> ، <ExternalRefreshToken> یا <ExternalAuthorizationCode> .

اعتبارسنجی داخلی اعتبارنامه‌های مشتری

  • ServiceCallout برای به دست آوردن یک توکن خارجی.
  • ExtractVariables یا یک مرحله جاوا اسکریپت برای استخراج توکن تولید شده خارجی از پاسخ.
  • OAuthV2 /GenerateAccessToken با عنصر <ExternalAuthorization> که روی false تنظیم شده است، و حداقل یکی از <ExternalAccessToken> ، <ExternalRefreshToken> یا <ExternalAuthorizationCode> .

یادداشت‌هایی در مورد جریان و پیکربندی سیاست

  • در صورتی که مایل به استفاده از یک سیستم خارجی برای اعتبارسنجی اعتبارنامه‌های کلاینت هستید، توسعه یک جریان سیاست‌گذاری که کارهای لازم را انجام دهد، به شما بستگی دارد. معمولاً شما از یک سیاست ServiceCallout برای ارسال اعتبارنامه‌های شناخته‌شده خارجی به سرویس احراز هویت خارجی استفاده می‌کنید. سرویس احراز هویت خارجی معمولاً یک پاسخ برمی‌گرداند و در صورت معتبر بودن اعتبارنامه‌ها، یک توکن دسترسی نیز برمی‌گرداند.

  • پس از ServiceCallout، پروکسی API باید پاسخ را تجزیه کند تا وضعیت اعتبار و همچنین access_token تولید شده خارجی و احتمالاً refresh_token را استخراج کند.

  • در سیاست OAuthV2/GenerateAccessToken، عنصر <StoreToken> را روی true تنظیم کنید و عنصر <ExternalAuthorization> را بسته به مورد، روی true یا false تنظیم کنید.

    وقتی سیاست OAuthV2/GenerateAccessToken اجرا می‌شود، متغیر oauth_external_authorization_status را می‌خواند. اگر متغیر تنظیم شده باشد و مقدار آن درست باشد، Apigee Edge تلاشی برای اعتبارسنجی اعتبارنامه‌های کلاینت نمی‌کند. اگر متغیر تنظیم نشده باشد یا مقدار آن درست نباشد، Apigee Edge تلاش می‌کند اعتبارنامه‌های کلاینت را اعتبارسنجی کند.

  • سه عنصر برای سیاست OAuthV2 وجود دارد که به شما امکان می‌دهد داده‌های خارجی را برای وارد کردن مشخص کنید: <ExternalAccessToken> ، <ExternalRefreshToken> و <ExternalAuthorizationCode> . هر یک از این عناصر یک متغیر جریان را می‌پذیرند. سیاست Edge آن متغیر را می‌خواند تا توکن دسترسی، توکن به‌روزرسانی یا کد مجوز تولید شده خارجی را پیدا کند. پیاده‌سازی سیاست‌ها و منطق برای قرار دادن توکن‌ها یا کدهای خارجی در متغیرهای مناسب به شما بستگی دارد.

    برای مثال، پیکربندی زیر در سیاست OAuthV2 به Edge می‌گوید که توکن را در یک متغیر زمینه‌ای به نام external_token جستجو کند.

    <ExternalAccessToken>external_token</ExternalAccessToken>

    همچنین به یک مرحله قبلی نیاز دارید که آن متغیر را تنظیم کند.

  • در مورد تنظیم متغیر oauth_external_authorization_status ، یک تکنیک رایج برای تنظیم این متغیر، استفاده از یک سیاست AssignMessage با عنصر AssignVariable است، مانند این:

    <AssignMessage name="AssignMessage-SetVariable">
    <DisplayName>Assign Message - Set Variable</DisplayName>
    <AssignVariable>
        <Name>oauth_external_authorization_status</Name>
        <Value>true</Value>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

    به یاد داشته باشید، این سیاست باید قبل از سیاست OAuthV2 با Operation = GenerateAccessToken قرار گیرد.

مثالی از سیاست OAuthV2

سیاست OAuthV2 زیر، با توجه به اینکه Edge یک مقدار توکن در متغیر جریان external_access_token پیدا می‌کند، یک توکن دسترسی Apigee Edge تولید می‌کند.

<OAuthV2 name="OAuth-v20-Store-External-Token">
    <ExternalAccessToken>external_access_token</ExternalAccessToken>
    <ExternalAuthorization>true</ExternalAuthorization>
    <Operation>GenerateAccessToken</Operation>
    <GenerateResponse enabled="true">
        <Format>FORM_PARAM</Format>
    </GenerateResponse>
    <ReuseRefreshToken>false</ReuseRefreshToken>
    <StoreToken>true</StoreToken>
    <SupportedGrantTypes>
        <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <ExpiresIn ref='flow.variable'>2400000</ExpiresIn>
</OAuthV2>

در تئوری، شما می‌توانید این الگو را با هر سرویس احراز هویت OAuth2 شخص ثالث اعمال کنید.