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

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

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

نحوه کار OAuth2 (با API Apigee Edge)

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

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

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

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

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

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

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

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

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

همانطور که شکل 1 نشان می‌دهد، وقتی درخواست اولیه خود را به 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: درخواست‌های بعدی

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

  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 ارسال کنید، می‌توانید علاوه بر ابزاری مانند curl ، از ابزارهای Apigee زیر نیز استفاده کنید:

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

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

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

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

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

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

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

از آکورل استفاده کنید

برای دسترسی به 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" در URL استفاده می‌کند.

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

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

از حلقه استفاده کنید

شما می‌توانید 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 برای اسکریپت‌نویسی دسترسی خودکار به APIهای 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 ‎ به یک رشته خالی، از درخواست کد MFA از کاربر ماشین جلوگیری می‌کند.