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

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

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

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

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

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

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

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

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

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

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

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

جریان OAuth: درخواست اول
شکل 1: جریان 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: درخواست های بعدی
شکل 2: جریان OAuth: درخواست های بعدی

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

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

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

هنگامی که یک نشانه دسترسی منقضی می شود (پس از 12 ساعت)، می توانید از نشانه refresh برای دریافت یک نشانه دسترسی جدید استفاده کنید:

جریان OAuth: نوسازی نشانه دسترسی
شکل 3: جریان OAuth: نوسازی نشانه دسترسی

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

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

توکن ها را دریافت کنید

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

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

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

  • توکن های دسترسی 12 ساعت دیگر منقضی می شوند.
  • توکن‌های Refresh در 30 روز منقضی می‌شوند.

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

با OAuth2 به Edge API دسترسی پیدا کنید

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

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

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

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

از فر استفاده کنید

برای دسترسی به Edge API می توانید از curl استفاده کنید. برای این کار ابتدا باید توکن های دسترسی و رفرش را دریافت کنید. شما می توانید اینها را با استفاده از ابزاری مانند get_token یا سرویس Edge OAuth2 دریافت کنید. .

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

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

رمز دسترسی تا 12 ساعت پس از صدور معتبر است. پس از انقضای توکن دسترسی، توکن به‌روزرسانی می‌تواند به مدت 30 روز برای صدور رمز دسترسی دیگر بدون نیاز به اعتبار استفاده شود. Apigee توصیه می کند به جای وارد کردن اعتبار و درخواست جدید با هر تماس API، فقط پس از انقضای توکن referesh درخواست یک نشانه دسترسی جدید کنید.

انقضای توکن

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

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

  • 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 از کاربر ماشین جلوگیری می کند.