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

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

با نوع اعطای اطلاعات اعتباری کارخواه، برنامه اطلاعات اعتباری خود (شناسه کارخواه و رمز کارخواه) را به نقطه پایانی در Apigee Edge که برای تولید کردن کد دسترسی تنظیم شده است ارسال می‌کند. اگر اطلاعات اعتباری معتبر باشد، Edge یک کد دسترسی به برنامه مشتری برمی‌گرداند.

درباره این موضوع

این موضوع شرح کلی از نوع اعطای اطلاعات اعتباری کارخواه OAuth 2.0 ارائه می‌دهد و درباره نحوه پیاده‌سازی این جریان در Apigee Edge بحث می‌کند.

موارد استفاده

معمولاً این نوع اعطا زمانی استفاده می‌شود که برنامه مالک منبع نیز باشد. برای مثال، برنامه ممکن است برای ذخیره و بازیابی داده‌هایی که برای انجام کارش استفاده می‌کند، نیاز به دسترسی به سرویس ذخیره‌سازی ابری زیرینه داشته باشد، نه داده‌هایی که به‌طور خاص متعلق به کاربر نهایی است. جریان این نوع اعطا کاملاً بین برنامه کارخواه و سرور مجوز رخ می‌دهد. کاربر نهایی در این نوع جریان کمک مالی شرکت نمی‌کند.

نقش‌ها

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

  • برنامه کارخواه -- برنامه‌ای که باید به منابع محافظت‌شده کاربر دسترسی داشته باشد. معمولاً با این جریان، برنامه به‌جای اینکه به‌صورت محلی در رایانه کیفی یا دستگاه کاربر اجرا شود، در سرور اجرا می‌شود.
  • Apigee Edge -- در این جریان، Apigee Edge سرور مجوز OAuth است. نقش آن تولید کد دسترسی، اعتبارسنجی کد دسترسی، و ارسال درخواست‌های مجاز برای منابع محافظت‌شده به سرور منبع است.
  • سرور منبع -- سرویس پشتیبانی که داده‌های محافظت‌شده را ذخیره می‌کند و برنامه مشتری برای دسترسی به آن نیاز به اجازه دارد. اگر از پراکسی‌های API میزبانی‌شده در Apigee Edge محافظت می‌کنید، Apigee Edge نیز سرور منبع است.

نمونه کد

می‌توانید پیاده‌سازی نمونه کامل و کارآمدی از نوع اعطای اطلاعات اعتباری مشتری را در GitHub پیدا کنید. برای پیوند به نمونه‌های بیشتر، به منابع اضافی در زیر مراجعه کنید.

روندنما

نمودار جریان زیر جریان اطلاعات اعتباری مشتری را با Apigee Edge به‌عنوان سرور مجوز نشان می‌دهد. به‌طورکلی، Edge در این جریان نیز سرور منبع است -- یعنی، کارگزاران نیابتی API منابع محافظت‌شده هستند.


مراحل جریان اطلاعات اعتباری کارخواه

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

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

۱. کارخواه درخواست داده‌واحد (توکن) دسترسی می‌کند

برای دریافت کردن کد دسترسی، کارخواه با مقادیر شناسه کارخواه و رمز کارخواه که از برنامه توسعه‌دهنده ثبت‌شده دریافت شده است، یک فراخوانی «میانای برنامه‌سازی کاربردی» به Edge ارسال می‌کند. علاوه‌براین، پارامتر grant_type=client_credentials باید به‌عنوان پارامتر پُرسمان ارسال شود. (بااین‌حال، می‌توانید خط‌مشی OAuthV2 را پیکربندی کنید تا این پارامتر را در سرصفحه یا بدنه درخواست بپذیرد -- برای جزئیات، خط‌مشی OAuthV2 را ببینید).

برای مثال:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials&client_id=ns4fQc14Zg4hKFCNaSzArVuwszX95X&client_secret=ZIjFyTsNgQNyxI'

توجه: اگرچه می‌توانید مقادیر client_id و client_secret را به‌عنوان پارامترهای پُرسمان همان‌طور که در بالا نشان داده شده است ارسال کنید، بهتر است آن‌ها را به‌عنوان رشته کدبندی‌شده نشانی وب ۶۴پایه‌ای در سرصفحه «مجوز» ارسال کنید. برای انجام این کار، باید از ابزار یا برنامه کمکی کدبندی base64 برای کدبندی دو مقدار با هم و با دونقطه به‌عنوان جداکننده استفاده کنید. به این صورت: aBase64EncodeFunction(clientidvalue:clientsecret). بنابراین، مثال بالا به این صورت کدبندی می‌شود: این:

result = aBase64EncodeFunction(ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI) // به دونقطه جداکننده دو مقدار توجه کنید.

نتیجه کدبندی base64 رشته بالا این است: bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==

سپس، درخواست داده‌واحد را به این صورت انجام دهید:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials' -H 'Authorization: Basic bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg=='

۲. ‫Edge اعتبارنامه‌ها را اعتبارسنجی می‌کند

توجه داشته باشید که تماس API به نقطه پایانی /accesstoken ارسال می‌شود. این نقطه پایانی خط‌مشی‌ای دارد که به آن پیوست شده است و اطلاعات اعتباری برنامه را اعتبارسنجی می‌کند. یعنی خط‌مشی کلیدهای ارسالی را با کلیدهایی که Apigee Edge هنگام ثبت برنامه ایجاد کرده است مقایسه می‌کند. اگر می‌خواهید درباره نقطه‌های پایانی OAuth در Edge بیشتر بدانید، پیکربندی نقطه‌های پایانی و خط‌مشی‌های OAuth را ببینید.

