Mengakses Edge API dengan SAML

Anda sedang melihat dokumentasi Apigee Edge.
Buka Dokumentasi Apigee X.
info

SAML mendukung lingkungan single sign-on (SSO). Dengan menggunakan SAML bersama Edge, Anda dapat mendukung SSO untuk UI dan API Edge selain layanan lain yang Anda sediakan dan yang juga mendukung SAML.

Prasyarat: Anda harus mengaktifkan SAML setidaknya selama satu organisasi sebelum Anda dapat menggunakannya untuk mengakses Edge API.

Perbedaan antara SAML dan OAuth2

Setelah SAML disiapkan, penggunaannya sangat mirip dengan menggunakan OAuth2 untuk mengakses Edge API. Saat memanggil Edge API, Anda menyertakan token akses OAuth2 di terhadap permintaan Anda.

Perbedaan utama antara SAML dan OAuth2 saat mengakses Edge API terletak pada Anda akan mendapatkan token. Dengan SAML, Anda harus menyertakan hal berikut saat mendapatkan pasangan token:

  1. Zona: Edge untuk pengguna Public Cloud harus merujuk nama zona mereka saat mendapatkan token.
  2. Kode sandi: Menyertakan kode sandi sekali pakai saat meminta akses/pembaruan pasangan token.

SAML menggunakan endpoint yang sama di layanan Edge OAuth2, dengan penambahan nama zona yang sesuai.

Untuk mendapatkan token akses dengan SAML, Anda dapat menggunakan salah satu metode berikut, yang dijelaskan di bagian ini:

Selain itu, Anda dapat mengotomatiskan proses pembuatan token untuk pengguna mesin, seperti yang dijelaskan dalam Mengotomatiskan proses pembuatan token.

Mendapatkan token akses dengan get_token

Anda dapat menggunakan utilitas get_token untuk menukar kredensial untuk akses OAuth2 dan token pembaruan yang digunakan dengan SAML.

Untuk mendapatkan token akses dengan get_token:

  1. Tetapkan variabel lingkungan SSO_LOGIN_URL ke URL login Anda. URL login memiliki format berikut:
    https://zoneName.login.apigee.com

    Misalnya, untuk zona bernama "acme", tetapkan SSO_LOGIN_URL ke "https://acme.login.apigee.com", seperti yang ditunjukkan contoh berikut:

    export SSO_LOGIN_URL=https://acme.login.apigee.com
  2. Panggil get_token untuk mendapatkan token akses OAuth2:
    get_token -u me@example.com

    Anda akan diminta untuk membuka URL yang ditampilkan guna mendapatkan kode sandi sekali pakai:

    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:

    Jika Anda belum login melalui Penyedia Identitas, Anda akan diminta untuk login inc.

    URL ini menampilkan kode sandi sekali pakai yang tetap valid sampai Anda memuat ulang URL tersebut untuk mendapatkan kode sandi baru, atau Anda menggunakan kode sandi dengan get_token untuk membuat token masing-masing. Contoh:

  3. Masukkan kode sandi. Utilitas get_token memperoleh token OAuth2, mencetak token akses ke stdout, dan menulis token akses dan refresh ke ~/.sso-cli.

  4. Memanggil Edge API dan meneruskan token akses di Authorization: Bearer seperti yang ditampilkan dalam contoh berikut:
    curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
      -H "Authorization: Bearer ACCESS_TOKEN"

    Nilai token akses dapat disalin dari stdout.

    Contoh ini mendapatkan detail tentang organisasi tertentu. Untuk daftar lengkap pengelolaan Endpoint API, lihat Referensi Apigee Edge API.

Saat token akses Anda berakhir, Anda dapat memanggil get_token lagi untuk mendapatkan akses baru sebelumnya yang benar. Contoh:

get_token -u me@example.com

Anda tidak akan dimintai kode sandi baru hingga masa berlaku token refresh berakhir.

