OAuth

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

OAuth به عنوان پروتکل پیشرو در احراز هویت برای APIها ظهور کرده است. نسخه‌ای از OAuth که در این مبحث به تفصیل پوشش داده شده است، در ... تعریف شده است. مشخصات OAuth 2.0

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

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

پیکربندی پیش‌فرض OAuth برای سازمان شما

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

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

به همین دلیل، «ارتقاء» طرح امنیتی API شما از اعتبارسنجی کلید API به اعتبارنامه‌های کلاینت OAuth نسبتاً ساده است. هر دو طرح از کلید مصرف‌کننده و رمز عبور یکسانی برای اعتبارسنجی برنامه کلاینت استفاده می‌کنند. تفاوت این است که اعتبارنامه‌های کلاینت یک لایه کنترل اضافی فراهم می‌کنند، زیرا می‌توانید به راحتی در صورت نیاز، یک توکن دسترسی را لغو کنید، بدون اینکه نیازی به لغو کلید مصرف‌کننده برنامه داشته باشید. برای کار با نقاط پایانی پیش‌فرض OAuth، می‌توانید از هر کلید مصرف‌کننده و رمز عبوری که برای برنامه در سازمان شما ایجاد شده است، برای بازیابی توکن‌های دسترسی از نقطه پایانی توکن استفاده کنید. (حتی می‌توانید اعتبارنامه‌های کلاینت را برای برنامه‌هایی که از قبل کلیدها و رمزهای عبور مصرف‌کننده دارند، فعال کنید.)

مشخصات کامل اعطای اعتبارنامه‌های کلاینت را می‌توانید در مشخصات OAuth 2.0 بیابید.

با یک سیاست از API خود محافظت کنید

قبل از اینکه بتوانید از توکن‌های دسترسی استفاده کنید، باید APIهای خود را برای اعتبارسنجی توکن‌های دسترسی OAuth در زمان اجرا پیکربندی کنید. برای انجام این کار ، یک پروکسی API را برای اعتبارسنجی توکن‌های دسترسی پیکربندی می‌کنید. این بدان معناست که هر بار که یک برنامه درخواستی برای استفاده از یکی از APIهای شما ارسال می‌کند، برنامه باید یک توکن دسترسی معتبر را همراه با درخواست API ارائه دهد. Apigee Edge پیچیدگی‌های مربوط به تولید، ذخیره‌سازی و اعتبارسنجی توکن‌های دسترسی ارائه شده را مدیریت می‌کند.

شما می‌توانید به راحتی هنگام ایجاد یک پروکسی API جدید، تأیید OAuth را به یک API اضافه کنید. هنگام ایجاد یک پروکسی API جدید، می‌توانید ویژگی‌ها را اضافه کنید . همانطور که در زیر نشان داده شده است، می‌توانید با انتخاب دکمه رادیویی کنار Secure with OAuth v2.0 Access Tokens، تأیید توکن‌های دسترسی OAuth 2.0 را اضافه کنید. وقتی این گزینه را انتخاب می‌کنید، دو سیاست به پروکسی API تازه ایجاد شده پیوست می‌شوند، یکی برای تأیید توکن‌های دسترسی و دیگری برای حذف توکن دسترسی پس از تأیید آن.

علاوه بر این، وقتی گزینه Secure with OAuth v2.0 Access Tokens را انتخاب می‌کنید، کادر انتخاب Publish API Product قابل انتخاب می‌شود و به طور خودکار انتخاب می‌شود. اگر می‌خواهید هنگام ساخت پروکسی API جدید، به طور خودکار محصولی تولید شود، این گزینه را علامت بزنید. محصول تولید شده خودکار با ارتباط با پروکسی API جدید ایجاد می‌شود. اگر محصولی از قبل دارید که می‌خواهید این API جدید را با آن مرتبط کنید، حتماً این کادر انتخاب را بردارید تا محصولی غیرضروری ایجاد نکنید. برای اطلاعات بیشتر در مورد محصولات، به «محصول API چیست؟» مراجعه کنید.

