Anda sedang melihat dokumentasi Apigee Edge.
Buka
Dokumentasi Apigee X. info
Apigee Edge memungkinkan Anda melakukan panggilan Edge API yang diautentikasi dengan token OAuth2. Dukungan untuk OAuth2 diaktifkan secara default di Edge untuk akun Cloud. Jika Anda menggunakan Edge untuk Private Cloud, Anda tidak dapat menggunakan OAuth2 tanpa pertama-tama menyiapkan SAML atau LDAP.
Cara kerja OAuth2 (dengan Apigee Edge API)
Panggilan ke Apigee Edge API memerlukan autentikasi agar kami dapat yakin bahwa Andalah yang Anda katakan begitu. Untuk mengautentikasi Anda, kami mewajibkan pengiriman token akses OAuth2 bersama permintaan Anda untuk mengakses API.
Misalnya, jika Anda ingin mendapatkan detail tentang suatu organisasi di Edge, Anda akan mengirim permintaan ke URL seperti berikut:
https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval
Namun, Anda tidak bisa begitu saja mengirimkan permintaan tersebut tanpa memberi tahu kami siapa Anda. Jika tidak, siapa saja dapat melihat detail organisasi Anda.
Di sinilah OAuth2 berperan: untuk mengautentikasi Anda, Anda harus mengirimkan token akses kepada kami. dalam permintaan tersebut. Token akses memberi tahu kami siapa Anda sehingga kami yakin bahwa Anda diizinkan untuk melihat detail organisasinya.
Untungnya, Anda bisa mendapatkan token dengan mengirimkan kredensial ke layanan OAuth2 Edge. Tujuan merespons dengan token akses dan refresh.
Alur OAuth2: Permintaan awal
Gambar berikut menunjukkan alur OAuth2 saat Anda mengakses Edge API untuk waktu:
Seperti yang ditunjukkan Gambar 1, saat Anda membuat permintaan awal ke Edge API:
- Anda meminta token akses. Anda dapat melakukannya dengan
Edge API, acurl, atau
get_token
. Contoh: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
- Layanan Edge OAuth2 merespons dengan token akses, dan mencetaknya ke
stdout
; misalnya:Dy42bGciOiJSUzI1NiJ9.eyJqdGkiOiJhM2YwNjA5ZC1lZTIxLTQ1YjAtOGQyMi04MTQ0MTYxNjNhNTMiLCJz AJpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNsaSIsIm NjbGkiLCJhenAiOiJlZGdlY2xpIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjJkMWU3NDI GzQyMC1kYzgxLTQzMDQtOTM4ZS1hOGNmNmVlODZhNzkiLCJzY29wZSI6WyJzY2ltLm1lIiwib3BlbmlkIiwic ENC05MzhlLWE4Y2Y2ZWU4NmE3OSIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoiZGFuZ2VyNDI0 RI6ImUyNTM2NWQyIiwiaWF0IjoxNTI4OTE2NDA5LCJleHAiOjE1Mjg5MTgyMDksImlzcyI6Imh0dHBzOi8vbG 420iLCJlbWFpbCI6ImRhbmdlcjQyNDJAeWFob28uY29tIiwiYXV0aF90aW1lIjoxNTI4OTE2NDA5LCJhbCI6M 2lLmNvbSIsInppZCI6InVhYSIsImF1ZCI6WyJlZGdlY2xpIiwic2NpbSIsIm9wZW5pZCIsInBhc3N3b3JkIiw
Utilitas
acurl
danget_token
secara otomatis menyimpan akses dan token refresh ke~/.sso-cli
(Token refresh tidak ditulis kestdout
.) Jika menggunakan layanan Edge OAuth2 untuk mendapatkan token, Anda harus menyimpannya untuk gunakanlah diri Anda sendiri. - Anda mengirimkan permintaan ke Edge API dengan token akses.
acurl
melampirkan token secara otomatis; misalnya:acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval
Jika Anda menggunakan klien HTTP lain, pastikan untuk menambahkan token akses. Contoh:
curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \ -H "Authorization: Bearer ACCESS_TOKEN"
- Edge API mengeksekusi permintaan Anda dan biasanya menampilkan respons dengan data.
Alur OAuth2: Permintaan berikutnya
Pada permintaan berikutnya, Anda tidak perlu menukar kredensial dengan token. Sebagai gantinya, Anda cukup menyertakan token akses yang sudah Anda miliki, selama token tersebut belum kedaluwarsa:
Jika Anda sudah memiliki token akses, seperti yang ditunjukkan pada Gambar 2:
- Anda mengirimkan permintaan ke Edge API dengan token akses.
acurl
melampirkan token secara otomatis. Jika menggunakan alat lain, Anda perlu menambahkan token secara manual. - Edge API mengeksekusi permintaan Anda dan biasanya menampilkan respons dengan data.
Alur OAuth2: Saat masa berlaku token akses Anda berakhir
Saat masa berlaku token akses berakhir (setelah 12 jam), Anda dapat menggunakan token refresh untuk mendapatkan token akses:
Seperti yang ditunjukkan pada Gambar 3, saat masa berlaku token akses Anda berakhir:
- Anda mengirimkan permintaan ke Edge API, tetapi token akses Anda sudah tidak berlaku.
- Edge API menolak permintaan Anda sebagai tidak sah.
- Anda mengirim token refresh ke layanan OAuth2 Edge. Jika Anda menggunakan
acurl
, ini sudah selesai secara otomatis untuk Anda. - Layanan OAuth2 Edge merespons dengan token akses baru.
- Anda mengirimkan permintaan ke Edge API dengan token akses baru.
- Edge API mengeksekusi permintaan Anda dan biasanya menampilkan respons dengan data.
Mendapatkan token
Untuk mendapatkan token akses yang dapat dikirim ke Edge API, Anda dapat menggunakan
Utilitas Apigee, selain utilitas seperti curl
:
- get_token utility: Menukarkan kredensial Apigee Anda untuk mendapatkan akses token baru yang dapat digunakan untuk memanggil Edge API.
- utilitas acurl: Menyediakan wrapper praktis seputar standar
Perintah
curl
. Membuat permintaan HTTP ke Edge tertentu, mendapatkan token akses dan refresh dariget_token
, lalu meneruskan token akses tersebut ke Edge API. - Endpoint token di layanan Edge OAuth2: Tukarkan Kredensial Apigee untuk akses dan token refresh melalui panggilan ke Edge API.
Utilitas ini bertukar kredensial akun Apigee Anda (alamat email dan sandi) untuk token dengan durasi berikut:
- Masa berlaku token akses berakhir dalam 12 jam.
- Masa berlaku token refresh akan berakhir dalam 30 hari.
Akibatnya, setelah Anda berhasil melakukan panggilan API dengan acurl
atau get_token
,
Anda dapat terus menggunakan
pasangan token selama 30 hari. Setelah masa berlaku habis, Anda harus memasukkan kembali
kredensial, dan mendapatkan
token baru.
Mengakses Edge API dengan OAuth2
Untuk mengakses Edge API, Anda mengirim permintaan ke endpoint API dan menyertakan token akses.
Anda dapat melakukannya dengan klien HTTP apa pun, termasuk utilitas command line seperti curl
,
UI berbasis browser seperti Postman, atau utilitas Apigee seperti acurl
.
Mengakses Edge API dengan acurl
dan curl
dijelaskan dalam
bagian-bagian berikutnya.
Gunakan acurl
Untuk mengakses Edge API dengan acurl
, permintaan awal Anda harus menyertakan
memiliki kredensial yang lengkap. Layanan OAuth2 Edge merespons dengan token akses dan refresh. acurl
menyimpan token secara lokal.
Pada permintaan berikutnya, acurl
menggunakan token yang disimpan di ~/.sso-cli
, jadi
Anda tidak perlu memasukkan kredensial Anda lagi
hingga token tersebut kedaluwarsa.
Contoh berikut menunjukkan permintaan acurl
awal yang mendapatkan detail untuk
"Ahamilton-eval" organisasi:
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" ]
Selain mendapatkan detail tentang organisasi, contoh ini juga menampilkan permintaan kedua yang berisi daftar kebijakan dalam "helloworld" Proxy API. Permintaan kedua menggunakan mempersingkat "o" untuk "organisasi" di URL.
Perlu diperhatikan bahwa acurl
akan otomatis meneruskan token akses pada permintaan kedua. Anda
tidak perlu meneruskan kredensial pengguna Anda setelah acurl
menyimpan token OAuth2. Ini
mendapatkan token dari ~/.sso-cli
untuk panggilan berikutnya.
Untuk informasi selengkapnya, lihat Menggunakan acurl untuk mengakses Edge API.
Gunakan curl
Anda dapat menggunakan curl
untuk mengakses Edge API. Untuk melakukannya, Anda terlebih dahulu harus mendapatkan
akses dan token refresh. Anda bisa mendapatkannya menggunakan utilitas seperti get_token
atau
Layanan OAuth2 Edge.
Setelah berhasil menyimpan token akses, Anda meneruskannya di
Header Authorization
panggilan Anda ke Edge API, seperti contoh berikut
menampilkan:
curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \ -H "Authorization: Bearer ACCESS_TOKEN"
Token akses berlaku selama 12 jam setelah diterbitkan. Setelah masa berlaku token akses berakhir, token refresh dapat digunakan selama 30 hari untuk menerbitkannya token akses lainnya tanpa memerlukan kredensial. Apigee merekomendasikan untuk meminta token akses baru hanya setelah token rujukan berakhir, bukan memasukkan kredensial dan membuat permintaan baru pada setiap panggilan API.
Akhir masa berlaku token
Setelah masa berlaku token akses berakhir, Anda dapat menggunakan token refresh untuk mendapatkan token akses baru tanpa dan mengirimkan kredensial lagi.
Cara Anda memuat ulang token akses bergantung pada alat yang Anda gunakan:
acurl
: Anda tidak perlu melakukan tindakan apa pun.acurl
otomatis memperbarui token akses saat Anda mengirim permintaan berisi permintaan yang sudah usang.get_token
: Panggilget_token
untuk memuat ulang token akses.- Layanan OAuth2 Edge: Mengirim permintaan yang menyertakan:
- Token refresh
- Parameter formulir
grant_type
ditetapkan ke "refresh_token"
OAuth2 untuk pengguna komputer
Anda dapat menggunakan utilitas acurl
dan get_token
untuk membuat skrip akses otomatis
ke API Edge dengan autentikasi OAuth2
untuk pengguna mesin. 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 '')
curl -H "Authorization: Bearer $TOKEN" 'https://api.enterprise.apigee.com/v1/organizations/...'
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 '' 'https://api.enterprise.apigee.com/v1/organizations/...'
Dalam kedua contoh tersebut, menetapkan nilai -m
ke string kosong akan mencegah pengguna perangkat
agar tidak dimintai kode MFA.