Saat masa berlaku token refresh berakhir, get_token akan meminta kode sandi baru. Anda harus membuat kode sandi baru sebelum Anda dapat membuat token akses OAuth2 yang baru.

Mendapatkan token akses dengan layanan OAuth2 Edge

Anda dapat menggunakan layanan Edge OAuth2 untuk mendapatkan token akses yang digunakan dengan SAML. Untuk mengautentikasi sendiri menggunakan Edge API, Anda menggunakan kode sandi pada permintaan awal untuk mendapatkan akses/pembaruan pasangan token, dan sekali lagi untuk mendapatkan pasangan token baru.

Untuk mendapatkan pasangan token dengan Edge API:

  1. Di browser, buka URL berikut untuk mendapatkan kode sandi sekali pakai:
    https://zoneName.login.apigee.com/passcode

    Misalnya, untuk zona bernama "acme", buka URL berikut:

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

    Jika Anda belum login melalui Penyedia Identitas, Anda akan diminta untuk login inc.

    URL ini menampilkan kode sandi sekali pakai yang berfungsi sebagai kredensial Anda untuk mendapatkan token dan tetap valid hingga Anda memuat ulang URL untuk mendapatkan kode sandi baru, atau Anda dapat menggunakan kode sandi dengan get_token untuk membuat token masing-masing. Contoh:

  2. Kirim permintaan ke Edge API, seperti yang ditunjukkan contoh berikut:
    curl https://zoneName.login.apigee.com/oauth/token \
          -s \
          -H "Accept: application/json" \
          -d 'grant_type=password&response_type=token&passcode=passcode'

    passcode berfungsi sebagai kredensial Anda untuk otorisasi.

    Dengan keterangan:

    • Header Authorization adalah "Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" (gunakan nilai tepatnya).
    • Jenis permintaannya adalah POST.
    • Isi permintaan berisi hal berikut:
      • grant_type adalah "sandi".
      • response_type adalah "token".
      • passcode dengan passcode adalah kode sandi yang ditampilkan di langkah sebelumnya.

    Panggilan tersebut akan mencetak token akses dan refresh ke layar.

Untuk memperbarui token akses:

Kirim permintaan ke https://zoneName.login.apigee.com/oauth/token, seperti yang ditunjukkan contoh berikut:

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

Dengan keterangan:

  • Isi permintaan berisi hal berikut:
    • grant_type adalah "refresh_token".
    • refresh_token adalah nilai token refresh.
  • Header Authorization adalah "Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" (gunakan nilai tepatnya).
  • Jenis permintaannya adalah POST.

Akses Edge API dengan SAML

Anda dapat menggunakan alat seperti curl atau utilitas praktis Apigee acurl dapat mengakses Edge API.

Dengan curl, Anda memanggil Edge API dan meneruskan token akses di Header Authorization: Bearer, seperti yang ditunjukkan contoh berikut:

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

Dengan acurl, Anda tidak perlu menentukan header Authorization. Contoh:

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

Contoh ini memanggil endpoint Edge API yang mendapatkan detail tentang organisasi tertentu. Untuk mengetahui daftar lengkap endpoint Edge API, lihat Referensi Apigee Edge API.

Untuk metode panggilan API lainnya, termasuk cara memastikan bahwa token Anda tetap ada baru, lihat Mengakses Edge API dengan OAuth2.

Pengguna perangkat di zona SAML

Anda dapat menggunakan utilitas acurl dan get_token untuk membuat skrip akses otomatis ke API Edge untuk pengguna mesin di zona SAML. Contoh berikut menunjukkan cara gunakan get_token untuk meminta token akses, lalu menambahkan nilai token ke panggilan 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/...'

Pada contoh di atas, menetapkan nilai -m ke string kosong akan mencegah pengguna perangkat agar tidak dimintai kode MFA. Menggunakan tanda --force-basic-auth akan mengganti perintah standar untuk kode sandi yang dipicu oleh permintaan dengan zona SAML.

Atau, Anda dapat menggabungkan permintaan token dan panggilan curl menggunakan utilitas acurl. Contoh:

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