۳. ‫Edge پاسخی برمی‌گرداند

اگر اطلاعات اعتباری درست باشد، Edge یک کد دسترسی به کارخواه برمی‌گرداند. اگر مشخص نشده باشد، خطایی برمی‌گردد.

۴. کارخواه میانای برنامه‌سازی کاربردی محافظت‌شده را فراخوانی می‌کند

اکنون، با یک کد دسترسی معتبر، کارخواه می‌تواند با «میانای برنامه‌سازی کاربردی» محافظت‌شده تماس بگیرد. در این سناریو، درخواست‌ها به Apigee Edge (پراکسی) ارسال می‌شود و Edge مسئولیت دارد کد دسترسی را قبل‌از ارسال تماس API به سرور منبع هدف درستی‌سنجی کند. برای مثال، فراخوانی API محافظت‌شده در زیر را ببینید.

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

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

پیکربندی جریان سفارشی

آسان‌ترین راه برای نشان دادن نحوه پیکربندی جریان پراکسی API، نشان دادن تعریف جریان XML است. در اینجا یک جریان پراکسی API نمونه طراحی‌شده برای پردازش درخواست کد دسترسی آورده شده است. برای مثال، وقتی درخواستی وارد می‌شود و پسوند مسیر با /accesstoken مطابقت دارد، خط‌مشی GetAccessToken راه‌اندازی می‌شود. برای نمای کلی سریع از مراحل لازم برای ایجاد یک جریان سفارشی مانند این، پیکربندی نقاط پایانی و خط‌مشی‌های OAuth را ببینید.

<Flows>
  <Flow name="GetAccessToken">
         <!-- This policy flow is triggered when the URI path suffix
         matches /oauth/accesstoken. Publish this URL to app developers 
         to use when obtaining an access token using an auth code   
         -->
    <Condition>proxy.pathsuffix == "/oauth/accesstoken"</Condition>
    <Request>
        <Step><Name>GetAccessToken</Name></Step>
    </Request>
  </Flow>
</Flows>

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

باید خط‌مشی را به نقطه پایانی پیوست کنید، به این صورت. برای نمای کلی سریع از مراحل لازم برای افزودن خط‌مشی OAuthV2 به نقطه پایانی پراکسی، پیکربندی نقاط پایانی و خط‌مشی‌های OAuth را ببینید.

دریافت کد دسترسی

این خط‌مشی به مسیر /accesstoken پیوست شده است. از خط‌مشی OAuthV2 با عملیات GenerateAccessToken مشخص‌شده استفاده می‌کند.

<OAuthV2 name="GetAccessToken">
  <Operation>GenerateAccessToken</Operation>
  <ExpiresIn>3600000</ExpiresIn>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GenerateResponse/>
</OAuthV2>

فراخوانی API برای دریافت کد دسترسی یک POST است و شامل سرصفحه «مجوز» با کدبندی base64 از client_id + client+secret و پارامتر پُرسمان grant_type=client_credentials است. همچنین می‌تواند شامل پارامترهای اختیاری برای محدوده و وضعیت باشد. برای مثال:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials' -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVgT1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ'

پیوست کردن خط‌مشی کد دسترسی درستی‌سنجی

برای محافظت از میانای برنامه‌سازی کاربردی خود با امنیت OAuth 2.0، باید خط‌مشی OAuthV2 را با عملکرد VerifyAccessToken اضافه کنید. این خط‌مشی بررسی می‌کند که درخواست‌های ورودی دارای کد دسترسی معتبر باشند. اگر کد معتبر باشد، Edge درخواست را پردازش می‌کند. اگر معتبر نباشد، Edge خطا برمی‌گرداند. برای مراحل اولیه، درستی‌سنجی کدهای دسترسی را ببینید.

<OAuthV2 async="false" continueOnError="false" enabled="true" name="VerifyAccessToken">
    <DisplayName>VerifyAccessToken</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <SupportedGrantTypes/>
    <GenerateResponse enabled="true"/>
    <Tokens/>
</OAuthV2>

فراخوانی API محافظت‌شده

برای فراخوانی کردن میانای برنامه‌سازی کاربردی که با امنیت OAuth 2.0 محافظت می‌شود، باید کد دسترسی معتبری ارائه دهید. الگوی صحیح این است که نشان را در سرایند «مجوز» بگنجانید، به این صورت: توجه داشته باشید که نشان دسترسی به‌عنوان «نشان حامل» نیز شناخته می‌شود.

$ curl -H "Authorization: Bearer UAj2yiGAcMZGxfN2DhcUbl9v8WsR" \
  http://myorg-test.apigee.net/v0/weather/forecastrss?w=12797282 

همچنین ارسال کد دسترسی را ببینید.

منابع تکمیلی

  • ‫Apigee برای توسعه‌دهندگان API آموزش آنلاین ارائه می‌دهد، ازجمله دوره‌ای درباره امنیت API که شامل OAuth می‌شود.
  • خط‌مشی OAuthV2 -- مثال‌های زیادی دارد که نشان می‌دهد چگونه درخواست‌ها را به سرور مجوز ارسال کنید و چگونه خط‌مشی OAuthV2 را پیکربندی کنید.