درحال مشاهده اسناد Apigee Edge هستید.
به
اسناد Apigee X بروید. اطلاعات
آنچه خواهید آموخت
- بارگیری و استقرار یک پراکسی میانای برنامهسازی کاربردی نمونه.
- ایجاد پراکسی میانای برنامهسازی کاربردی محافظتشده با OAuth.
- محصول، توسعهدهنده، و برنامهای ایجاد کنید.
- اعتبارنامهها را با کد دسترسی OAuth مبادله کنید.
- با کد دسترسی، میانای برنامهسازی کاربردی را فراخوانی کنید.
این آموزش نحوه ایمن کردن یک API با OAuth 2.0 را نشان میدهد.
OAuth یک پروتکل مجوز است که به برنامهها امکان میدهد ازطرف کاربران به اطلاعات دسترسی پیدا کنند بدون اینکه کاربران مجبور باشند نام کاربری و گذرواژه خود را فاش کنند.
با OAuth، اعتبارنامههای امنیتی (مثل نام کاربری/گذرواژه یا کلید/رمز) با ژتون دسترسی مبادله میشود. برای مثال:
joe:joes_password (نام کاربری:گذرواژه) یا
Nf2moHOASMJeUmXVdDhlMbPaXm2U7eMc:unUOXYpPe74ZfLEb (کلید:رمز)
به چیزی شبیه این تبدیل میشود:
b0uiYwjRZLEo4lEu7ky2GGxHkanN
رمز دسترسی رشتهای تصادفی از نویسهها است و موقتی است (باید پساز مدت نسبتاً کوتاهی منقضی شود)، بنابراین انتقال آن برای اصالتسنجی کاربر در گردش کار برنامه بسیار ایمنتر از انتقال اطلاعات اعتباری واقعی است.
مشخصات OAuth 2.0 مکانیسمهای مختلفی را برای توزیع کردن کدهای دسترسی برای برنامهها تعریف میکند که «انواع اعطا» نامیده میشوند. پایهایترین نوع اعطا که توسط OAuth 2.0 تعریف شده است «اعتبارنامههای کارخواه» نامیده میشود. در این نوع اعطا، ژتونهای دسترسی OAuth در ازای اعتبارنامههای کارخواه تولید میشوند، که جفتهای کلید مصرفکننده/رمز مصرفکننده هستند، مانند مثال بالا.
نوع اعطای اطلاعات اعتباری کارخواه در Edge بااستفاده از خطمشیها در پراکسیهای API پیادهسازی میشود. جریان OAuth معمولی شامل دو مرحله است:
- برای تولید نمودار دسترسی OAuth از اطلاعات اعتباری کارخواه، کارگزار میانای برنامهسازی کاربردی ۱ را فراخوانی کنید. خطمشی OAuth v2.0 در پراکسی API این کار را انجام میدهد.
- برای ارسال کد دسترسی OAuth در تماس با میانای برنامهسازی کاربردی، کارگزار میانای برنامهسازی کاربردی ۲ را فراخوانی کنید. میانای برنامهسازی کاربردی پراکسی کد دسترسی را بااستفاده از خطمشی OAuth v2.0 درستیسنجی میکند.
آنچه نیاز خواهید داشت
- حساب Apigee Edge. اگر هنوز حساب ندارید، میتوانید با دنبال کردن دستورالعملهای ایجاد حساب Apigee Edge ثبتنام کنید.
- cURL نصبشده روی ماشین شما برای برقراری تماسهای API از خط فرمان.
بارگیری و پیادهسازی میانای برنامهسازی کاربردی پراکسی تولیدکننده کد
در این مرحله، کارگزار نیابتی میانای برنامهسازی کاربردی را ایجاد میکنید که از کلید مصرفکننده و رمز مصرفکننده ارسالشده در فراخوانی میانای برنامهسازی کاربردی، یک کد دسترسی OAuth تولید میکند. Apigee یک پراکسی API نمونه ارائه میدهد که این کار را انجام میدهد. اکنون کارگزار نیابتی را بارگیری و مستقر میکنید، سپس از آن در آموزش گامبهگام استفاده میکنید. (میتوانید خودتان بهراحتی این پراکسی API را بسازید. این مرحله بارگیری و استقرار برای راحتی شما است و برای نشان دادن اینکه همرسانی پراکسیهایی که قبلاً ایجاد شدهاند چقدر آسان است.)
- فایل ZIP نمونه کارگزار میانای برنامهسازی کاربردی «oauth» را در هر دایرکتوری در سیستم فایل بارگیری کنید.
- به https://apigee.com/edge بروید و به سیستم وارد شوید.
- در نوار پیمایش سمت راست، توسعه > پراکسیهای API را انتخاب کنید.
- روی + پراکسی کلیک کنید.

