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

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

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

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

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

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

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

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

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

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

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

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

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

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

  1. متغیر محیط SSO_LOGIN_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:

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

    این نشانی وب گذرنویسه یکبارمصرفی را برمی‌گرداند که تا زمانی که آن نشانی وب را برای دریافت گذرنویسه جدید بازآوری کنید معتبر است، یا از گذرنویسه با 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 کپی کرد.

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

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

get_token -u me@example.com

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

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

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

می‌توانید از سرویس Edge OAuth2 برای دریافت کدهای دسترسی که با SAML استفاده می‌کنید استفاده کنید. برای اصالت‌سنجی خودتان با Edge API، از گذرکد در درخواست اولیه خود برای دریافت جفت کد دسترسی/بازآوری استفاده می‌کنید و دوباره برای دریافت جفت کد جدید استفاده می‌کنید.

برای دریافت جفت کد با «میانای برنامه‌سازی کاربردی Edge»:

  1. در مرورگر، به نشانی وب زیر بروید تا گذرواژه یک‌بارمصرف دریافت کنید: 
    https://zoneName.login.apigee.com/passcode

    برای مثال، برای منطقه‌ای به‌نام «acme»، به نشانی وب زیر بروید:

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

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

    این نشانی وب گذرنویسه یک‌بارمصرفی را برمی‌گرداند که به‌عنوان اطلاعات اعتباری شما برای دریافت نشان‌ها عمل می‌کند و تا زمانی که نشانی وب را برای دریافت گذرنویسه جدید بازآوری کنید معتبر می‌ماند، یا می‌توانید از گذرنویسه با 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 «رمز» است.
      • 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 مقدار ژتون بازآوری است.
  • سرصفحه Authorization عبارت است از «Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0» (از این مقدار دقیق استفاده کنید).
  • نوع درخواست POST است.

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

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

با curl، «میانای برنامه‌سازی کاربردی Edge» را فراخوانی می‌کنید و رمز دسترسی را در سرصفحه 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، ازجمله روش‌هایی برای اطمینان از اینکه کد شما همیشه تازه است، به دسترسی به Edge API با OAuth2 مراجعه کنید.

کاربران ماشین در مناطق SAML

می‌توانید از ابزارهای acurl و get_token برای نوشتن دستورگان دسترسی خودکارسازی‌شده به «میاناهای برنامه‌سازی کاربردی 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 روی رشته خالی باعث می‌شود کاربر ماشین برای دریافت کد «احراز هویت چندعاملی» درخواست نشود. استفاده از پرچم --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/...'