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 برای هر برنامه ای که در یک سازمان ثبت شده است صادر می کند. "Credentials Client" به خود کلید مصرف کننده و جفت مخفی اشاره دارد.

برای کسب اطلاعات بیشتر درباره صدور اعتبار برای برنامه‌ها با استفاده از خدمات برنامه‌نویس 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 را تنظیم می کنید با این عملیات آشنا خواهید شد.)

خط مشی OAuthTokens از نوع OAuthV2 را تأیید کنید

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

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

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

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

برای ایجاد این خط‌مشی در رابط کاربری مدیریت، به APIs > API Proxies بروید.

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

از نمای کلی برای هواشناسی، نمای توسعه را انتخاب کنید.

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

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

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

افزودن را انتخاب کنید و خط مشی ایجاد شده و به درخواست PreFlow weatherapi پیوست می شود.

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

اگر به صورت محلی در یک ویرایشگر متن یا IDE کار می کنید، خط مشی را به درخواست 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 را که توسط پروکسی oauth API در معرض دید قرار گرفته است، فراخوانی کنند تا یک نشانه دسترسی دریافت کنند. پس از اینکه برنامه یک نشانه دسترسی داشت، می‌تواند بارها و بارها با weatherapi تماس بگیرد، تا زمانی که نشانه دسترسی منقضی شود، یا نشانه دسترسی لغو شود.

اکنون باید دنده خود را تغییر دهید تا خود را یک توسعه‌دهنده اپلیکیشن بدانید. می‌خواهید با 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 نمایه برنامه ای را که مشخص کرده اید برمی گرداند. به عنوان مثال، نمایه برنامه هواشناسی دارای نمایش 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 توجه کنید. شما از این اعتبارنامه ها برای به دست آوردن یک نشانه دسترسی با ارائه آنها به عنوان اعتبارنامه های احراز هویت اولیه در یک درخواست 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 Services کلید مصرف کننده و راز را تأیید می کند و سپس پاسخی حاوی رمز دسترسی برای این برنامه ایجاد می کند: 

{
  "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

این آدرسی است که توسعه دهندگان برای به دست آوردن نشانه های دسترسی با آن تماس می گیرند.

تنظیمات OAuth سه پایه

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

OAuth 1.0a

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

کمک بگیرید

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