استفاده از OAuth2 برای دسترسی به Edge API

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

‫Apigee Edge به شما امکان می‌دهد تماس‌های Edge API را که با کد OAuth2 اصالت‌سنجی شده‌اند برقرار کنید. پشتیبانی از OAuth2 به‌طور پیش‌فرض در Edge برای حساب‌های Cloud فعال است. اگر از Edge برای «ابر خصوصی» استفاده می‌کنید، نمی‌توانید بدون ابتدا راه‌اندازی SAML یا LDAP از OAuth2 استفاده کنید.

نحوه عملکرد OAuth2 (با Apigee Edge API)

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

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

https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

اما نمی‌توانید فقط آن درخواست را بدون اینکه به ما بگویید چه کسی هستید ارسال کنید. درغیراین‌صورت، هرکسی می‌تواند جزئیات سازمانتان را ببیند.

اینجا است که OAuth2 وارد می‌شود: برای اصالت‌سنجی شما، باید کد دسترسی را نیز در آن درخواست برای ما ارسال کنید. کد دسترسی به ما می‌گوید شما چه کسی هستید تا مطمئن شویم که مجاز به دیدن جزئیات سازمان هستید.

خوشبختانه، می‌توانید با ارسال اطلاعات اعتباری خود به سرویس Edge OAuth2 کد دریافت کنید. این سرویس با کدهای دسترسی و بازآوری پاسخ می‌دهد.

جریان OAuth2: درخواست اولیه

تصویر زیر جریان OAuth2 را هنگام دسترسی به Edge API برای اولین‌بار نشان می‌دهد:

جریان OAuth: اولین درخواست
شکل ۱: جریان OAuth: اولین درخواست

همان‌طور که شکل ۱ نشان می‌دهد، وقتی درخواست اولیه خود را به Edge API ارسال می‌کنید:

  1. کد دسترسی درخواست می‌کنید. می‌توانید این کار را با Edge API، acurl، یا get_token انجام دهید. برای مثال: 
    get_token
Enter username:
ahamilton@apigee.com
Enter the password for user 'ahamilton@apigee.com'
[hidden input]
Enter the six-digit code if 'ahamilton@apigee.com' is MFA enabled or press ENTER:
123456
  2. سرویس Edge OAuth2 با یک کد دسترسی پاسخ می‌دهد و آن را در stdout چاپ می‌کند؛ برای مثال: 
    Dy42bGciOiJSUzI1NiJ9.eyJqdGkiOiJhM2YwNjA5ZC1lZTIxLTQ1YjAtOGQyMi04MTQ0MTYxNjNhNTMiLCJz
AJpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNsaSIsIm
NjbGkiLCJhenAiOiJlZGdlY2xpIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjJkMWU3NDI
GzQyMC1kYzgxLTQzMDQtOTM4ZS1hOGNmNmVlODZhNzkiLCJzY29wZSI6WyJzY2ltLm1lIiwib3BlbmlkIiwic
ENC05MzhlLWE4Y2Y2ZWU4NmE3OSIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoiZGFuZ2VyNDI0
RI6ImUyNTM2NWQyIiwiaWF0IjoxNTI4OTE2NDA5LCJleHAiOjE1Mjg5MTgyMDksImlzcyI6Imh0dHBzOi8vbG
420iLCJlbWFpbCI6ImRhbmdlcjQyNDJAeWFob28uY29tIiwiYXV0aF90aW1lIjoxNTI4OTE2NDA5LCJhbCI6M
2lLmNvbSIsInppZCI6InVhYSIsImF1ZCI6WyJlZGdlY2xpIiwic2NpbSIsIm9wZW5pZCIsInBhc3N3b3JkIiw

    برنامه‌های کمکی acurl و get_token کد دسترسی و کد بازآوری را به‌طور بی‌صدا در ~/.sso-cli ذخیره می‌کنند (کد بازآوری در stdout نوشته نمی‌شود). اگر از سرویس Edge OAuth2 برای دریافت کدها استفاده می‌کنید، باید آن‌ها را برای استفاده بعدی خودتان ذخیره کنید.

  3. درخواستی را با کد دسترسی به Edge API ارسال می‌کنید. ‫acurl به‌طور خودکار نشان را پیوست می‌کند؛ برای مثال: 
    acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

    اگر از کارخواه HTTP دیگری استفاده می‌کنید، حتماً کد دسترسی را اضافه کنید. برای مثال:

    curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"
  4. ‫Edge API درخواست شما را اجرا می‌کند و معمولاً پاسخی حاوی داده برمی‌گرداند.

جریان OAuth2: درخواست‌های بعدی

در درخواست‌های بعدی، نیازی به تبدیل اطلاعات اعتباری خود به کد ندارید. درعوض، می‌توانید فقط کد دسترسی‌ای را که ازقبل دارید اضافه کنید، به‌شرطی که هنوز منقضی نشده باشد:

جریان OAuth: درخواست‌های بعدی
شکل ۲: جریان OAuth: درخواست‌های بعدی

همان‌طور که شکل ۲ نشان می‌دهد، وقتی ازقبل یک کد دسترسی دارید:

  1. درخواستی را با کد دسترسی به Edge API ارسال می‌کنید. ‫acurl به‌طور خودکار نشان را پیوست می‌کند. اگر از ابزارهای دیگری استفاده می‌کنید، باید نشان را به‌صورت دستی اضافه کنید.
  2. ‫Edge API درخواست شما را اجرا می‌کند و معمولاً پاسخی حاوی داده برمی‌گرداند.

جریان OAuth2: وقتی کد دسترسی شما منقضی می‌شود

وقتی کد دسترسی منقضی می‌شود (پس‌از ۱۲ ساعت)، می‌توانید از کد بازآوری برای دریافت کد دسترسی جدید استفاده کنید:

جریان OAuth: درحال بازآوری کد دسترسی
شکل ۳: جریان OAuth: بازآوری کد دسترسی

همان‌طور که شکل ۳ نشان می‌دهد، وقتی کد دسترسی شما منقضی شده است:

  1. درخواستی را به Edge API ارسال می‌کنید، اما کد دسترسی شما منقضی شده است.
  2. ‫Edge API درخواست شما را به‌عنوان غیرمجاز رد می‌کند.
  3. یک کد نوسازی به سرویس Edge OAuth2 ارسال می‌کنید. اگر از acurl استفاده می‌کنید، این کار به‌طور خودکار برای شما انجام می‌شود.
  4. سرویس Edge OAuth2 با یک کد دسترسی جدید پاسخ می‌دهد.
  5. درخواستی را با رمز دسترسی جدید به Edge API ارسال می‌کنید.
  6. ‫Edge API درخواست شما را اجرا می‌کند و معمولاً پاسخی حاوی داده برمی‌گرداند.

دریافت کدها

برای دریافت کد دسترسی که می‌توانید به Edge API ارسال کنید، می‌توانید از ابزارهای کمکی Apigee زیر، علاوه‌بر ابزاری کمکی مثل curl، استفاده کنید:

  • ابزار get_token: اطلاعات اعتباری Apigee شما را با توکن‌های دسترسی و بازآوری که می‌توانید برای فراخوانی Edge API استفاده کنید مبادله می‌کند.
  • ابزار acurl: یک پوشش راحت برای فرمان استاندارد curl ارائه می‌دهد. درخواست‌های HTTP را برای Edge API می‌سازد، از get_token کد دسترسی و کد بازآوری دریافت می‌کند، و کد دسترسی را به Edge API ارسال می‌کند.
  • نقطه‌های پایان کد در سرویس Edge OAuth2: اعتبارنامه‌های Apigee خود را ازطریق تماس با Edge API با کدهای دسترسی و بازآوری مبادله کنید.

این ابزارها اعتبارنامه‌های حساب Apigee شما (نشانی ایمیل و گذرواژه) را با نشانه‌هایی با مدت زمان‌های زیر مبادله می‌کنند:

  • رمزهای دسترسی ظرف ۱۲ ساعت منقضی می‌شود.
  • نشان‌های بازآوری ظرف ۳۰ روز منقضی می‌شوند.

درنتیجه، پس‌از اینکه با acurl یا get_token فراخوانی API را باموفقیت انجام دادید، می‌توانید تا ۳۰ روز از جفت کد استفاده کنید. پس‌از انقضا، باید اعتبارنامه‌هایتان را دوباره وارد کنید و نشان‌های جدید دریافت کنید.

دسترسی به Edge API با OAuth2

برای دسترسی به Edge API، درخواستی را به نقطه پایانی API ارسال می‌کنید و کد دسترسی را اضافه می‌کنید. می‌توانید این کار را با هر کارخواه HTTP، ازجمله ابزار خط فرمان مثل curl، واسط کاربر مبتنی بر مرورگر مثل Postman، یا ابزار Apigee مثل acurl انجام دهید.

دسترسی به Edge API با acurl و با curl در بخش‌های زیر توضیح داده شده است.

استفاده از acurl

برای دسترسی به Edge API با acurl، درخواست اولیه شما باید شامل اطلاعات اعتباری شما باشد. سرویس Edge OAuth2 با ژتون‌های دسترسی و بازآوری پاسخ می‌دهد. ‫acurl کدها را به‌صورت محلی ذخیره می‌کند.

در درخواست‌های بعدی، acurl از نشان‌های ذخیره‌شده در ~/.sso-cli استفاده می‌کند تا لازم نباشد اطلاعات اعتباری‌تان را دوباره وارد کنید تا زمانی که نشان‌ها منقضی شوند.

مثال زیر درخواست اولیه acurl را نشان می‌دهد که جزئیات سازمان «ahamilton-eval» را دریافت می‌کند:

acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -u ahamilton@apigee.com
Enter the password for user 'ahamilton@apigee.com'
[hidden input]
Enter the six-digit code (no spaces) if 'ahamilton@apigee.com' is MFA-enabled or press ENTER:
1a2b3c
{
  "createdAt" : 1491854501264,
  "createdBy" : "noreply_iops@apigee.com",
  "displayName" : "ahamilton",
  "environments" : [ "prod", "test" ],
  "lastModifiedAt" : 1491854501264,
  "lastModifiedBy" : "noreply_iops@apigee.com",
  "name" : "ahamilton",
  "properties" : {
    "property" : [ {
      "name" : "features.isSmbOrganization",
      "value" : "false"
    }, {
      "name" : "features.isCpsEnabled",
      "value" : "true"
    } ]
  },
  "type" : "trial"
}

acurl https://api.enterprise.apigee.com/v1/o/ahamilton-eval/apis/helloworld/revisions/1/policies

[ "SOAP-Message-Validation-1", "Spike-Arrest-1", "XML-to-JSON-1" ]

علاوه‌بر دریافت جزئیات درباره سازمان، این مثال درخواست دومی را نیز نشان می‌دهد که فهرستی از خط‌مشی‌ها را در پراکسی API «helloworld» دریافت می‌کند. درخواست دوم از کوته‌سازی «o» برای «organizations» در نشانی وب استفاده می‌کند.

توجه داشته باشید که acurl به‌طور خودکار در درخواست دوم، رمز دسترسی را ارسال می‌کند. وقتی acurl نشان‌های OAuth2 را ذخیره کرد، دیگر لازم نیست اطلاعات اعتباری کاربرتان را ارسال کنید. برای تماس‌های بعدی، نشان را از ~/.sso-cli دریافت می‌کند.

برای اطلاعات بیشتر، استفاده از acurl برای دسترسی به Edge API را ببینید.

استفاده از curl

می‌توانید از curl برای دسترسی به Edge API استفاده کنید. برای انجام این کار، ابتدا باید به کد دسترسی و کد بازآوری دسترسی پیدا کنید. می‌توانید این موارد را بااستفاده از ابزاری مانند get_token یا سرویس Edge OAuth2 دریافت کنید.

پس‌از اینکه باموفقیت کد دسترسی‌تان را ذخیره کردید، آن را در سرصفحه Authorization تماس‌هایتان به Edge API ارسال می‌کنید، همان‌طور که در مثال زیر نشان داده شده است:

curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"

کد دسترسی تا ۱۲ ساعت پس‌از صدور معتبر است. پس‌از انقضای کد دسترسی، می‌توان از کد نوسازی به‌مدت ۳۰ روز برای صدور کد دسترسی دیگر بدون نیاز به اطلاعات اعتباری استفاده کرد. ‫Apigee توصیه می‌کند که به‌جای وارد کردن اطلاعات اعتباری و ایجاد درخواست جدید با هر تماس API، فقط پس‌از منقضی شدن کد نوسازی، کد دسترسی جدید درخواست کنید.

انقضای کد

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

نحوه بازآوری کردن کد دسترسی به ابزاری که استفاده می‌کنید بستگی دارد:

  • ‫acurl: اقدامی لازم نیست. وقتی درخواستی حاوی رمز دسترسی منسوخ‌شده ارسال می‌کنید، acurl به‌طور خودکار رمز دسترسی را بازآوری می‌کند.
  • get_token: برای بازآوری کد دسترسی، با get_token تماس بگیرید.
  • سرویس Edge OAuth2: درخواستی ارسال کنید که شامل موارد زیر باشد:
    • ژتون بازآوری
    • پارامتر فرم grant_type روی «refresh_token» تنظیم شد

‫OAuth2 برای کاربران ماشین

می‌توانید از ابزارهای acurl و get_token برای نوشتن دستورگان دسترسی خودکار به «میاناهای برنامه‌سازی کاربردی Edge» با اصالت‌سنجی OAuth2 برای کاربران ماشین استفاده کنید. مثال زیر نحوه استفاده از get_token برای درخواست کردن کد دسترسی و سپس افزودن مقدار کد به تماس curl را نشان می‌دهد:

  USER=me@example.com
  PASS=not-that-secret
  TOKEN=$(get_token -u $USER:$PASS -m '')
  curl -H "Authorization: Bearer $TOKEN" 'https://api.enterprise.apigee.com/v1/organizations/...'

یا می‌توانید درخواست کد و curl تماس را بااستفاده از ابزار acurl ترکیب کنید. برای مثال:

  USER=me@example.com
  PASS=not-that-secret
  acurl -u $USER:$PASS -m '' 'https://api.enterprise.apigee.com/v1/organizations/...'

در هر دو مثال، تنظیم مقدار -m روی رشته خالی باعث می‌شود کاربر ماشین برای دریافت کد «احراز هویت چندعاملی» درخواست نشود.