- در دستیار ایجاد پراکسی، روی بارگذاری بسته پراکسی کلیک کنید.
- فایل
oauth.zipبارگیریشده را انتخاب کنید و روی بعدی کلیک کنید. - روی ایجاد کردن کلیک کنید.
- پساز تکمیل ساخت، روی ویرایش پراکسی کلیک کنید تا پراکسی جدید را در ویرایشگر پراکسی API مشاهده کنید.
- در صفحه «نمای کلی» ویرایشگر «پراکسی API»، روی منو کرکرهای استقرار کلیک کنید
و آزمایش را انتخاب کنید. این محیط آزمایشی در سازمان شما است.

در پیامواره تأیید، روی استقرار کلیک کنید.
وقتی دوباره روی منو کرکرهای «استقرار» کلیک کنید، نماد سبزی نشان میدهد که کارگزار در محیط آزمایش مستقر شده است.

عالی بود! کارگزار API تولیدکننده کد دسترسی را باموفقیت در سازمان Edge خود بارگیری و پیادهسازی کردید.
مشاهده جریان و خطمشی OAuth
بیایید نگاهی دقیقتر به محتوای پراکسی API بیندازیم.
- در ویرایشگر پراکسی API، روی زبانه توسعه کلیک کنید. در قاب سمت راست
Navigator، دو خطمشی را خواهید دید. همچنین دو جریان
POSTدر بخشProxy Endpointsخواهید دید. -
روی AccessTokenClientCredential در زیر
Proxy Endpointsکلیک کنید.

در نمای کد 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 انجام دهید. در مراحل بعدی، از این پراکسی میانای برنامهسازی کاربردی برای تولید کد دسترسی OAuth استفاده خواهید کرد. اما ابتدا باید چند کار دیگر انجام دهید:
- پراکسی میانای برنامهسازی کاربردی را که واقعاً میخواهید با OAuth ایمن کنید ایجاد کنید.
- چند آرتیفکت دیگر ایجاد کنید که منجر به کلید مصرفکننده و رمز مصرفکننده موردنیاز برای تبادل با رمز دسترسی شود.
ایجاد پراکسی API محافظتشده با OAuth
اکنون باید پراکسی API را که میخواهید محافظت کنید ایجاد کنید. این فراخوانی API چیزی را که میخواهید برمیگرداند. در این مورد، کارگزار API سرویس mocktarget مربوط به Apigee را فراخوانی میکند تا نشانی IP شما را برگرداند. اما، تنها درصورتی میتوانید آن را ببینید که یک کد دسترسی OAuth معتبر را با تماس API خود ارسال کنید.
کارگزار میانای برنامهسازی کاربردی که در اینجا ایجاد میکنید شامل خطمشیای است که وجود کد OAuth را در درخواست بررسی میکند.
- در نوار پیمایش سمت راست، توسعه > پراکسیهای API را انتخاب کنید.
- روی + پراکسی کلیک کنید.

