استفاده از کدهای OAuth طرف سوم

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

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

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

مثال

اگر می‌خواهید نمونه کاری را ببینید که تکنیک توضیح‌داده‌شده در این موضوع را نشان می‌دهد، به نمونه مدیریت نماینده‌ای نمانام Apigee نگاهی بیندازید.

این چیست؟

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

پس‌زمینه

در حالت معمول، Apigee Edge با تولید رشته‌ای تصادفی از حروف و اعداد، یک کد تولید می‌کند. ‫Apigee Edge داده‌های دیگری مثل زمان صدور رمز، انقضا، فهرست «محصولات API» که رمز برای آن‌ها معتبر است، و محدوده را به آن رمز منسوب می‌کند. همه این اطلاعات را می‌توان در پاسخی که به‌طور خودکار توسط خط‌مشی OAuthV2 پیکربندی‌شده با «عملیات = 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 با «عملکرد = VerifyAccessToken» - کد را جستجو می‌کند، همه اطلاعات را بازیابی می‌کند، و از آن اطلاعات برای تعیین معتبر بودن یا نبودن کد برای پراکسی API درخواستی استفاده می‌کند. این امر اعتبارسنجی کد نامیده می‌شود. همه اطلاعات بالا نشان را تشکیل می‌دهد. مقدار access_token فقط روشی برای جستجوی آن اطلاعات است.

ازطرف دیگر، با دنبال کردن مراحلی که در اینجا توضیح داده شده است، می‌توانید Edge را پیکربندی کنید تا نشانی ذخیره کند تا مقدار access_token آن چیزی باشد که سرویس خارجی تولید کرده است. همه فراداده‌های دیگر ممکن است یکسان باشند. برای مثال، فرض کنید سیستمی خارج از Apigee Edge دارید که نشانه‌هایی با قالب «TOKEN-<16 عدد تصادفی>» تولید می‌کند. در این حالت، فراداده کامل نشان ذخیره‌شده توسط 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"
}

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

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

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

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

به‌هرحال، چه به‌صورت ضمنی و چه به‌صورت صریح، باید مطمئن شوید که «پراکسی میانای برنامه‌سازی کاربردی» که کد تولید می‌کند، ابتدا اطلاعات اعتباری کارخواه را درستی‌سنجی می‌کند. به‌خاطر داشته باشید که اعتبارسنجی کارخواه مستقل از تولید کردن کد دسترسی است. می‌توانید 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 را ازطریق Edge API مدیریتی وارد کنید.

جریان خط‌مشی برای OAuth طرف سوم در Apigee

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

برون‌سازمانی اعتبارسنجی اطلاعات اعتباری کارخواه

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

داخلی اعتبارسنجی اطلاعات اعتباری کارخواه

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

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

  • درصورتی‌که بخواهید از سیستم خارجی برای اعتبارسنجی اطلاعات اعتباری مشتری استفاده کنید، توسعه جریان خط‌مشی که کارهای لازم را انجام دهد برعهده شما است. معمولاً از خط‌مشی 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 با «عملکرد = GenerateAccessToken» قرار بگیرد.

خط‌مشی نمونه OAuthV2

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

<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 طرف سوم اعمال کنید.