اگر نیاز دارید که تأیید توکن دسترسی را برای پروکسی API موجود فعال کنید، تنها کاری که باید انجام دهید این است که یک سیاست از نوع OAuthV2 را به API که می‌خواهید محافظت کنید، پیوست کنید. سیاست‌های OAuthV2 با مشخص کردن یک عملیات کار می‌کنند. اگر می‌خواهید توکن‌های دسترسی را تأیید کنید، عملیاتی به نام VerifyAccessToken را مشخص می‌کنید. (انواع دیگر عملیاتی که توسط نوع سیاست OAuthV2 پشتیبانی می‌شوند، GenerateAccessToken و GenerateRefreshToken هستند. هنگام تنظیم نقاط پایانی OAuth، در مورد این عملیات‌ها اطلاعات کسب خواهید کرد.)

سیاست VerifyOAuthTokens از نوع OAuthV2

یک نمونه از سیاست اعتبارسنجی توکن‌های دسترسی به شکل زیر است. (تنظیمات در جدول زیر توضیح داده شده است.)

<OAuthV2 name="VerifyOAuthTokens">
  <Operation>VerifyAccessToken</Operation>
</OAuthV2>

تنظیمات خط‌مشی

نام توضیحات پیش‌فرض الزامی است؟
OAuthV2 نوع سیاست
name نام سیاست، که در پیکربندی API proxy Endpoint به آن ارجاع داده شده است. ناموجود بله
Operation عملیاتی که باید توسط سیاست OAuthV2 اجرا شود. با تعیین VerifyAccessToken، شما سیاست را برای بررسی درخواست‌های مربوط به توکن‌های دسترسی پیکربندی می‌کنید و تأیید می‌کنید که توکن دسترسی معتبر است، منقضی نشده است و برای مصرف منبع API درخواستی (URI) تأیید شده است. (برای انجام این بررسی، سیاست، محصول API را که برنامه برای مصرف آن تأیید شده است، می‌خواند.) ناموجود بله

برای ایجاد این سیاست در رابط کاربری مدیریت، به APIها > API Proxies بروید.

از فهرست پروکسی‌های API، weatherapi را انتخاب کنید.

از نمای کلی مربوط به weatherapi، نمای توسعه (Develop view) را انتخاب کنید.

از منوی کشویی، گزینه New Policy > OAuth v2.0 را انتخاب کنید.

پس از انتخاب سیاست OAuth نسخه ۲.۰، منوی پیکربندی سیاست جدید نمایش داده خواهد شد.

به پالیسی خود یک نام توصیفی بدهید و حتماً گزینه‌های Attach Policy ، Flow PreFlow و Request را به عنوان تنظیمات پیوست پالیسی انتخاب کنید.

گزینه Add را انتخاب کنید تا پالیسی ایجاد شده و به درخواست PreFlow از weatherapi پیوست شود.

پس از افزودن خط‌مشی، پیکربندی PreFlow درخواست زیر در پنل Designer نمایش داده می‌شود.

اگر به صورت محلی در یک ویرایشگر متن یا IDE کار می‌کنید، باید Policy را به درخواست PreFlow پروکسی API که می‌خواهید محافظت کنید، پیوست کنید:

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthTokens</Name></Step>
  </Request>
</PreFlow>

با پیوست کردن این سیاست به درخواست PreFlow، تضمین می‌کنید که این سیاست همیشه روی همه پیام‌های درخواست اعمال می‌شود.

اکنون شما یک API را با اعتبارنامه‌های کلاینت OAuth 2.0 ایمن کرده‌اید. مرحله بعدی یادگیری نحوه دریافت یک توکن دسترسی و استفاده از آن برای دسترسی به API امن است.

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

اکنون که weatherapi با OAuth 2.0 ایمن شده است، برنامه‌ها باید توکن‌های دسترسی را برای استفاده از API ارائه دهند. برای دسترسی به یک منبع محافظت‌شده، برنامه یک توکن دسترسی را در درخواست به عنوان یک هدر HTTP "Authorization" به شرح زیر ارائه می‌دهد:

$ curl -H "Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

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

اما برنامه‌ها چگونه توکن‌های دسترسی را دریافت می‌کنند؟ در بخش بعدی به این موضوع خواهیم پرداخت.

نحوه تبادل اعتبارنامه‌های کلاینت با توکن دسترسی