- در دستیار ساختن پراکسی، پراکسی معکوس (رایجترین) را انتخاب کنید، و روی بعدی کلیک کنید.
- پراکسی را با موارد زیر پیکربندی کنید:
در این فیلد این کار را انجام دهید نام پراکسی وارد کنید: helloworld_oauth2مسیر پایه پروژه تغییر به:
/hellooauth2«مسیر پایه پروژه» بخشی از نشانی وبی است که برای ارسال درخواست به پراکسی میانای برنامهسازی کاربردی استفاده میشود.
میانای برنامهسازی کاربردی موجود وارد کردن:
https://mocktarget.apigee.net/ipاین عنصر نشانی وب هدفی را تعریف میکند که Apigee Edge در درخواست به پراکسی API فراخوانی میکند.
شرح وارد کنید: hello world protected by OAuth - روی بعدی کلیک کنید.
- در صفحه خطمشیهای رایج:
در این فیلد این کار را انجام دهید امنیت: صدور مجوز انتخاب کنید: OAuth 2.0 - روی بعدی کلیک کنید.
- در صفحه میزبانهای مجازی، روی بعدی کلیک کنید.
- در صفحه ساختن، مطمئن شوید که محیط آزمایش انتخاب شده باشد و روی ایجاد و استقرار کلیک کنید.
- در صفحه خلاصه، تأییدیهای میبینید که پراکسی جدید میانای برنامهسازی کاربردی شما با موفقیت ایجاد شده است و پراکسی میانای برنامهسازی کاربردی در محیط آزمایشی شما مستقر شده است.
- برای نمایش صفحه نمای کلی برای پراکسی میانای برنامهسازی کاربردی، روی ویرایش پراکسی کلیک کنید.
توجه داشته باشید که این بار پراکسی API بهطور خودکار مستقر میشود. روی منو کرکرهای «استقرار» کلیک کنید تا مطمئن شوید نقطه سبز استقراری در کنار محیط «آزمایش» وجود دارد.
مشاهده خطمشیها
بیایید نگاهی دقیقتر به آنچه ساختهاید بیندازیم.
- در ویرایشگر پراکسی API، روی زبانه توسعه کلیک کنید. خواهید دید که دو خطمشی
به جریان درخواست پراکسی API اضافه شده است:
- درستیسنجی کد دسترسی OAuth v2.0 – تماس با میانای برنامهسازی کاربردی را بررسی میکند تا مطمئن شود کد OAuth معتبری وجود دارد.
- حذف کردن مجوز سرایند – خطمشی AssignMessage که پساز بررسی کردن رمز دسترسی، آن را برمیدارد تا به سرویس هدف منتقل نشود. (اگر سرویس هدف به کد دسترسی OAuth نیاز داشته باشد، از این خطمشی استفاده نمیکنید).
-
در نمای جریان، روی نماد درستیسنجی کردن «رمز دسترسی OAuth v2.0» کلیک کنید و به 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است. این «عملیات» تعریف میکند که خطمشی باید چه کاری انجام دهد. در این مورد، خطمشی کد OAuth معتبر را در درخواست بررسی میکند.
افزودن محصول میانای برنامهسازی کاربردی
برای افزودن محصول API بااستفاده از Apigee UI:
- انتشار > محصولات API را انتخاب کنید.
- روی +محصول API کلیک کنید.
- جزئیات محصول را برای محصول API خود وارد کنید.
فیلد شرح نام نام داخلی محصول API. نویسههای خاص را در نام مشخص نکنید.
توجه: پساز ایجاد محصول API، نمیتوانید نام آن را ویرایش کنید. برای مثال،helloworld_oauth2-Productنام نمایشی نام نمایشی محصول API. نام نمایشی در «میانای کاربر» استفاده میشود و میتوانید هرزمان بخواهید آن را ویرایش کنید. اگر مشخص نشده باشد، از مقدار «نام» استفاده خواهد شد. این فیلد بااستفاده از مقدار «نام» بهطور خودکار تکمیل میشود؛ میتوانید محتوای آن را ویرایش یا حذف کنید. نام نمایشی میتواند شامل نویسههای خاص باشد. برای مثال، helloworld_oauth2-Product.شرح شرح محصول API. محیط زیست محیطهایی که محصول API به آنها اجازه دسترسی میدهد. محیطی را که کارگزار پراکسی API را در آن مستقر کردهاید انتخاب کنید. برای مثال، test.دسترسی عمومی را انتخاب کنید. تأیید خودکار درخواستهای دسترسی تأیید خودکار درخواستهای کلید برای این محصول API از هر برنامهای را فعال کنید. سهمیه برای این آموزش گامبهگام نادیده بگیرید. محدودههای OAuth مجاز برای این آموزش گامبهگام نادیده بگیرید. - در فیلد پراکسیهای API، پراکسی API را که بهتازگی ایجاد کردهاید انتخاب کنید.
- در فیلد مسیر، «/» را وارد کنید. فیلدهای دیگر را نادیده بگیرید.
- روی ذخیره کلیک کنید.
افزودن توسعهدهنده و برنامه به سازمان
در مرحله بعد، گردش کار توسعهدهندهای را که برای استفاده از میاناهای برنامهسازی کاربردی شما ثبتنام میکند شبیهسازی خواهید کرد. در حالت ایدهآل، توسعهدهندگان خودشان و برنامههایشان را ازطریق درگاه توسعهدهنده شما ثبت میکنند. در این مرحله، توسعهدهنده و برنامهای را بهعنوان سرپرست اضافه خواهید کرد.
توسعهدهنده یک یا چند برنامه دارد که میاناهای برنامهسازی کاربردی شما را فراخوانی میکنند و هر برنامه کلید مصرفکننده و رمز مصرفکننده منحصربهفردی دریافت میکند. این کلید/رمز-بهازای-هر-برنامه همچنین به شما، ارائهدهنده API، کنترل دقیقتری بر دسترسی به APIهایتان و گزارش تحلیلی دقیقتری درباره ترافیک API میدهد، زیرا Edge میداند کدام توسعهدهنده و برنامه به کدام کد OAuth تعلق دارند.
ایجاد توسعهدهنده
بیایید توسعهدهندهای بهنام Nigel Tufnel بسازیم.
- در منو، انتشار > توسعهدهندگان را انتخاب کنید.
- روی + توسعهدهنده کلیک کنید.
- موارد زیر را در پنجره توسعهدهنده جدید وارد کنید:
در این فیلد ورود نام Nigelنام خانوادگی Tufnelنام کاربری nigelایمیل nigel@example.com - روی ایجاد کردن کلیک کنید.
ثبت برنامه
بیایید برنامهای برای نایجل بسازیم.
- منتشر کردن > برنامهها را انتخاب کنید.
- روی + برنامه کلیک کنید.
- موارد زیر را در پنجره برنامه جدید وارد کنید:
در این فیلد این کار را انجام دهید نام و نام نمایشی وارد کردن: nigel_appتوسعهدهنده روی توسعهدهنده کلیک کنید و موارد زیر را انتخاب کنید: Nigel Tufnel (nigel@example.com)نشانی وب تماس برگشتی و یادداشتها خالی بگذارید - در بخش محصولات، روی افزودن محصول کلیک کنید.
- helloworld_oauth2-Product را انتخاب کنید.
- روی ایجاد کردن کلیک کنید.
دریافت کلید مصرفکننده و رمز مصرفکننده
اکنون کلید مصرفکننده و رمز مصرفکننده را دریافت خواهید کرد که با رمز دسترسی OAuth مبادله خواهد شد.
- مطمئن شوید که صفحه nigel_app نمایش داده میشود. اگر نیست، در صفحه «برنامهها» (انتشار > برنامهها)، روی nigel_app کلیک کنید.
-
در صفحه nigel_app، در ستونهای کلید و رمز روی نمایش کلیک کنید. توجه داشته باشید که کلید/رمز با «helloworld_oauth2-Product» که قبلاً بهطور خودکار ایجاد شده است مرتبط است.
- «کلید» و «رمز» را انتخاب و کپی کنید. آنها را در یک فایل نوشتاری موقت جایگذاری کنید. از آنها در مرحله بعدی استفاده خواهید کرد، جایی که کارگزار نیابتی API را فرا میخوانید که این اطلاعات اعتباری را با یک کد دسترسی OAuth مبادله میکند.
برای دریافت نشانی IP، میانای برنامهسازی کاربردی را فراخوانی کنید (ناموفق!)
برای سرگرمی، پراکسی API محافظتشدهای را که قرار است نشانی IP شما را برگرداند
فراخوانی کنید. فرمان cURL زیر را در پنجره پایانه اجرا کنید و نام سازمان Edge خود را جایگزین کنید. کلمه test در نشانی وب محیط آزمایش سازمان شما است،
همان محیطی که کارگزاران نیابتیتان را در آن مستقر کردهاید. مسیر پایه کارگزار
/hellooauth2 است، همان مسیر پایهای که هنگام ایجاد کارگزار مشخص کردید.
توجه داشته باشید که در تماس،
کد دسترسی OAuth را ارسال نمیکنید.
curl https://ORG_NAME-test.apigee.net/hellooauth2
ازآنجاییکه کارگزار نیابتی API خطمشی درستیسنجی کد دسترسی OAuth نسخه ۲.۰ را دارد و کد OAuth معتبری را در درخواست بررسی میکند، تماس باید با پیام زیر ناموفق باشد: پیام:
{"fault":{"faultstring":"Invalid access token","detail":{"errorcode":"oauth.v2.InvalidAccessToken"}}}در این مورد، شکست خوب است! یعنی پراکسی API شما بسیار ایمنتر است. فقط برنامههای مطمئن با کد دسترسی OAuth معتبر میتوانند این «میانای برنامهسازی کاربردی» را باموفقیت فراخوانی کنند.
دریافت کد دسترسی OAuth
اکنون به پرداخت بزرگ میرسیم. قریب به استفاده از کلید و رمزی هستید که در فایل نوشتاری کپی و جایگذاری کردهاید و آنها را با رمز دسترسی OAuth مبادله میکنید. اکنون میخواهید فراخوانی میانای برنامهسازی کاربردی را برای پراکسی نمونه میانای برنامهسازی کاربردی که وارد کردهاید، oauth، انجام دهید که یک کد دسترسی میانای برنامهسازی کاربردی تولید میکند.
بااستفاده از آن کلید و رمز، تماس 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 نگاه میکردید، آن جریانی که میگفت اگر نشانی وب منبع
/accesstoken و فعل درخواست POST است،
خطمشی GenerateAccessTokenClient OAuth را که یک کد دسترسی تولید میکند اجرا کنید؟ دستور cURL شما
با آن شرایط مطابقت داشت، بنابراین خطمشی OAuth اجرا شد. کلید مصرفکننده و رمز مصرفکننده شما را درستیسنجی کرد
و آنها را با یک ژتون OAuth که ۱ ساعت دیگر منقضی میشود مبادله کرد.
تماس با میانای برنامهسازی کاربردی با کد دسترسی (موفقیتآمیز!)
اکنون که کد دسترسی دارید، میتوانید از آن برای فراخوانی پراکسی API استفاده کنید. تماس cURL زیر را برقرار کنید. نام سازمان Edge و کد دسترسی را جایگزین کنید.
curl https://ORG_NAME-test.apigee.net/hellooauth2 -H "Authorization: Bearer TOKEN"
اکنون باید تماس موفقی با پراکسی API داشته باشید که نشانی IP شما را برمیگرداند. برای مثال:
{"ip":"::ffff:192.168.14.136"}میتوانید آن تماس با میانای برنامهسازی کاربردی را تقریباً یک ساعت تکرار کنید، پساز این مدت زمان، رمز دسترسی منقضی خواهد شد. برای برقراری تماس پساز یک ساعت، باید بااستفاده از مراحل قبلی، کد دسترسی جدیدی تولید کنید.
تبریک! کارگزاری میانای برنامهسازی کاربردی ایجاد کردهاید و با الزامی کردن اینکه یک رمز دسترسی OAuth معتبر در تماس گنجانده شود، از آن محافظت کردهاید.
موضوعات مرتبط
- صفحه اصلی OAuth
- خطمشی OAuthV2
- بارگیری پراکسیهای API (که نشان میدهد چگونه یک پراکسی API را در یک فایل ZIP مانند آنچه بارگیری کردهاید دستهبندی کنید)