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

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

SAML از محیط ورود یکپارچه (SSO) پشتیبانی می‌کند. با استفاده از SAML با Edge، می‌توانید علاوه بر سایر سرویس‌هایی که ارائه می‌دهید و از SAML نیز پشتیبانی می‌کنند، از SSO برای رابط کاربری و API Edge نیز پشتیبانی کنید.

پیش‌نیاز: قبل از اینکه بتوانید از SAML برای دسترسی به Edge API استفاده کنید، باید آن را حداقل برای یک سازمان فعال کنید .

تفاوت‌های بین SAML و OAuth2

پس از راه‌اندازی SAML، استفاده از آن بسیار شبیه به استفاده از OAuth2 برای دسترسی به Edge API است. وقتی Edge API را فراخوانی می‌کنید، یک توکن دسترسی OAuth2 را در درخواست خود قرار می‌دهید.

تفاوت کلیدی بین SAML و OAuth2 هنگام دسترسی به Edge API در نحوه دریافت توکن‌ها است. با SAML، هنگام دریافت جفت توکن خود باید موارد زیر را لحاظ کنید:

  1. مناطق: کاربران Edge برای ابر عمومی باید هنگام دریافت توکن‌ها، نام منطقه خود را ذکر کنند.
  2. کد عبور: هنگام درخواست جفت توکن دسترسی/بازخوانی، یک کد عبور یکبار مصرف وارد کنید.

SAML از همان نقاط پایانی در سرویس Edge OAuth2 استفاده می‌کند، با این تفاوت که نام منطقه‌ی مناسب به آن اضافه شده است.

برای دریافت توکن‌های دسترسی با SAML، می‌توانید از یکی از روش‌های زیر که در این بخش توضیح داده شده است، استفاده کنید:

علاوه بر این، می‌توانید فرآیند تولید توکن را برای کاربران دستگاه، همانطور که در «خودکارسازی فرآیند تولید توکن» توضیح داده شده است، خودکار کنید.

دریافت توکن‌های دسترسی با get_token

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

برای دریافت توکن دسترسی با get_token:

  1. متغیر محیطی SSO_LOGIN_URL را روی URL ورود به سیستم خود تنظیم کنید. URL ورود به سیستم به شکل زیر است:
    https://zoneName.login.apigee.com

    برای مثال، برای منطقه‌ای با نام "acme"، SSO_LOGIN_URL را روی "https://acme.login.apigee.com" تنظیم کنید، همانطور که در مثال زیر نشان داده شده است:

    export SSO_LOGIN_URL=https://acme.login.apigee.com
  2. برای دریافت توکن دسترسی OAuth2، get_token فراخوانی کنید:
    get_token -u me@example.com

    از شما خواسته می‌شود برای دریافت رمز عبور یکبار مصرف، به آدرس اینترنتی نمایش داده شده مراجعه کنید:

    Get passcode from https://acme.login.apigee.com/passcode
[Note:  Passcode can be used only time time and expires] Input passcode (no spaces) and then press ENTER:

    اگر اخیراً از طریق ارائه دهنده هویت خود وارد سیستم نشده‌اید، از شما خواسته می‌شود که وارد سیستم شوید.

    این URL یک کد عبور یکبار مصرف را برمی‌گرداند که تا زمانی که آن URL را برای دریافت کد عبور جدید به‌روزرسانی نکنید، یا از کد عبور به همراه get_token برای تولید یک توکن دسترسی استفاده نکنید، معتبر باقی می‌ماند. برای مثال:

  3. کد عبور را وارد کنید. ابزار get_token توکن‌های OAuth2 را دریافت می‌کند، توکن دسترسی را در stdout چاپ می‌کند و توکن‌های دسترسی و رفرش را در ~/.sso-cli می‌نویسد.

  4. رابط برنامه‌نویسی Edge را فراخوانی کنید و توکن دسترسی را در هدر Authorization: Bearer قرار دهید، همانطور که در مثال زیر نشان داده شده است:
    curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"

    مقدار توکن دسترسی را می‌توان از stdout کپی کرد.

    این مثال جزئیاتی در مورد سازمان داده شده ارائه می‌دهد. برای مشاهده لیست کاملی از نقاط پایانی API مدیریت، به مرجع API Apigee Edge مراجعه کنید.