برنامه‌ها با ارائه جفت کلید/رمز مصرف‌کننده خود به نقطه پایانی توکن، توکن‌های دسترسی را به دست می‌آورند. نقطه پایانی توکن در پروکسی API به نام oauth پیکربندی شده است. بنابراین برنامه‌ها برای دریافت توکن دسترسی باید API ارائه شده توسط پروکسی API oauth را فراخوانی کنند. پس از اینکه برنامه یک توکن دسترسی داشت، می‌تواند API weather را بارها و بارها فراخوانی کند، تا زمانی که توکن دسترسی منقضی شود یا توکن دسترسی لغو شود.

حالا باید دنده عوض کنید و خودتان را به عنوان یک توسعه‌دهنده اپلیکیشن در نظر بگیرید. شما می‌خواهید weatherapi را فراخوانی کنید، بنابراین باید یک توکن دسترسی برای اپلیکیشن خود دریافت کنید. اولین کاری که باید انجام دهید این است که یک جفت کلید مصرف‌کننده و رمز (که با نام کلید API یا کلید اپلیکیشن نیز شناخته می‌شود) دریافت کنید.

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

شما می‌توانید تمام برنامه‌های موجود در سازمان خود را در رابط کاربری مدیریتی Apigee Edge مشاهده کنید.

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

(اگر هیچ برنامه‌ای نمایش داده نشد، می‌توانید نحوه ثبت یک برنامه را در مبحثی با عنوان ثبت برنامه‌ها و مدیریت کلیدهای API بیاموزید.)

برای مشاهده مشخصات دقیق یک برنامه، آن را از لیست انتخاب کنید.

در نمای جزئیات برنامه‌ای که انتخاب کرده‌اید، به فیلدهای Consumer Key و Consumer Secret توجه کنید. این دو مقدار، اطلاعات احراز هویت کلاینت هستند که برای دریافت توکن دسترسی OAuth از آنها استفاده خواهید کرد. 

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps \
-u myname:mypass

این فراخوانی لیستی از برنامه‌ها را بر اساس شناسه برنامه برمی‌گرداند.

[ "da496fae-2a04-4a5c-b2d0-709278a6f9db", "50e3e831-175b-4a05-8fb6-05a54701af6e" ]

شما می‌توانید با یک فراخوانی ساده‌ی GET روی شناسه‌ی برنامه، پروفایل آن را بازیابی کنید:

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/{app_id} \
-u myname:mypass

برای مثال:

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/da496fae-2a04-4a5c-b2d0-709278a6f9db \
-u myname:mypass

فراخوانی API، پروفایل برنامه‌ای که مشخص کرده‌اید را برمی‌گرداند. برای مثال، یک پروفایل برنامه برای weatherapp دارای نمایش JSON زیر است:

{
  "accessType" : "read",
  "apiProducts" : [ ],
  "appFamily" : "default",
  "appId" : "da496fae-2a04-4a5c-b2d0-709278a6f9db",
  "attributes" : [ ],
  "callbackUrl" : "http://weatherapp.com",
  "createdAt" : 1380290158713,
  "createdBy" : "noreply_admin@apigee.com",
  "credentials" : [ {
    "apiProducts" : [ {
      "apiproduct" : "PremiumWeatherAPI",
      "status" : "approved"
    } ],
    "attributes" : [ ],
    "consumerKey" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
    "consumerSecret" : "hAr4Gn0gA9vAyvI4",
    "expiresAt" : -1,
    "issuedAt" : 1380290161417,
    "scopes" : [ ],
    "status" : "approved"
  } ],
  "developerId" : "5w95xGkpnjzJDBT4",
  "lastModifiedAt" : 1380290158713,
  "lastModifiedBy" : "noreply_admin@apigee.com",
  "name" : "weatherapp",
  "scopes" : [ ],
  "status" : "approved"
}

به مقادیر consumerKey و consumerSecret توجه کنید. شما از این اعتبارنامه‌ها برای دریافت یک access token با ارائه آنها به عنوان اعتبارنامه‌های Basic Authentication در یک درخواست HTTP، همانطور که در زیر نشان داده شده است، استفاده می‌کنید. نوع اعطای مجوز به عنوان یک پارامتر پرس و جو به درخواست ارائه می‌شود. (مطمئن شوید که مقدار متغیر {org_name} را تغییر دهید تا منعکس کننده نام سازمان شما در Apigee Edge باشد.)

ایجاد درخواست برای دریافت توکن دسترسی

در درخواست زیر، مقدار consumerKey خود را به جای client_id قرار دهید. مقدار consumerSecret مرتبط را به جای client_secret قرار دهید.

