شما در حال مشاهده مستندات Apigee Edge هستید.
به مستندات Apigee X مراجعه کنید . اطلاعات
آنچه یاد خواهید گرفت
- یک نمونه پروکسی API را دانلود و مستقر کنید.
- یک پروکسی API محافظتشده با OAuth ایجاد کنید.
- یک محصول، توسعهدهنده و اپلیکیشن ایجاد کنید.
- اعتبارنامهها را در ازای دریافت توکن دسترسی OAuth مبادله کنید.
- یک API را با یک توکن دسترسی فراخوانی کنید.
این آموزش به شما نشان میدهد که چگونه یک API را با OAuth 2.0 ایمن کنید.
OAuth یک پروتکل احراز هویت است که به برنامهها اجازه میدهد بدون نیاز به افشای نام کاربری و رمز عبور کاربران، به اطلاعات آنها دسترسی پیدا کنند.
با OAuth، اطلاعات امنیتی (مانند نام کاربری/رمز عبور یا کلید/رمز عبور) با یک توکن دسترسی مبادله میشوند. برای مثال:
joe:joes_password (نام کاربری:رمز عبور) یا
Nf2moHOASMJeUmXVdDhlMbPaXm2U7eMc:unUOXYpPe74ZfLEb (کلید: مخفی)
تبدیل به چیزی شبیه به:
b0uiYwjRZLEo4lEu7ky2GGxHkanN
توکن دسترسی یک رشته تصادفی از کاراکترها است و موقتی است (باید پس از مدت زمان نسبتاً کوتاهی منقضی شود)، بنابراین ارسال آن برای احراز هویت کاربر در گردش کار یک برنامه بسیار امنتر از ارسال اعتبارنامههای واقعی است.
مشخصات OAuth 2.0 مکانیسمهای مختلفی به نام «انواع اعطای مجوز» را برای توزیع توکنهای دسترسی برای برنامهها تعریف میکند. اساسیترین نوع اعطای مجوز که توسط OAuth 2.0 تعریف شده است، «اعتبارنامههای کلاینت» نامیده میشود. در این نوع اعطای مجوز، توکنهای دسترسی OAuth در ازای اعتبارنامههای کلاینت تولید میشوند که مانند مثال بالا، جفتهای کلید مصرفکننده/رمز مصرفکننده هستند.
نوع اعطای اعتبارنامهی کلاینت در Edge با استفاده از سیاستهای موجود در پروکسیهای API پیادهسازی میشود. یک جریان معمول OAuth شامل دو مرحله است:
- برای تولید یک توکن دسترسی OAuth از اعتبارنامههای کلاینت ، API proxy 1 را فراخوانی کنید . یک سیاست OAuth v2.0 در API proxy این کار را انجام میدهد.
- برای ارسال توکن دسترسی OAuth در یک فراخوانی API ، پروکسی API 2 را فراخوانی کنید . پروکسی API با استفاده از خطمشی OAuth نسخه ۲.۰، توکن دسترسی را تأیید میکند.
آنچه نیاز دارید
- یک حساب کاربری Apigee Edge. اگر هنوز حساب کاربری ندارید، میتوانید با استفاده از دستورالعملهای موجود در بخش «ایجاد حساب کاربری Apigee Edge» ثبتنام کنید.
- cURL روی دستگاه شما نصب شده باشد تا بتوانید فراخوانیهای API را از خط فرمان انجام دهید.
دانلود و استقرار یک پروکسی API تولیدکننده توکن
در این مرحله، شما یک پروکسی API ایجاد خواهید کرد که یک توکن دسترسی OAuth را از یک کلید مصرفکننده و رمز مصرفکننده که در یک فراخوانی API ارسال میشود، تولید میکند. Apigee یک پروکسی API نمونه ارائه میدهد که این کار را انجام میدهد. اکنون پروکسی را دانلود و مستقر میکنید، سپس بعداً در آموزش از آن استفاده خواهید کرد. (شما میتوانید خودتان به راحتی این پروکسی API را بسازید. این مرحله دانلود و مستقر کردن برای راحتی و نشان دادن سهولت اشتراکگذاری پروکسیهایی است که قبلاً ایجاد شدهاند.)
- فایل زیپ نمونه پروکسی API 'oauth' را در هر دایرکتوری روی سیستم فایل خود دانلود کنید .
- به آدرس https://apigee.com/edge بروید و وارد سیستم شوید.
- در نوار ناوبری سمت چپ، گزینهی Develop > API Proxies را انتخاب کنید.
- روی + پروکسی کلیک کنید.
- در ویزارد ایجاد پروکسی ، روی آپلود بسته پروکسی کلیک کنید.
- فایل
oauth.zipکه دانلود کردهاید را انتخاب کنید و روی Next کلیک کنید. - روی ایجاد کلیک کنید.
- پس از اتمام ساخت، برای مشاهده پروکسی جدید در ویرایشگر پروکسی API، روی ویرایش پروکسی کلیک کنید.
- در صفحه مرور کلی ویرایشگر پروکسی API، روی منوی کشویی Deployment کلیک کنید و test را انتخاب کنید. این محیط تست در سازمان شماست.
در اعلان تأیید، روی «استقرار» کلیک کنید.
وقتی دوباره روی منوی کشویی Deployment کلیک کنید، یک آیکون سبز نشان میدهد که پروکسی در محیط آزمایشی مستقر شده است.
آفرین! شما با موفقیت یک پروکسی API تولیدکننده توکن دسترسی را دانلود و در سازمان Edge خود مستقر کردید.
جریان و سیاست OAuth را مشاهده کنید
بیایید نگاهی دقیقتر به آنچه پروکسی API شامل میشود، بیندازیم.
- در ویرایشگر پروکسی API، روی برگه Develop کلیک کنید. در پنل سمت چپ Navigator ، دو سیاست (policy) خواهید دید. همچنین دو جریان
POSTرا در بخشProxy Endpointsمشاهده خواهید کرد. در قسمت
Proxy Endpointsروی AccessTokenClientCredential کلیک کنید.
در نمای کد XML، یک
Flowبه نامAccessTokenClientCredentialخواهید دید:<Flow name="AccessTokenClientCredential"> <Description/> <Request> <Step> <Name>GenerateAccessTokenClient</Name> </Step> </Request> <Response/> <Condition>(proxy.pathsuffix MatchesPath "/accesstoken") and (request.verb = "POST")</Condition> </Flow>یک جریان، یک مرحله پردازش در یک پروکسی API است. در این حالت، جریان زمانی فعال میشود که یک شرط خاص برآورده شود (به آن جریان شرطی میگویند). شرط، که در عنصر
<Condition>تعریف شده است، میگوید که اگر فراخوانی پروکسی API به منبع/accesstokenانجام شود و فعل درخواستPOSTباشد، آنگاه سیاستGenerateAccessTokenClientاجرا کنید که توکن دسترسی را تولید میکند.حالا بیایید نگاهی به سیاستی که جریان شرطی فعال میکند بیندازیم. روی آیکون سیاست GenerateAccessTokenClient در نمودار جریان کلیک کنید.
پیکربندی XML زیر در نمای کد بارگذاری میشود:<OAuthV2 name="GenerateAccessTokenClient"> <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type --> <Operation>GenerateAccessToken</Operation> <!-- This is in millseconds, so expire in an hour --> <ExpiresIn>3600000</ExpiresIn> <SupportedGrantTypes> <!-- This part is very important: most real OAuth 2.0 apps will want to use other grant types. In this case it is important to NOT include the "client_credentials" type because it allows a client to get access to a token with no user authentication --> <GrantType>client_credentials</GrantType> </SupportedGrantTypes> <GrantType>request.queryparam.grant_type</GrantType> <GenerateResponse/> </OAuthV2>
پیکربندی شامل موارد زیر است:
-
<Operation>که میتواند یکی از چندین مقدار از پیش تعریف شده باشد، مشخص میکند که این سیاست قرار است چه کاری انجام دهد. در این مورد، قرار است یک توکن دسترسی ایجاد کند. - این توکن ۱ ساعت (۳۶۰۰۰۰۰ میلیثانیه) پس از تولید، منقضی خواهد شد.
- در
<SupportedGrantTypes>، انتظار میرود OAuth<GrantType>مورد استفاده،client_credentialsباشد (مبادله یک کلید مصرفکننده و رمز برای یک توکن OAuth). - عنصر دوم
<GrantType>به سیاست میگوید که در فراخوانی API، پارامتر نوع اعطای کمک هزینه را جستجو کند، همانطور که توسط مشخصات OAuth 2.0 الزامی شده است. (این را بعداً در فراخوانی API خواهید دید). نوع کمک هزینه همچنین میتواند در هدر HTTP (request.header.grant_type) یا به عنوان یک پارامتر فرم (request.formparam.grant_type) ارسال شود.
-
در حال حاضر نیازی به انجام کار دیگری با پروکسی API ندارید. در مراحل بعدی، از این پروکسی API برای تولید توکن دسترسی OAuth استفاده خواهید کرد. اما ابتدا باید چند کار دیگر انجام دهید:
- پروکسی API مورد نظر خود را که میخواهید با OAuth ایمن کنید، ایجاد کنید.
- چند مصنوعات دیگر ایجاد کنید که منجر به کلید مصرفکننده و راز مصرفکنندهای میشوند که برای تبادل با یک نشانه دسترسی نیاز دارید.
پروکسی API محافظتشده با OAuth را ایجاد کنید
حالا شما باید پروکسی API مورد نظر خود را ایجاد کنید. این فراخوانی API است که چیزی را که شما میخواهید برمیگرداند. در این حالت، پروکسی API سرویس mocktarget شرکت Apigee را برای بازگرداندن آدرس IP شما فراخوانی میکند. اما، شما فقط در صورتی میتوانید آن را ببینید که یک توکن دسترسی OAuth معتبر را با فراخوانی API خود ارسال کنید.
پروکسی API که اینجا ایجاد میکنید شامل سیاستی خواهد بود که وجود توکن OAuth را در درخواست بررسی میکند.
- در نوار ناوبری سمت چپ، گزینهی Develop > API Proxies را انتخاب کنید.
- روی + پروکسی کلیک کنید.
- در ویزارد ساخت پروکسی ، پروکسی معکوس (رایجترین) را انتخاب کنید و روی بعدی کلیک کنید.
- پروکسی را با موارد زیر پیکربندی کنید:
در این زمینه این کار را انجام دهید نام پروکسی وارد کنید: helloworld_oauth2مسیر پایه پروژه تغییر به:
/hellooauth2مسیر پایه پروژه بخشی از URL است که برای ارسال درخواست به پروکسی API استفاده میشود.
API موجود وارد شوید:
https://mocktarget.apigee.net/ipاین، URL هدفی را تعریف میکند که Apigee Edge در هنگام درخواست به پروکسی API فراخوانی میکند.
توضیحات وارد کنید: hello world protected by OAuth - روی بعدی کلیک کنید.
- در صفحه سیاستهای مشترک :
در این زمینه این کار را انجام دهید امنیت: مجوز انتخاب کنید: OAuth 2.0 - روی بعدی کلیک کنید.
- در صفحه میزبانهای مجازی ، روی «بعدی» کلیک کنید.
- در صفحه ساخت ، مطمئن شوید که محیط آزمایشی انتخاب شده است و روی «ایجاد و استقرار» کلیک کنید.
- در صفحه خلاصه ، تأییدیهای مبنی بر موفقیتآمیز بودن ایجاد پروکسی API جدید و استقرار آن در محیط آزمایشی مشاهده میکنید.
- برای نمایش صفحه مرور کلی برای پروکسی API ، روی ویرایش پروکسی کلیک کنید.
توجه داشته باشید که این بار پروکسی API به طور خودکار مستقر میشود. روی منوی کشویی Deployment کلیک کنید تا مطمئن شوید که یک نقطه سبز رنگ در کنار محیط "test" وجود دارد.
مشاهده سیاستها
بیایید نگاهی دقیقتر به آنچه خلق کردهاید بیندازیم.
- در ویرایشگر پروکسی API، روی برگه «توسعه» کلیک کنید. خواهید دید که دو خطمشی به جریان درخواست پروکسی API اضافه شده است:
- تأیید توکن دسترسی OAuth نسخه ۲.۰ - فراخوانی API را بررسی میکند تا مطمئن شود که یک توکن OAuth معتبر وجود دارد.
- حذف مجوز هدر - یک سیاست AssignMessage که توکن دسترسی را پس از بررسی حذف میکند، به طوری که به سرویس هدف منتقل نشود. (اگر سرویس هدف به توکن دسترسی OAuth نیاز داشت، شما از این سیاست استفاده نمیکردید).
روی آیکون Verify OAuth v2.0 Access Token در نمای جریان کلیک کنید و به XML زیر آن در قسمت کد نگاه کنید.
<OAuthV2 async="false" continueOnError="false" enabled="true" name="verify-oauth-v2-access-token"> <DisplayName>Verify OAuth v2.0 Access Token</DisplayName> <Operation>VerifyAccessToken</Operation> </OAuthV2>توجه داشته باشید که
<Operation>VerifyAccessTokenاست. این Operation مشخص میکند که Policy قرار است چه کاری انجام دهد. در این مورد، قرار است توکن OAuth معتبری را در درخواست بررسی کند.
افزودن محصول API
برای افزودن یک محصول API با استفاده از رابط کاربری Apigee:
- انتشار > محصولات API را انتخاب کنید.
- روی +محصول API کلیک کنید.
- جزئیات محصول را برای محصول API خود وارد کنید.
میدان توضیحات نام نام داخلی محصول API. کاراکترهای خاص را در نام مشخص نکنید.
توجه: پس از ایجاد محصول API، نمیتوانید نام را ویرایش کنید. برای مثال،helloworld_oauth2-Productنام نمایشی نام نمایشی برای محصول API. نام نمایشی در رابط کاربری استفاده میشود و میتوانید آن را در هر زمانی ویرایش کنید. در صورت عدم تعیین، از مقدار Name استفاده خواهد شد. این فیلد به طور خودکار با استفاده از مقدار Name پر میشود؛ میتوانید محتوای آن را ویرایش یا حذف کنید. نام نمایشی میتواند شامل کاراکترهای ویژه باشد. به عنوان مثال، helloworld_oauth2-Product.توضیحات شرح محصول API. محیط زیست محیطهایی که محصول API به آنها اجازه دسترسی میدهد. محیطی را که پروکسی API را در آن مستقر کردهاید انتخاب کنید. برای مثال، test.دسترسی عمومی را انتخاب کنید. درخواستهای دسترسی را بهطور خودکار تأیید کنید تأیید خودکار درخواستهای کلیدی برای این محصول API را از هر برنامهای فعال کنید. سهمیه این آموزش را نادیده بگیرید. محدودههای مجاز OAuth این آموزش را نادیده بگیرید. - در فیلد API proxies ، پراکسی API که ایجاد کردهاید را انتخاب کنید.
- در فیلد مسیر ، "/" را وارد کنید. فیلدهای دیگر را نادیده بگیرید.
- روی ذخیره کلیک کنید.
یک توسعهدهنده و برنامه به سازمان خود اضافه کنید
در مرحله بعد، شما قصد دارید گردش کار ثبت نام یک توسعهدهنده برای استفاده از API های خود را شبیهسازی کنید. در حالت ایدهآل، توسعهدهندگان خود و برنامههایشان را از طریق پورتال توسعهدهندگان شما ثبت میکنند. با این حال، در این مرحله، شما یک توسعهدهنده و یک برنامه را به عنوان مدیر اضافه خواهید کرد.
یک توسعهدهنده یک یا چند برنامه خواهد داشت که APIهای شما را فراخوانی میکنند و هر برنامه یک کلید مصرفکننده و یک راز مصرفکننده منحصر به فرد دریافت میکند. این کلید/راز به ازای هر برنامه همچنین به شما، به عنوان ارائهدهنده API، کنترل دقیقتری بر دسترسی به APIهای شما و گزارشهای تحلیلی دقیقتری در مورد ترافیک API میدهد، زیرا Edge میداند کدام توسعهدهنده و برنامه متعلق به کدام توکن OAuth است.
یک توسعهدهنده ایجاد کنید
بیایید یک توسعهدهنده به نام نایجل تافنل ایجاد کنیم.
- از منو، گزینه انتشار > توسعهدهندگان را انتخاب کنید.
- روی + توسعهدهنده کلیک کنید.
- در پنجره New Developer موارد زیر را وارد کنید:
در این زمینه وارد شوید نام Nigelنام خانوادگی Tufnelنام کاربری nigelایمیل nigel@example.com - روی ایجاد کلیک کنید.
ثبت یک برنامه
بیایید یک برنامه برای نایجل بسازیم.
- انتشار > برنامهها را انتخاب کنید.
- روی + برنامه کلیک کنید.
- در پنجره New App موارد زیر را وارد کنید:
در این زمینه این کار را انجام دهید نام و نام نمایشی وارد کنید: nigel_appتوسعهدهنده روی توسعهدهنده کلیک کنید و گزینهی زیر را انتخاب کنید: Nigel Tufnel (nigel@example.com)آدرس اینترنتی و یادداشتهای مربوط به فراخوانی مجدد خالی بگذارید - در قسمت محصولات ، روی افزودن محصول کلیک کنید.
- helloworld_oauth2-Product را انتخاب کنید.
- روی ایجاد کلیک کنید.
کلید مصرفکننده و رمز مصرفکننده را دریافت کنید
اکنون کلید مصرفکننده و راز مصرفکننده را دریافت خواهید کرد که با یک توکن دسترسی OAuth مبادله میشوند.
- مطمئن شوید که صفحه nigel_app نمایش داده میشود. در غیر این صورت، در صفحه برنامهها (Publish > Apps)، روی nigel_app کلیک کنید.
در صفحه nigel_app، روی نمایش در ستونهای Key و Secret کلیک کنید. توجه داشته باشید که کلید/راز با "helloworld_oauth2-Product" که قبلاً به طور خودکار ایجاد شده است، مرتبط است.
- کلید و رمز را انتخاب و کپی کنید. آنها را در یک فایل متنی موقت جایگذاری کنید . در مرحله بعد، جایی که پروکسی API را فراخوانی میکنید که این اعتبارنامهها را با یک توکن دسترسی OAuth مبادله میکند، از آنها استفاده خواهید کرد.
سعی کنید API را برای دریافت آدرس IP خود فراخوانی کنید (ناموفق!)
فقط برای شروع، سعی کنید پروکسی API محافظتشدهای را که قرار است آدرس IP شما را برگرداند، فراخوانی کنید. دستور cURL زیر را در یک پنجره ترمینال اجرا کنید و نام سازمان Edge خود را جایگزین کنید. کلمه test در URL، محیط آزمایشی سازمان شما است، همان جایی که پروکسیهای خود را در آن مستقر کردهاید. مسیر پایه پروکسی /hellooauth2 است، همان مسیری که هنگام ایجاد پروکسی مشخص کردهاید. توجه داشته باشید که در این فراخوانی، توکن دسترسی OAuth را ارسال نمیکنید .
curl https://ORG_NAME-test.apigee.net/hellooauth2
از آنجا که پروکسی API دارای سیاست Verify OAuth v2.0 Access Token است که توکن OAuth معتبر را در درخواست بررسی میکند، فراخوانی باید با پیام زیر ناموفق باشد:
{"fault":{"faultstring":"Invalid access token","detail":{"errorcode":"oauth.v2.InvalidAccessToken"}}}در این مورد، شکست خوب است! این به این معنی است که پروکسی API شما بسیار امنتر است. فقط برنامههای قابل اعتماد با یک توکن دسترسی OAuth معتبر میتوانند با موفقیت این API را فراخوانی کنند.
دریافت توکن دسترسی OAuth
حالا به نتیجهی نهایی میرسیم. شما در شرف استفاده از کلید و رمزی هستید که کپی و در یک فایل متنی پیست کردهاید و آنها را با یک توکن دسترسی OAuth جایگزین میکنید. اکنون قرار است یک فراخوانی API به پروکسی نمونه API که وارد کردهاید، oauth ، انجام دهید که یک توکن دسترسی API ایجاد میکند.
با استفاده از آن کلید و رمز، فراخوانی cURL زیر را انجام دهید (توجه داشته باشید که پروتکل https است)، و نام سازمان Edge، کلید و رمز خود را در جایی که مشخص شده است جایگزین کنید:
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \ "https://ORG_NAME-test.apigee.net/oauth/client_credential/accesstoken?grant_type=client_credentials" \ -d "client_id=CLIENT_KEY&client_secret=CLIENT_SECRET"
توجه داشته باشید که اگر از کلاینتی مانند Postman برای برقراری تماس استفاده میکنید، client_id و client_secret در بدنه درخواست قرار میگیرند و باید با x-www-form-urlencoded باشند.
شما باید پاسخی شبیه به این دریافت کنید:
{ "issued_at" : "1466025769306", "application_name" : "716bbe61-f14a-4d85-9b56-a62ff8e0d347", "scope" : "", "status" : "approved", "api_product_list" : "[helloworld_oauth2-Product]", "expires_in" : "3599", //--in seconds "developer.email" : "nigel@example.com", "token_type" : "BearerToken", "client_id" : "xNnREu1DNGfiwzQZ5HUN8IAUwZSW1GZW", "access_token" : "GTPY9VUHCqKVMRB0cHxnmAp0RXc0", "organization_name" : "myOrg", "refresh_token_expires_in" : "0", //--in seconds "refresh_count" : "0" }
شما توکن دسترسی OAuth خود را دریافت کردید! مقدار access_token را (بدون علامت نقل قول) کپی کرده و در فایل متنی خود قرار دهید. در یک لحظه از آن استفاده خواهید کرد.
چی شد؟
یادتان هست قبلاً به جریان شرطی در پروکسی oauth نگاه کردید، همان جریانی که میگفت اگر URI منبع /accesstoken و فعل درخواست POST باشد، باید سیاست OAuth مربوط GenerateAccessTokenClient که یک توکن دسترسی تولید میکند، اجرا شود؟ دستور cURL شما این شرایط را داشت، بنابراین سیاست OAuth اجرا شد. این دستور کلید مصرفکننده و رمز مصرفکننده شما را تأیید کرد و آنها را با یک توکن OAuth که ظرف ۱ ساعت منقضی میشود، جایگزین کرد.
فراخوانی API با استفاده از توکن دسترسی (موفقیت!)
حالا که یک توکن دسترسی دارید، میتوانید از آن برای فراخوانی پروکسی API استفاده کنید. فراخوانی cURL زیر را انجام دهید. نام سازمان Edge و توکن دسترسی خود را جایگزین کنید.
curl https://ORG_NAME-test.apigee.net/hellooauth2 -H "Authorization: Bearer TOKEN"
اکنون باید یک فراخوانی موفق به پروکسی API داشته باشید که آدرس IP شما را برمیگرداند. برای مثال:
{"ip":"::ffff:192.168.14.136"}شما میتوانید آن فراخوانی API را نزدیک به یک ساعت تکرار کنید، پس از آن زمان توکن دسترسی منقضی میشود. برای برقراری تماس پس از یک ساعت، باید با استفاده از مراحل قبلی یک توکن دسترسی جدید ایجاد کنید.
تبریک! شما یک پروکسی API ایجاد کردهاید و با الزام به درج یک توکن دسترسی معتبر OAuth در فراخوانی، از آن محافظت کردهاید.
مباحث مرتبط
- خانه OAuth
- سیاست OAuthV2
- دانلود پروکسیهای API (که نحوهی دستهبندی یک پروکسی API را در یک فایل ZIP مانند فایلی که دانلود کردهاید نشان میدهد)