وقتی توکن دسترسی شما منقضی شد، می‌توانید دوباره get_token فراخوانی کنید تا یک توکن دسترسی جدید دریافت کنید. برای مثال:

get_token -u me@example.com

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

وقتی توکن به‌روزرسانی منقضی می‌شود، get_token از شما رمز عبور جدیدی می‌خواهد. قبل از اینکه بتوانید توکن دسترسی OAuth2 جدیدی ایجاد کنید، باید یک رمز عبور جدید ایجاد کنید.

دریافت توکن‌های دسترسی با سرویس Edge OAuth2

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

برای دریافت یک جفت توکن با Edge API:

  1. برای دریافت رمز یکبار مصرف، در مرورگر خود به آدرس اینترنتی زیر مراجعه کنید:
    https://zoneName.login.apigee.com/passcode

    برای مثال، برای منطقه‌ای با نام "acme"، به آدرس اینترنتی زیر بروید:

    https://acme.login.apigee.com/passcode

    اگر اخیراً از طریق ارائه دهنده هویت خود وارد سیستم نشده‌اید، از شما خواسته می‌شود که وارد سیستم شوید.

    این URL یک کد عبور یکبار مصرف را برمی‌گرداند که به عنوان اعتبارنامه شما برای دریافت توکن‌ها عمل می‌کند و تا زمانی که URL را برای دریافت کد عبور جدید به‌روزرسانی نکنید، معتبر باقی می‌ماند، یا می‌توانید از کد عبور با get_token برای تولید یک توکن دسترسی استفاده کنید. به عنوان مثال:

  2. همانطور که در مثال زیر نشان داده شده است، یک درخواست به Edge API ارسال کنید:
    curl https://zoneName.login.apigee.com/oauth/token \
      -s \
      -H "Accept: application/json" \
      -d 'grant_type=password&response_type=token&passcode=passcode'

    passcode به عنوان اعتبارنامه شما برای مجوز عمل می‌کند.

    کجا:

    • هدر Authorization برابر با «Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0» است (دقیقاً از همین مقدار استفاده کنید).
    • نوع درخواست POST است.
    • متن درخواست شامل موارد زیر است:
      • grant_type همان "رمز عبور" است.
      • response_type برابر با "token" است.
      • passcode که در آن passcode کد عبوری است که در مرحله قبل برگردانده شده است.

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

برای به‌روزرسانی توکن دسترسی خود:

همانطور که در مثال زیر نشان داده شده است، درخواستی را به https:// zoneName .login.apigee.com/oauth/token ارسال کنید: 

curl https://zoneName.login.apigee.com/oauth/token \
      -d 'grant_type=refresh_token&refresh_token=REFRESH_TOKEN'

کجا:

  • متن درخواست شامل موارد زیر است:
    • grant_type با "refresh_token" است.
    • refresh_token مقدار توکن refresh است.
  • هدر Authorization برابر با «Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0» است (دقیقاً از همین مقدار استفاده کنید).
  • نوع درخواست POST است.

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

برای دسترسی به API اج می‌توانید از ابزارهایی مانند curl یا ابزار کمکی Apigee به acurl استفاده کنید.

با curl ، شما Edge API را فراخوانی می‌کنید و توکن دسترسی را در هدر Authorization: Bearer ارسال می‌کنید، همانطور که در مثال زیر نشان داده شده است: 

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

با acurl ، نیازی به مشخص کردن هدر Authorization ندارید. برای مثال: 

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

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

برای روش‌های بیشتر فراخوانی API، از جمله روش‌هایی برای اطمینان از به‌روز ماندن توکن شما، به Access the Edge API with OAuth2 مراجعه کنید.

کاربران دستگاه در مناطق SAML

شما می‌توانید از ابزارهای acurl و get_token برای اسکریپت‌نویسی دسترسی خودکار به APIهای Edge برای کاربران ماشین در مناطق SAML استفاده کنید. مثال زیر نحوه استفاده از get_token برای درخواست یک توکن دسترسی و سپس اضافه کردن مقدار توکن به یک فراخوانی curl را نشان می‌دهد: 

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

در مثال بالا، تنظیم مقدار -m به یک رشته خالی، از درخواست کد MFA به کاربر ماشین جلوگیری می‌کند. استفاده از پرچم --force-basic-auth درخواست استاندارد برای کد عبور ایجاد شده توسط درخواست‌های دارای مناطق SAML را لغو می‌کند.

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

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