$ curl https://{org_name}-test.apigee.net/oauth/client_credential/accesstoken?grant_type=client_credentials -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K&client_secret=hAr4Gn0gA9vAyvI4'

سرویس‌های API کلید و رمز مصرف‌کننده را تأیید می‌کنند و سپس پاسخی حاوی توکن دسترسی برای این برنامه تولید می‌کنند: 

{
  "issued_at" : "1380892555397",
  "application_name" : "957aa73f-25c2-4ead-8021-adc01f0d2c6b",
  "scope" : "",
  "status" : "approved",
  "api_product_list" : "[oauth-test]",
  "expires_in" : "3599",
  "developer.email" : "tesla@weathersample.com",
  "organization_id" : "0",
  "client_id" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
  "access_token" : "ylSkZIjbdWybfs4fUQe9BqP0LH5Z",
  "organization_name" : "rqa",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

به مقدار access_token در پاسخ بالا توجه کنید. این توکن دسترسی است که برنامه برای دسترسی در زمان اجرا به منابع محافظت‌شده از آن استفاده خواهد کرد. توکن دسترسی برای این برنامه ylSkZIjbdWybfs4fUQe9BqP0LH5Z است.

اکنون یک توکن دسترسی معتبر به نام ylSkZIjbdWybfs4fUQe9BqP0LH5Z دارید که می‌تواند برای دسترسی به APIهای محافظت‌شده استفاده شود.

کار با پیکربندی پیش‌فرض OAuth

هر سازمان (حتی یک سازمان آزمایشی رایگان) در Apigee Edge به یک نقطه پایانی توکن OAuth مجهز شده است. این نقطه پایانی با سیاست‌هایی در پروکسی API به نام oauth از پیش پیکربندی شده است. می‌توانید به محض ایجاد حساب کاربری در Apigee Edge ، استفاده از نقطه پایانی توکن را شروع کنید.

نقطه پایانی پیش‌فرض OAuth، آدرس اینترنتی (URI) نقطه پایانی زیر را نمایش می‌دهد: 

/oauth/client_credential/accesstoken

این URI را برای توسعه‌دهندگانی که نیاز به دریافت توکن‌های دسترسی دارند منتشر کنید. توسعه‌دهندگان برنامه، برنامه‌های خود را برای فراخوانی این نقطه پایانی پیکربندی می‌کنند و جفت‌های کلید مصرف‌کننده و رمز خود را برای دریافت توکن‌های دسترسی ارائه می‌دهند.

نقطه پایانی توکن اعتبارنامه‌های پیش‌فرض کلاینت از طریق شبکه و در آدرس اینترنتی زیر در معرض نمایش قرار می‌گیرد: 

https://{org_name}-{env_name}.apigee.net/oauth/client_credential/accesstoken

برای مثال، اگر نام سازمان شما "apimakers" باشد، آدرس اینترنتی (URL) به صورت زیر خواهد بود: 

https://apimakers-test.apigee.net/oauth/client_credential/accesstoken

این URL ای است که توسعه دهندگان برای دریافت توکن های دسترسی فراخوانی می کنند.

پیکربندی‌های OAuth سه‌گانه

پیکربندی‌های OAuth سه‌گانه ( کد مجوز، انواع اعطای ضمنی و رمز عبور ) شما، به عنوان ارائه‌دهنده API، را ملزم به احراز هویت کاربران نهایی برنامه می‌کند. از آنجایی که هر سازمانی کاربران را به روش‌های مختلفی احراز هویت می‌کند، برای ادغام OAuth با مخزن کاربران شما، به برخی سفارشی‌سازی‌های سیاست یا کد نیاز است. به عنوان مثال، ممکن است همه کاربران شما در Active Directory، در یک LDAP یا برخی دیگر از مخازن کاربران ذخیره شده باشند. برای راه‌اندازی و اجرای OAuth سه‌گانه، باید بررسی این مخزن کاربران را در جریان کلی OAuth ادغام کنید.

OAuth نسخه ۱.۰a

برای جزئیات بیشتر در مورد سیاست OAuth 1.0a، به سیاست OAuth v1.0a مراجعه کنید.

کمک بگیرید

برای راهنمایی، به پشتیبانی مشتریان Apigee مراجعه کنید.