Anda sedang melihat dokumentasi Apigee Edge.
Buka
dokumentasi Apigee X. info
Edge Microgateway v. 3.0.x
Topik ini membahas cara mengelola dan mengonfigurasi Edge Microgateway.
Mengupgrade Edge Microgateway jika Anda memiliki koneksi internet
Bagian ini menjelaskan cara mengupgrade penginstalan Edge Microgateway yang ada. Jika Anda beroperasi tanpa koneksi internet, lihat Dapatkah saya menginstal Edge Microgateway tanpa koneksi internet?.
Apigee menyarankan Anda untuk menguji konfigurasi yang ada dengan versi baru sebelum mengupgrade lingkungan produksi.
- Jalankan perintah
npm
berikut untuk mengupgrade ke Edge Microgateway versi terbaru:npm upgrade edgemicro -g
Untuk melakukan upgrade ke versi Edge Microgateway tertentu, Anda harus menentukan nomor versi dalam perintah upgrade. Jika Anda tidak menentukan nomor versi, versi terbaru akan diinstal. Misalnya, untuk mengupgrade ke versi 3.0.2, gunakan perintah berikut:
npm upgrade edgemicro@3.0.2 -g
- Lihat nomor versi aplikasi. Misalnya, jika Anda menginstal versi 3.0.2:
edgemicro --version current nodejs version is v12.5.0 current edgemicro version is 3.0.2
- Terakhir, upgrade ke proxy edgemicro-auth versi terbaru:
edgemicro upgradeauth -o org_name -e env_name -u username
Membuat perubahan konfigurasi
File konfigurasi yang perlu Anda ketahui meliputi:
- File konfigurasi sistem default
- File konfigurasi default untuk instance Edge Microgateway yang baru diinisialisasi
- File konfigurasi dinamis untuk menjalankan instance
Bagian ini membahas file ini dan hal yang perlu Anda ketahui tentang cara mengubahnya.
File konfigurasi sistem default
Saat Anda menginstal Edge Microgateway, file konfigurasi sistem default akan ditempatkan di sini:
prefix/lib/node_modules/edgemicro/config/default.yaml
Dengan prefix adalah direktori awalan npm
. Lihat
Di mana Edge Microgateway diinstal jika Anda tidak dapat menemukan direktori ini.
Jika mengubah file konfigurasi sistem, Anda harus melakukan inisialisasi ulang, mengonfigurasi ulang, dan memulai ulang Edge Microgateway:
edgemicro initedgemicro configure [params]
edgemicro start [params]
File konfigurasi default untuk instance Edge Microgateway yang baru diinisialisasi
Saat Anda menjalankan edgemicro init
, file konfigurasi sistem (dijelaskan
di atas), default.yaml
, akan ditempatkan di direktori ~/.edgemicro
.
Jika mengubah file konfigurasi di ~/.edgemicro
, Anda harus mengonfigurasi ulang dan memulai ulang
Edge Microgateway:
edgemicro stopedgemicro configure [params]
edgemicro start [params]
File konfigurasi dinamis untuk menjalankan instance
Saat Anda menjalankan edgemicro configure [params]
, file konfigurasi dinamis akan dibuat di ~/.edgemicro
. File ini diberi nama sesuai dengan pola ini: org-env-config.yaml
, dengan org dan env adalah nama organisasi dan lingkungan Apigee Edge Anda. Anda dapat menggunakan file ini untuk membuat perubahan
konfigurasi, lalu memuatnya ulang tanpa periode nonaktif. Misalnya, jika menambahkan dan mengonfigurasi plugin, Anda dapat memuat ulang konfigurasi tanpa menyebabkan periode nonaktif, seperti yang dijelaskan di bawah.
Jika Edge Microgateway sedang berjalan (opsi periode nonaktif nol):
- Muat ulang konfigurasi Edge Microgateway:
edgemicro reload -o org_name -e env_name -k key -s secret
Dengan keterangan:
- org_name adalah nama organisasi Edge Anda (Anda harus menjadi administrator organisasi).
- env_name adalah lingkungan dalam organisasi Anda (seperti "test" atau "prod").
- key adalah kunci yang ditampilkan sebelumnya oleh perintah konfigurasi.
- secret adalah kunci yang ditampilkan sebelumnya oleh perintah konfigurasi.
Contoh:
edgemicro reload -o docs -e test -k 701e70ee718ce6dc188...78b6181d000723 \ -s 05c14356e42ed1...4e34ab0cc824
Jika Edge Microgateway dihentikan:
- Mulai ulang Edge Microgateway:
edgemicro start -o org_name -e env_name -k key -s secret
Dengan keterangan:
- org_name adalah nama organisasi Edge Anda (Anda harus menjadi administrator organisasi).
- env_name adalah lingkungan dalam organisasi Anda (seperti "test" atau "prod").
- key adalah kunci yang ditampilkan sebelumnya oleh perintah konfigurasi.
- secret adalah kunci yang ditampilkan sebelumnya oleh perintah konfigurasi.
Contoh:
edgemicro start -o docs -e test -k 701e70ee718ce...b6181d000723 \ -s 05c1435...e34ab0cc824
Berikut adalah contoh file konfigurasi. Untuk mengetahui detail tentang setelan file konfigurasi, lihat Referensi konfigurasi Edge Microgateway.
edge_config: bootstrap: >- https://edgemicroservices-us-east-1.apigee.net/edgemicro/bootstrap/organization/docs/environment/test jwt_public_key: 'https://docs-test.apigee.net/edgemicro-auth/publicKey' managementUri: 'https://api.enterprise.apigee.com' vaultName: microgateway authUri: 'https://%s-%s.apigee.net/edgemicro-auth' baseUri: >- https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s bootstrapMessage: Please copy the following property to the edge micro agent config keySecretMessage: The following credentials are required to start edge micro products: 'https://docs-test.apigee.net/edgemicro-auth/products' edgemicro: port: 8000 max_connections: 1000 max_connections_hard: 5000 config_change_poll_interval: 600 logging: level: error dir: /var/tmp stats_log_interval: 60 rotate_interval: 24 plugins: sequence: - oauth headers: x-forwarded-for: true x-forwarded-host: true x-request-id: true x-response-time: true via: true oauth: allowNoAuthorization: false allowInvalidAuthorization: false verify_api_key_url: 'https://docs-test.apigee.net/edgemicro-auth/verifyApiKey' analytics: uri: >- https://edgemicroservices-us-east-1.apigee.net/edgemicro/axpublisher/organization/docs/environment/test
Menyetel variabel lingkungan
Perintah antarmuka command line yang memerlukan nilai untuk organisasi dan lingkungan Edge Anda, serta kunci dan rahasia yang diperlukan untuk memulai Edge Microgateway dapat disimpan dalam variabel lingkungan berikut:
EDGEMICRO_ORG
EDGEMICRO_ENV
EDGEMICRO_KEY
EDGEMICRO_SECRET
Menyetel variabel ini bersifat opsional. Jika menetapkannya, Anda tidak perlu menentukan nilainya saat menggunakan Antarmuka Command Line (CLI) untuk mengonfigurasi dan memulai Edge Microgateway.
Mengonfigurasi SSL di server Edge Microgateway
Tonton video berikut untuk mempelajari cara mengonfigurasi TLS di Apigee Edge Microgateway:
Video | Deskripsi |
---|---|
Mengonfigurasi TLS 1 arah Utara | Pelajari cara mengonfigurasi TLS di Apigee Edge Microgateway. Video ini memberikan Ringkasan TLS dan nilai pentingnya, memperkenalkan TLS di Edge Microgateway, dan menunjukkan cara mengonfigurasi TLS One-Way Northbound. |
Mengonfigurasi TLS 2 arah Utara | Ini adalah video kedua tentang cara mengonfigurasi TLS di Apigee Edge Microgateway. Video ini menjelaskan cara mengonfigurasi TLS 2 arah ke utara. |
Mengonfigurasi TLS 1 arah dan 2 arah | Video ketiga tentang cara mengonfigurasi TLS di Apigee Edge Microgateway ini menjelaskan cara mengonfigurasi TLS 1 arah dan 2 arah arah selatan. |
Anda dapat mengonfigurasi server Microgateway untuk menggunakan SSL. Misalnya, dengan SSL yang dikonfigurasi, Anda dapat memanggil API melalui Edge Microgateway dengan protokol "https", seperti ini:
https://localhost:8000/myapi
Untuk mengonfigurasi SSL di server Microgateway, ikuti langkah-langkah berikut:
- Buat atau dapatkan sertifikat dan kunci SSL menggunakan utilitas openssl atau metode apa pun yang Anda inginkan.
- Tambahkan atribut
edgemicro:ssl
ke file konfigurasi Edge Microgateway. Untuk daftar lengkap opsi, lihat tabel di bawah. Misalnya:
edgemicro: ssl: key: <absolute path to the SSL key file> cert: <absolute path to the SSL cert file> passphrase: admin123 #option added in v2.2.2 rejectUnauthorized: true #option added in v2.2.2 requestCert: true
- Mulai ulang Edge Microgateway. Ikuti langkah-langkah yang diuraikan dalam Membuat perubahan konfigurasi bergantung pada file konfigurasi mana yang Anda edit: file default atau file konfigurasi runtime.
Berikut adalah contoh bagian edgemicro
file konfigurasi, dengan SSL terkonfigurasi:
edgemicro: port: 8000 max_connections: 1000 max_connections_hard: 5000 logging: level: error dir: /var/tmp stats_log_interval: 60 rotate_interval: 24 plugins: sequence: - oauth ssl: key: /MyHome/SSL/em-ssl-keys/server.key cert: /MyHome/SSL/em-ssl-keys/server.crt passphrase: admin123 #option added in v2.2.2 rejectUnauthorized: true #option added in v2.2.2
Berikut adalah daftar semua opsi server yang didukung:
Opsi | Deskripsi |
---|---|
key |
Jalur ke file ca.key (dalam format PEM). |
cert |
Jalur ke file ca.cert (dalam format PEM). |
pfx |
Jalur ke file pfx yang berisi kunci pribadi, sertifikat, dan sertifikat CA
klien dalam format PFX. |
passphrase |
String yang berisi frasa sandi untuk kunci pribadi atau PFX. |
ca |
Jalur ke file yang berisi daftar sertifikat tepercaya dalam format PEM. |
ciphers |
String yang menjelaskan penyandian yang akan digunakan, dipisahkan oleh tanda ":". |
rejectUnauthorized |
Jika true (benar), sertifikat server akan diverifikasi berdasarkan daftar CA yang diberikan. Jika verifikasi gagal, pesan error akan ditampilkan. |
secureProtocol |
Metode SSL yang akan digunakan. Misalnya, SSLv3_method untuk memaksa SSL ke versi 3. |
servername |
Nama server untuk ekstensi TLS SNI (Server Name Indication). |
requestCert |
true untuk SSL 2 arah; false untuk SSL 1 arah |
Menggunakan opsi SSL/TLS klien
Anda dapat mengonfigurasi Edge Microgateway menjadi klien TLS atau SSL saat terhubung ke endpoint target. Pada file konfigurasi Microgateway, gunakan elemen target untuk menetapkan opsi SSL/TLS.
Contoh ini memberikan setelan yang akan diterapkan ke semua host:
edgemicro: ... targets: ssl: client: key: /Users/jdoe/nodecellar/twowayssl/ssl/client.key cert: /Users/jdoe/nodecellar/twowayssl/ssl/ca.crt passphrase: admin123 rejectUnauthorized: true
Dalam contoh ini, setelan hanya diterapkan ke host yang ditentukan:
edgemicro: ... targets: - host: 'myserver.example.com' ssl: client: key: /Users/myname/twowayssl/ssl/client.key cert: /Users/myname/twowayssl/ssl/ca.crt passphrase: admin123 rejectUnauthorized: true
Berikut adalah contoh untuk TLS:
edgemicro: ... targets: - host: 'myserver.example.com' tls: client: pfx: /Users/myname/twowayssl/ssl/client.pfx passphrase: admin123 rejectUnauthorized: true
Berikut adalah daftar semua opsi klien yang didukung:
Opsi | Deskripsi |
---|---|
pfx |
Jalur ke file pfx yang berisi kunci pribadi, sertifikat, dan sertifikat CA
klien dalam format PFX. |
key |
Jalur ke file ca.key (dalam format PEM). |
passphrase |
String yang berisi frasa sandi untuk kunci pribadi atau PFX. |
cert |
Jalur ke file ca.cert (dalam format PEM). |
ca |
Jalur ke file yang berisi daftar sertifikat tepercaya dalam format PEM. |
ciphers |
String yang menjelaskan penyandian yang akan digunakan, dipisahkan oleh tanda ":". |
rejectUnauthorized |
Jika true (benar), sertifikat server akan diverifikasi berdasarkan daftar CA yang diberikan. Jika verifikasi gagal, pesan error akan ditampilkan. |
secureProtocol |
Metode SSL yang akan digunakan. Misalnya, SSLv3_method untuk memaksa SSL ke versi 3. |
servername |
Nama server untuk ekstensi TLS SNI (Server Name Indication). |
Menyesuaikan proxy edgemicro-auth
Secara default, Edge Microgateway menggunakan proxy yang di-deploy di Apigee Edge untuk autentikasi OAuth2.
Proxy ini di-deploy saat Anda pertama kali menjalankan edgemicro configure
. Anda dapat mengubah konfigurasi default proxy ini guna menambahkan dukungan untuk klaim kustom ke Token Web JSON (JWT), mengonfigurasi masa berlaku token, dan membuat token refresh. Untuk mengetahui detailnya, lihat halaman edgemicro-auth di GitHub.
Menggunakan layanan autentikasi kustom
Secara default, Edge Microgateway menggunakan proxy yang di-deploy di Apigee Edge untuk autentikasi OAuth2.
Proxy ini di-deploy saat Anda pertama kali menjalankan edgemicro configure
. Secara default, URL proxy ini ditentukan dalam file konfigurasi Edge Microgateway sebagai berikut:
authUri: https://myorg-myenv.apigee.net/edgemicro-auth
Jika ingin menggunakan layanan khusus Anda sendiri untuk menangani autentikasi, ubah nilai authUri
di file konfigurasi agar mengarah ke layanan Anda. Misalnya, Anda mungkin memiliki layanan yang menggunakan LDAP untuk memverifikasi identitas.
Mengelola file log
Edge Microgateway mencatat informasi tentang setiap permintaan dan respons ke dalam log. File log memberikan informasi yang berguna untuk proses debug dan pemecahan masalah.
Tempat file log disimpan
Secara default, file log disimpan di /var/tmp
.
Cara mengubah direktori file log default
Direktori tempat file log disimpan ditentukan dalam file konfigurasi Edge Microgateway. Lihat juga Membuat perubahan konfigurasi.
edgemicro: home: ../gateway port: 8000 max_connections: -1 max_connections_hard: -1 logging: level: info dir: /var/tmp stats_log_interval: 60 rotate_interval: 24
Ubah nilai dir untuk menentukan direktori file log yang berbeda.
Mengirim log ke konsol
Anda dapat mengonfigurasi logging sehingga informasi log itu dikirim ke output standar, bukan ke
file log. Tetapkan flag to_console
ke benar (true) seperti berikut:
edgemicro: logging: to_console: true
Dengan setelan ini, log akan dikirim ke {i>standard out<i}. Saat ini, Anda tidak dapat mengirim log ke stdout dan file log sekaligus.
Cara menetapkan level logging
Anda dapat menetapkan level log ini: info, warning, dan error. Tingkat info direkomendasikan. Mencatat semua permintaan dan respons API ke dalam log, dan ini merupakan default.
Cara mengubah interval log
Anda dapat mengonfigurasi interval ini di file konfigurasi Edge Microgateway. Lihat juga Membuat perubahan konfigurasi.
Atribut yang dapat dikonfigurasi adalah:
- stats_log_interval: (default: 60) Interval, dalam detik, saat catatan statistik ditulis ke file log API.
- rotate_interval: (default: 24) Interval, dalam jam, saat file log dirotasi. Contoh:
edgemicro: home: ../gateway port: 8000 max_connections: -1 max_connections_hard: -1 logging: level: info dir: /var/tmp stats_log_interval: 60 rotate_interval: 24
Praktik pemeliharaan file log yang baik
Saat data file log terakumulasi dari waktu ke waktu, Apigee merekomendasikan agar Anda melakukan praktik berikut:
- Karena file log bisa menjadi cukup besar, pastikan direktori file log memiliki ruang yang cukup. Lihat bagian berikut Tempat file log disimpan dan Cara mengubah direktori file log default.
- Hapus atau pindahkan file log ke direktori arsip terpisah minimal seminggu sekali.
- Jika kebijakan Anda adalah menghapus log, Anda dapat menggunakan perintah CLI
edgemicro log -c
untuk menghapus (membersihkan) log lama.
Konvensi penamaan file log
Setiap instance Edge Microgateway menghasilkan tiga jenis file log:
- api - Mencatat semua permintaan dan respons yang mengalir melalui Edge Microgateway ke dalam log. Penghitung API (statistik) dan error juga dicatat ke file ini.
- err - Mencatat apa pun yang dikirim ke stderr.
- out - Mencatat apa pun yang dikirim ke stdout ke dalam log.
Ini adalah konvensi penamaan:
edgemicro-<Host Name>-<Instance ID>-<Log Type>.log
Contoh:
edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.log edgemicro-mymachine-local-MTQzNTg1NDMODAyMQ-err.log edgemicro-mymachine-local-mtqzntgndmxodaymq-out.log
Tentang konten file log
Ditambahkan di: v2.3.3
Secara default, layanan logging menghapus JSON dari proxy, produk, dan JSON Web Token (JWT) yang didownload. Jika Anda ingin menampilkan objek ini ke file log, tetapkan
DEBUG=*
saat Anda memulai Edge Microgateway. Contoh:
DEBUG=* edgemicro start -o docs -e test -k abc123 -s xyz456
Isi file log "api"
File log "api" berisi informasi mendetail tentang alur permintaan dan respons melalui Edge Microgateway. File log "api" diberi nama seperti ini:
edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log
Untuk setiap permintaan yang dibuat ke Edge Microgateway, empat peristiwa dicatat dalam file log "api":
- Permintaan masuk dari klien
- Permintaan keluar dibuat ke target
- Respons masuk dari target
- Respons keluar ke klien
Masing-masing entri terpisah ini direpresentasikan dalam notasi singkat untuk membantu membuat file log lebih ringkas. Berikut adalah empat contoh entri yang mewakili masing-masing dari keempat peristiwa tersebut. Di file log, baris terlihat seperti ini (nomor baris hanya untuk referensi dalam dokumen, dan tidak muncul di file log).
(1) 1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0 (2) 1436403888665 info treq m=GET, u=/, h=127.0.0.18080, i=0 (3) 1436403888672 info tres s=200, d=7, i=0 (4) 1436403888676 info res s=200, d=11, i=0
Mari kita lihat satu per satu:
1. Contoh permintaan masuk dari klien:
1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0
- 1436403888651 - Stempel tanggal Unix
- info - Tergantung konteksnya. Bisa berupa info, peringatan, atau error, bergantung pada level log. Dapat berupa statistik untuk catatan statistik, memberikan peringatan untuk peringatan, atau error untuk error.
- req - Mengidentifikasi peristiwa. Dalam hal ini, minta dari klien.
- m - Kata kerja HTTP yang digunakan dalam permintaan.
- u - Bagian URL yang mengikuti basepath.
- h - Host dan nomor port tempat Edge Microgateway memproses.
- r - Host dan port jarak jauh tempat permintaan klien berasal.
- i - ID permintaan. Keempat entri peristiwa akan menggunakan ID ini. Setiap permintaan diberi ID permintaan unik. Menghubungkan data log dengan ID permintaan dapat memberikan insight berharga tentang latensi target.
- d - Durasi dalam milidetik sejak permintaan diterima oleh Edge Microgateway. Pada contoh di atas, respons target untuk permintaan 0 diterima setelah 7 milidetik (baris 3), dan respons dikirim ke klien setelah 4 milidetik tambahan (baris 4). Dengan kata lain, total latensi permintaan adalah 11 milidetik, di mana 7 milidetik diambil oleh target dan 4 milidetik lagi oleh Edge Microgateway.
2. Contoh permintaan keluar yang dibuat untuk target:
1436403888665 info treq m=GET, u=/, h=127.0.0.1:8080, i=0
- 1436403888651 - Stempel tanggal Unix
- info - Tergantung konteksnya. Bisa berupa info, peringatan, atau error, bergantung pada level log. Dapat berupa statistik untuk catatan statistik, memberikan peringatan untuk peringatan, atau error untuk error.
- treq - Mengidentifikasi peristiwa. Dalam hal ini, menargetkan permintaan.
- m - Kata kerja HTTP yang digunakan dalam permintaan target.
- u - Bagian URL yang mengikuti basepath.
- h - Host dan nomor port target backend.
- i - ID entri log. Keempat entri peristiwa akan menggunakan ID ini.
3. Contoh respons masuk dari target
1436403888672 info tres s=200, d=7, i=0
1436403888651 - Stempel tanggal Unix
- info - Tergantung konteksnya. Bisa berupa info, peringatan, atau error, bergantung pada level log. Dapat berupa statistik untuk catatan statistik, memberikan peringatan untuk peringatan, atau error untuk error.
- tres - Mengidentifikasi peristiwa. Dalam hal ini, respons target.
- s - Status respons HTTP.
- d - Durasi dalam milidetik. Waktu yang dibutuhkan untuk panggilan API oleh target.
- i - ID entri log. Keempat entri peristiwa akan menggunakan ID ini.
4. Contoh respons keluar kepada klien
1436403888676 info res s=200, d=11, i=0
1436403888651 - Stempel tanggal Unix
- info - Tergantung konteksnya. Bisa berupa info, peringatan, atau error, bergantung pada level log. Dapat berupa statistik untuk catatan statistik, memberikan peringatan untuk peringatan, atau error untuk error.
- res - Mengidentifikasi peristiwa. Dalam hal ini, berikan respons kepada klien.
- s - Status respons HTTP.
- d - Durasi dalam milidetik. Ini adalah total waktu yang dibutuhkan oleh panggilan API, termasuk waktu yang dibutuhkan oleh API target dan waktu yang dibutuhkan oleh Edge Microgateway itu sendiri.
- i - ID entri log. Keempat entri peristiwa akan menggunakan ID ini.
Jadwal file log
File log dirotasi pada interval yang ditentukan oleh atribut konfigurasi rotate_interval. Entri akan terus ditambahkan ke file log yang sama hingga interval rotasi berakhir. Namun, setiap kali Edge Microgateway dimulai ulang, Edge Microgateway akan menerima UID baru dan membuat kumpulan file log baru dengan UID ini. Lihat juga Praktik pemeliharaan file log yang baik.
Pesan error
Beberapa entri log akan berisi pesan error. Untuk membantu mengidentifikasi di mana dan mengapa error terjadi, lihat Referensi error Edge Microgateway.
Referensi konfigurasi Edge Microgateway
Lokasi file konfigurasi
Atribut konfigurasi yang dijelaskan di bagian ini ada di file konfigurasi Edge Microgateway. Lihat juga Membuat perubahan konfigurasi.
atribut edge_config
Setelan ini digunakan untuk mengonfigurasi interaksi antara instance Edge Microgateway dan Apigee Edge.
- bootstrap: (default: none) URL yang mengarah ke layanan khusus Edge Microgateway yang berjalan di Apigee Edge. Edge Microgateway menggunakan layanan ini untuk
berkomunikasi dengan Apigee Edge. URL ini akan ditampilkan saat Anda menjalankan perintah untuk membuat pasangan kunci publik/pribadi:
edgemicro genkeys
. Lihat Menyiapkan dan mengonfigurasi Edge Microgateway untuk mengetahui detailnya. - jwt_public_key: (default: none) URL yang mengarah ke proxy Edge Microgateway yang di-deploy di Apigee Edge. Proxy ini berfungsi sebagai endpoint autentikasi untuk mengeluarkan token akses bertanda tangan ke klien. URL ini ditampilkan saat Anda menjalankan perintah untuk men-deploy proxy: edgemicro configure. Lihat Menyiapkan dan mengonfigurasi Edge Microgateway untuk mengetahui detailnya.
- quotaUri: Tetapkan properti konfigurasi ini jika Anda ingin mengelola kuota melalui proxy
edgemicro-auth
yang di-deploy ke organisasi Anda. Jika properti ini tidak disetel, endpoint kuota akan ditetapkan secara default ke endpoint Edge Microgateway internal.edge_config: quotaUri: https://your_org-your_env.apigee.net/edgemicro-auth
Untuk menggunakan fitur ini, Anda harus terlebih dahulu men-deploy proxy
edgemicro-auth
versi 3.0.5 atau yang lebih baru ke organisasi Anda. Untuk mengetahui detailnya, lihat Mengupgrade proxy edgemicro-auth.
Atribut edgemicro
Setelan ini mengonfigurasi proses Edge Microgateway.
- port: (default: 8000) Nomor port yang digunakan oleh proses Edge Microgateway.
- max_connections: (default: -1) Menentukan jumlah maksimum koneksi masuk simultan yang dapat diterima Edge Microgateway. Jika jumlah ini terlampaui, status berikut akan ditampilkan:
res.statusCode = 429; // Too many requests
- max_connections_hard: (default: -1) Jumlah maksimum permintaan serentak yang dapat diterima Edge Microgateway sebelum menonaktifkan koneksi. Setelan ini dimaksudkan untuk menggagalkan serangan denial of service. Biasanya, tetapkan ke angka yang lebih besar dari max_connections.
-
logging:
-
level: (default: error)
- info - Mencatat semua permintaan dan respons yang mengalir melalui instance Edge Microgateway ke dalam log.
- warn - Mencatat pesan peringatan saja.
- error - Hanya mencatat pesan error dalam log.
- dir: (default: /var/tmp) Direktori tempat file log disimpan.
- stats_log_interval: (default: 60) Interval, dalam detik, saat catatan statistik ditulis ke file log api.
- rotate_interval: (default: 24) Interval, dalam jam, saat file log dirotasi.
-
level: (default: error)
- plugin: Plugin menambahkan fungsi ke Edge Microgateway. Untuk mengetahui detail cara mengembangkan plugin, lihat Mengembangkan plugin kustom.
- dir: Jalur relatif dari direktori ./gateway ke direktori ./plugins, atau jalur absolut.
- sequence: Daftar modul plugin yang akan ditambahkan ke instance Edge Microgateway. Modul akan dieksekusi sesuai urutan yang ditentukan di sini.
-
debug: Menambahkan proses debug jarak jauh ke proses Edge Microgateway.
- port: Nomor port yang akan diproses. Misalnya, setel debugger IDE Anda untuk memproses port ini.
- args: Argumen untuk proses debug. Contoh:
args --nolazy
- config_change_poll_interval: (default: 600 detik) Edge Microgateway
memuat konfigurasi baru secara berkala dan menjalankan pemuatan ulang jika ada perubahan. Polling ini
mendeteksi setiap perubahan yang dibuat di Edge (perubahan pada produk, proxy yang peka terhadap microgateway, dll.) serta
perubahan yang dibuat pada file konfigurasi lokal.
- disable_config_poll_interval: (default: false) Tetapkan ke true untuk menonaktifkan polling perubahan otomatis.
- request_timeout: Menetapkan waktu tunggu untuk permintaan target. Waktu tunggu disetel dalam detik. Jika waktu tunggu habis, Edge Microgateway akan merespons dengan kode status 504. (Ditambahkan v2.4.x)
atribut header
Setelan ini mengonfigurasi cara header HTTP tertentu diperlakukan.
- x-forwarded-for: (default: true) Tetapkan ke false agar header tidak diteruskan ke target. Perhatikan bahwa jika header x-forwarded-for ada dalam permintaan, nilainya akan ditetapkan ke nilai client-ip di Edge Analytics.
- x-forwarded-host: (default: true) Tetapkan ke false untuk mencegah header x-forwarded-host diteruskan ke target.
- x-request-id: (default: true) Tetapkan ke false untuk mencegah header x-request-id diteruskan ke target.
- x-response-time: (default: true) Setel ke false untuk mencegah header waktu respons x diteruskan ke target.
- via: (default: true) Tetapkan ke false untuk mencegah diteruskannya header ke target.
atribut oauth
Setelan ini mengonfigurasi cara autentikasi klien diterapkan oleh Edge Microgateway.
- allowNoAuthorization: (default: false) Jika ditetapkan ke true, panggilan API akan diizinkan untuk melewati Edge Microgateway tanpa header Authorization sama sekali. Tetapkan parameter ini ke false untuk mewajibkan header Authorization (default).
- allowInvalidAuthorization: (default: false) Jika ditetapkan ke true, panggilan API akan diizinkan untuk diteruskan jika token yang diteruskan di header Authorization tidak valid atau sudah tidak berlaku. Tetapkan kolom ini ke false untuk mewajibkan token yang valid (default).
- authorization-header: (default: Authorization: Bearer) Header yang digunakan untuk mengirim token akses ke Edge Microgateway. Anda dapat mengubah setelan default jika target perlu menggunakan header Authorization untuk beberapa tujuan lain.
- api-key-header: (default: x-api-key) Nama header atau parameter kueri yang digunakan untuk meneruskan kunci API ke Edge Microgateway. Lihat juga Menggunakan kunci API.
- keep-authorization-header: (default: false) Jika ditetapkan ke true, header Authorization yang dikirim dalam permintaan akan diteruskan ke target (hal ini dipertahankan).
- allowOAuthOnly -- Jika ditetapkan ke true, setiap API harus membawa header Otorisasi dengan Token Akses Pembawa. Memungkinkan Anda hanya mengizinkan model keamanan OAuth (dengan tetap mempertahankan kompatibilitas mundur). (Ditambahkan 2.4.x)
- allowAPIKeyOnly -- Jika ditetapkan ke true, setiap API harus membawa header x-api-key (atau lokasi kustom) dengan Kunci API.Memungkinkan Anda hanya mengizinkan model keamanan kunci API (sekaligus mempertahankan kompatibilitas mundur). (Menambahkan 2.4.x)
- gracePeriod -- Parameter ini membantu mencegah error yang disebabkan oleh sedikit perbedaan antara waktu sistem dan waktu Tidak Sebelum (nbf) atau Dikeluarkan Pada (iat) yang ditentukan dalam token otorisasi JWT. Setel parameter ini ke jumlah detik untuk memungkinkan perbedaan tersebut. (Ditambahkan 2.5.7)
Atribut khusus plugin
Lihat Menggunakan plugin untuk mengetahui detail tentang atribut yang dapat dikonfigurasi untuk setiap plugin.
Memfilter proxy
Anda dapat memfilter proxy berbasis microgateway mana yang akan diproses oleh instance Edge Microgateway.
Saat Edge Microgateway dimulai, Edge akan mendownload semua proxy yang peka terhadap microgateway di
organisasi yang terkait dengannya. Gunakan konfigurasi berikut untuk membatasi proxy yang akan diproses oleh microgateway. Misalnya, konfigurasi ini membatasi proxy yang akan diproses oleh microgateway ke tiga: edgemicro_proxy-1
, edgemicro_proxy-2
, dan edgemicro_proxy-3
:
proxies: - edgemicro_proxy-1 - edgemicro_proxy-2 - edgemicro_proxy-3
Mengonfigurasi frekuensi push analisis
Gunakan parameter konfigurasi ini untuk mengontrol frekuensi Edge Microgateway mengirim data analisis ke Apigee:
- bufferSize (Opsional): Jumlah maksimum data analisis yang dapat ditampung buffer sebelum mulai menghapus data terlama. Default: 10000
- batchSize (Opsional): Ukuran maksimum batch data analisis yang dikirim ke Apigee. Default: 500
- flushInterval (Opsional): Jumlah milidetik antara setiap flush batch data analisis yang dikirim ke Apigee. Default: 5000
Contoh:
analytics: bufferSize: 15000 batchSize: 1000 flushInterval: 6000
Menyamarkan data analisis
Konfigurasi berikut mencegah informasi jalur permintaan muncul di analisis Edge. Tambahkan baris berikut ke konfigurasi microgateway untuk menyamarkan URI permintaan dan/atau jalur permintaan. Perhatikan bahwa URI terdiri dari nama host dan bagian jalur dari permintaan.
analytics: mask_request_uri: 'string_to_mask' mask_request_path: 'string_to_mask'
Memisahkan panggilan API di Edge Analytics
Anda dapat mengonfigurasi plugin analisis untuk memisahkan jalur API tertentu agar muncul sebagai proxy terpisah di dasbor Edge Analytics. Misalnya, Anda dapat memisahkan API health check di dasbor agar tidak membingungkannya dengan panggilan proxy API sebenarnya. Di dasbor Analytics, proxy yang terpisah mengikuti pola penamaan ini:
edgemicro_proxyname-health
Gambar berikut menampilkan dua proxy yang dipisahkan di dasbor Analytics: edgemicro_hello-health
dan
edgemicro_mock-health
:
Gunakan parameter ini untuk memisahkan jalur relatif dan absolut di dasbor Analytics sebagai proxy terpisah:
- relativePath (Opsional): Menentukan jalur relatif yang akan dipisahkan di dasbor Analytics. Misalnya, jika Anda menentukan
/healthcheck
, semua panggilan API yang berisi jalur/healthcheck
akan muncul di dasbor sebagaiedgemicro_proxyname-health
. Perhatikan bahwa tanda ini mengabaikan jalur dasar proxy. Untuk memisahkan berdasarkan jalur lengkap, termasuk jalur dasar, gunakan flagproxyPath
. - proxyPath (Opsional): Menentukan jalur proxy API lengkap, termasuk basepath proxy, yang akan dipisahkan di dasbor analisis. Misalnya, jika Anda menentukan
/mocktarget/healthcheck
, dengan/mocktarget
sebagai basepath proxy, semua panggilan API dengan jalur/mocktarget/healthcheck
akan muncul di dasbor sebagaiedgemicro_proxyname-health
.
Misalnya, dalam konfigurasi berikut, setiap jalur API yang berisi /healthcheck
akan
dipisahkan oleh plugin analisis. Artinya, /foo/healthcheck
dan /foo/bar/healthcheck
akan dipisahkan sebagai proxy terpisah yang disebut edgemicro_proxyname-health
di dasbor analisis.
analytics: uri: >- https://xx/edgemicro/ax/org/docs/environment/test bufferSize: 100 batchSize: 50 flushInterval: 500 relativePath: /healthcheck
Dalam konfigurasi berikut, setiap API dengan jalur proxy /mocktarget/healthcheck
akan dipisahkan sebagai proxy terpisah yang disebut edgemicro_proxyname-health
di dasbor analisis.
analytics: uri: >- https://xx/edgemicro/ax/org/docs/environment/test bufferSize: 100 batchSize: 50 flushInterval: 500 proxyPath: /mocktarget/healthcheck
Menyiapkan Edge Microgateway di balik firewall perusahaan
Versi v2.4.x yang didukung
Jika Edge Microgateway diinstal di belakang firewall, gateway tersebut mungkin tidak dapat berkomunikasi dengan Apigee Edge. Dalam hal ini, ada dua opsi yang dapat Anda pertimbangkan:
Opsi 1:
Opsi pertama adalah menetapkan opsi edgemicro: proxy_tunnel ke true dalam file konfigurasi microgateway:
edge_config: proxy: http://10.224.16.85:3128 proxy_tunnel: true
Jika proxy_tunnel bernilai true, Edge Microgateway akan menggunakan metode CONNECT HTTP untuk tunnel permintaan HTTP melalui koneksi TCP tunggal. (Hal yang sama berlaku jika variabel lingkungan untuk mengonfigurasi proxy mengaktifkan TLS).
Opsi 2:
Opsi kedua adalah menentukan proxy dan menetapkan proxy_tunnel ke false dalam file konfigurasi microgateway. Contoh:
edge_config: proxy: http://10.224.16.85:3128 proxy_tunnel: false
Dalam kasus ini, Anda dapat menetapkan variabel berikut untuk mengontrol host bagi setiap proxy HTTP yang ingin digunakan, atau host mana yang tidak boleh menangani proxy Edge Microgateway: HTTP_PROXY, HTTPS_PROXY, dan NO_PROXY.
Anda dapat menetapkan NO_PROXY sebagai daftar domain yang dipisahkan koma yang tidak boleh dijadikan proxy oleh Edge Microgateway. Contoh:
export NO_PROXY='localhost,localhost:8080'
Setel HTTP_PROXY dan HTTPS_PROXY ke endpoint proxy HTTP Edge Microgateway dapat mengirim pesan ke endpoint. Contoh:
export HTTP_PROXY='http://localhost:3786' export HTTPS_PROXY='https://localhost:3786'
Untuk mengetahui informasi selengkapnya tentang variabel ini, lihat https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables
Lihat juga
Cara menyiapkan Edge Microgateway di balik firewall perusahaan di Komunitas Apigee.
Menggunakan karakter pengganti di proxy yang mendukung Microgateway
Anda dapat menggunakan satu atau beberapa karakter pengganti "*" di jalur dasar proxy edgemicro_* (Microgateway-aware). Misalnya, jalur dasar /team/*/members memungkinkan klien memanggil https://[host]/team/blue/members dan https://[host]/team/green/members tanpa mengharuskan Anda membuat proxy API baru untuk mendukung tim baru. Perlu diperhatikan bahwa /**/
tidak didukung.
Penting: Apigee TIDAK mendukung penggunaan karakter pengganti "*" sebagai elemen pertama dari jalur dasar. Misalnya, hal ini TIDAK didukung: penelusuran /*/
.
Merotasi kunci JWT
Pada waktu tertentu setelah mulai membuat JWT, Anda mungkin perlu mengubah pasangan kunci publik/pribadi yang disimpan di KVM yang dienkripsi Edge. Proses menghasilkan pasangan kunci baru ini disebut rotasi kunci.
Cara Edge Microgateway menggunakan JWT
JSON Web Token (JWT) adalah standar token yang dijelaskan di RFC7519. JWT menyediakan cara untuk menandatangani serangkaian klaim, yang dapat diverifikasi dengan andal oleh penerima JWT.
Edge Microgateway menggunakan JWT sebagai token pemilik untuk keamanan OAuth. Saat membuat token OAuth untuk Edge Microgateway, Anda akan menerima kembali JWT. Anda kemudian dapat menggunakan JWT di header Otorisasi panggilan API. Contoh:
curl -i http://localhost:8000/hello -H "Authorization: Bearer eyJhbGciOiJ..dXDefZEA"
Membuat JWT baru
Anda dapat membuat JWT untuk Edge Microgateway menggunakan perintah edgemicro token
atau API. Contoh:
edgemicro token get -o docs -e test -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy
Perintah ini meminta Apigee Edge untuk menghasilkan JWT yang kemudian dapat digunakan untuk memverifikasi panggilan API. Parameter -i
dan -s
adalah ID konsumen dan nilai rahasia dari aplikasi developer di organisasi Apigee Edge Anda.
Atau, Anda juga dapat membuat JWT menggunakan API pengelolaan:
curl -i -X POST "http://org-env.apigee.net/edgemicro-auth/token" \ -H "Content-Type: application/json" \ -d '{ "client_id": "your consumer key", "client_secret": "your consumer secret", "grant_type": "client_credentials" }'
Dengan keterangan:
- org adalah nama organisasi Edge Anda (Anda harus menjadi administrator org).
- env adalah lingkungan dalam organisasi Anda (seperti "test" atau "prod").
- client_id adalah ID Konsumen di Aplikasi Developer yang Anda buat sebelumnya.
- client_secret adalah Rahasia Konsumen di Aplikasi Developer yang Anda buat sebelumnya.
Apa itu rotasi kunci?
Pada waktu tertentu setelah mulai membuat JWT, Anda mungkin perlu mengubah pasangan kunci publik/pribadi yang disimpan di KVM yang dienkripsi Edge. Proses menghasilkan pasangan kunci baru ini disebut rotasi kunci. Saat Anda merotasi kunci, pasangan kunci pribadi/publik baru akan dihasilkan dan disimpan di KVM "microgateway" dalam organisasi/lingkungan Apigee Edge Anda. Selain itu, kunci publik lama dipertahankan bersama dengan nilai ID kunci aslinya.
Untuk menghasilkan JWT, Edge menggunakan informasi yang disimpan di KVM terenkripsi. KVM
bernama microgateway
telah dibuat dan diisi dengan kunci saat Anda pertama kali menyiapkan (mengonfigurasi)
Edge Microgateway. Kunci di KVM digunakan untuk menandatangani dan mengenkripsi JWT.
Kunci KVM meliputi:
-
private_key - Kunci pribadi RSA terbaru (yang terakhir dibuat) yang digunakan untuk menandatangani JWT.
-
public_key - Sertifikat terbaru (yang terakhir dibuat) yang digunakan untuk memverifikasi JWT yang ditandatangani dengan private_key.
-
private_key_kid - ID kunci pribadi terbaru (yang terakhir dibuat). ID kunci ini terkait dengan nilai private_key dan digunakan untuk mendukung rotasi kunci.
-
public_key1_kid - ID kunci publik terbaru (yang terakhir dibuat). Kunci ini terkait dengan nilai public_key1 dan digunakan untuk mendukung rotasi kunci. Nilai ini sama dengan turunan kunci pribadi.
-
public_key1 - Kunci publik terbaru (terakhir dibuat).
Saat Anda melakukan rotasi kunci, nilai kunci yang ada akan diganti di peta dan kunci baru akan ditambahkan untuk mempertahankan kunci publik lama. Contoh:
-
public_key2_kid - ID kunci publik lama. Kunci ini dikaitkan dengan nilai public_key2 dan digunakan untuk mendukung rotasi kunci.
-
public_key2 - Kunci publik lama.
JWT yang ditampilkan untuk verifikasi akan diverifikasi menggunakan kunci publik baru. Jika verifikasi gagal, kunci publik lama akan digunakan, sampai masa berlakunya habis (setelah 30 menit). Dengan cara ini, Anda dapat "merotasi" kunci tanpa langsung mengganggu traffic API.
Cara melakukan rotasi kunci
Bagian ini menjelaskan cara melakukan rotasi kunci.
Jika Anda mengonfigurasi instance Edge Microgateway sebelum versi 2.5.2
Jika instance Edge Microgateway dikonfigurasi sebelum versi 2.5.2, Anda harus menjalankan dua perintah berikut untuk mengupgrade KVM dan kebijakan autentikasi:
upgradekvm -o org -e env -u username
Untuk informasi selengkapnya tentang perintah ini, lihat Mengupgrade KVM.
Perintah berikutnya mengupgrade proxy edgemicro-oauth yang di-deploy ke organisasi Apigee Anda saat Anda mengonfigurasi Edge Microgateway. Proxy ini menyediakan layanan yang diperlukan untuk menghasilkan token.
upgradeauth -o org -e env -u username
Untuk mengetahui informasi selengkapnya tentang perintah ini, lihat Mengupgrade proxy edgemicro-auth.
Memutar tombol
Tambahkan baris berikut ke file ~/.edgemicro/org-env-config.yaml
. Di sini, Anda harus menentukan organisasi dan lingkungan yang sama dengan yang Anda konfigurasikan untuk digunakan oleh microgateway:
jwk_public_keys: 'https://org-env.apigee.net/edgemicro-auth/jwkPublicKeys'
Jalankan perintah rotasi kunci untuk merotasi kunci. (Untuk informasi selengkapnya tentang perintah ini, lihat Merotasi tombol.)
edgemicro rotatekey -o org -e env -u username -k kid_value
Contoh:
edgemicro rotatekey -o jdoe -e test -u jdoe@google.com -k 2 current nodejs version is v12.5.0 current edgemicro version is 3.0.2 password: Checking if private key exists in the KVM... Checking for certificate... Found Certificate Generating New key/cert pair... Extract new public key Key Rotation successfully completed!
Parameter -k
menentukan ID Kunci (anak). ID ini digunakan untuk mencocokkan kunci tertentu.
Edge Microgateway menggunakan nilai ini untuk memilih di antara serangkaian kunci selama rotasi kunci. Untuk mengetahui informasi selengkapnya, baca Bagian 4.5 spesifikasi Kunci Web JSON.
Setelah kunci dirotasi, Edge akan menampilkan beberapa tombol ke Edge Microgateway. Perhatikan pada contoh berikut, setiap kunci memiliki nilai "anak" (ID Kunci) yang unik. Microgateway kemudian menggunakan kunci ini untuk memvalidasi token otorisasi. Jika validasi token gagal, microgateway akan memeriksa apakah ada kunci yang lebih lama dalam rangkaian kunci dan mencoba kunci tersebut. Format kunci yang ditampilkan adalah JSON Web Key (JWK). Anda dapat membaca tentang format ini di RFC 7517.
{ "keys": [ { "kty": "RSA", "n": "nSl7R_0wKLiWi6cO3n8aOJwYGBtinq723Jgg8i7KKWTSTYoszOjgGsJf_MX4JEW1YCScwpE5o4o8ccQN09iHVTlIhk8CNiMZNPipClmRVjaL_8IWvMQp1iN66qy4ldWXzXnHfivUZZogCkBNqCz7VSC5rw2Jf57pdViULVvVDGwTgf46sYveW_6h8CAGaD0KLd3vZffxIkoJubh0yMy0mQP3aDOeIGf_akeZeZ6GzF7ltbKGd954iNTiKmdm8IKhz6Y3gLpC9iwQ-kex_j0CnO_daHl1coYxUSCIdv4ziWIeM3dmjQ5_2dEvUDIGG6_Az9hTpNgPE5J1tvrOHAmunQ", "e": "AQAB", "kid": "2" }, { "kty": "RSA", "n": "8BKwzx34BMUcHwTuQtmp8LFRCMxbkKg_zsWD6eOMIUTAsORexTGJsTy7z-4aH0wJ3fT-3luAAUPLBQwGcuHo0P1JnbtPrpuYjaJKSZOeIMOnlryJCspmv-1xG4qAqQ9XaZ9C97oecuj7MMoNwuaZno5MvsY-oi5B_gqED3vIHUjaWCErd4reONyFSWn047dvpE6mwRhZbcOTkAHT8ZyKkHISzopkFg8CD-Mij12unxA3ldcTV7yaviXgxd3eFSD1_Z4L7ZRsDUukCJkJ-8qY2-GWjewzoxl-mAW9D1tLK6qAdc89yFem3JHRW6L1le3YK37-bs6b2a_AqJKsKm5bWw", "e": "AQAB", "kid": "1" } ] }
Memfilter proxy yang didownload
Secara default, Edge Microgateway akan mendownload semua proxy di organisasi Edge Anda yang dimulai dengan awalan penamaan "edgemicro_". Anda dapat mengubah default ini untuk mendownload proxy yang namanya cocok dengan pola.
- Buka file konfigurasi Edge Micro:
~/.edgemicro/org-env-config.yaml
- Tambahkan elemen proxyPattern di bagian edge_config. Misalnya, pola berikut akan
mendownload proxy seperti edgemicro_foo, edgemicro_fast, dan edgemicro_first.
edge_config: … proxyPattern: edgemicro_f*
Menentukan produk tanpa proxy API
Di Apigee Edge, Anda dapat membuat produk API yang tidak berisi proxy API apa pun. Konfigurasi produk ini memungkinkan kunci API yang terkait dengan produk tersebut berfungsi dengan proxy apa pun yang di-deploy di organisasi Anda. Mulai versi 2.5.4, Edge Microgateway mendukung konfigurasi produk ini.
Proses debug dan pemecahan masalah
Menghubungkan ke debugger
Anda dapat menjalankan Edge Microgateway dengan debugger, seperti node-inspector. Hal ini berguna untuk memecahkan masalah dan men-debug plugin kustom.
- Mulai ulang Edge Microgateway dalam mode debug. Untuk melakukannya, tambahkan
DEBUG=*
ke awal perintahstart
. Contoh:DEBUG=* edgemicro start -o myorg -e test -k db4e9e8a95aa7fabfdeacbb1169d0a8cbe42bec19c6b98129e02 -s 6e56af7c1b26dfe93dae78a735c8afc9796b077d105ae5618ce7ed
- Mulai debugger dan setel agar memproses nomor port untuk proses debug.
- Kini Anda dapat menyusuri kode Edge Microgateway, menetapkan titik henti sementara, ekspresi smartwatch, dan sebagainya.
Anda dapat menentukan flag Node.js standar yang terkait dengan mode debug. Misalnya,
--nolazy
membantu men-debug kode asinkron.
Memeriksa file log
Jika mengalami masalah, pastikan Anda memeriksa file log untuk mengetahui detail eksekusi dan informasi error. Untuk mengetahui detailnya, lihat Mengelola file log.
Menggunakan keamanan kunci API
Kunci API menyediakan mekanisme sederhana untuk mengautentikasi klien yang membuat permintaan ke Edge Microgateway. Anda dapat memperoleh kunci API dengan menyalin nilai Kunci Konsumen (juga disebut Client-ID) dari produk Apigee Edge yang menyertakan proxy autentikasi Edge Microgateway.
Menyimpan cache kunci
Kunci API dipertukarkan untuk token pemilik, yang di-cache. Anda dapat menonaktifkan caching dengan menyetel header Cache-Control: no-cache
pada permintaan masuk ke Edge Microgateway.
Menggunakan kunci API
Anda dapat meneruskan kunci API dalam permintaan API sebagai parameter kueri atau di header. Secara default, header dan nama parameter kueri adalah x-api-key
.
Contoh parameter kueri:
curl http://localhost:8000/foobar?x-api-key=JG616Gjz7xs4t0dvpvVsGdI49G34xGsz
Contoh tajuk:
curl http://localhost:8000/foobar -H "x-api-key:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"
Mengonfigurasi nama kunci API
Secara default, x-api-key
adalah nama yang digunakan untuk header kunci API dan parameter kueri.
Anda dapat mengubah setelan default ini di file konfigurasi, seperti yang dijelaskan dalam Membuat perubahan konfigurasi. Misalnya, untuk mengubah nama menjadi apiKey:
oauth: allowNoAuthorization: false allowInvalidAuthorization: false api-key-header: apiKey
Dalam contoh ini, parameter kueri dan nama header diubah menjadi apiKey
. Nama
x-api-key
tidak akan berfungsi lagi pada kedua kasus tersebut. Lihat juga
Membuat perubahan konfigurasi.
Contoh:
curl http://localhost:8000/foobar -H "apiKey:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"
Untuk mengetahui informasi selengkapnya tentang penggunaan kunci API dengan permintaan proxy, lihat Mengamankan Edge Microgateway.
Mengaktifkan kode respons upstream
Secara default, plugin oauth
hanya menampilkan kode status error 4xx jika responsnya bukan status 200. Anda dapat mengubah perilaku ini agar selalu menampilkan kode 4xx atau 5xx yang tepat, bergantung pada error-nya. (Dirilis dalam versi 3.0.7)
Untuk mengaktifkan fitur ini, tambahkan properti oauth.useUpstreamResponse: true
ke konfigurasi Edge Microgateway Anda. Contoh:
oauth: allowNoAuthorization: false allowInvalidAuthorization: false gracePeriod: 10 useUpstreamResponse: true
Menggunakan keamanan token OAuth2
Bagian ini menjelaskan cara mendapatkan token akses OAuth2 dan token refresh. Token akses digunakan untuk membuat panggilan API yang aman melalui microgateway. Token refresh digunakan untuk mendapatkan token akses baru.
Cara mendapatkan token akses
Bagian ini menjelaskan cara menggunakan proxy edgemicro-auth
untuk mendapatkan token akses.
Anda juga bisa mendapatkan token akses menggunakan perintah CLI edgemicro token
.
Untuk mengetahui detail tentang CLI, lihat Mengelola token.
API 1: Mengirim kredensial sebagai parameter isi
Ganti nama organisasi dan lingkungan Anda di URL, dan ganti nilai Consumer ID dan Consumer Secret yang diperoleh dari aplikasi developer di Apigee Edge untuk parameter isi client_id dan client_secret:
curl -i -X POST "http://<org>-<test>.apigee.net/edgemicro-auth/token" \ -d '{"grant_type": "client_credentials", "client_id": "your_client_id", \ "client_secret": "your_client_secret"}' -H "Content-Type: application/json"
API 2: Mengirim kredensial di header Basic Auth
Kirim kredensial klien sebagai header Autentikasi Dasar dan grant_type
sebagai parameter formulir. Formulir perintah ini juga dibahas di
RFC 6749: Framework Otorisasi OAuth 2.0.
http://<org>-<test>.apigee.net/edgemicro-auth/token -v -u your_client_id:your_client_secret \ -d 'grant_type=client_credentials' -H "Content-Type: application/x-www-form-urlencoded"
Contoh output
API menampilkan respons JSON. Perhatikan bahwa tidak ada perbedaan antara propertitoken
dan
access_token
. Anda dapat menggunakan salah satunya.
{ "token": "eyJraWQiOiIxIiwidHlwIjoi", "access_token": "eyJraWQiOiIxIiwid", "token_type": "bearer", "expires_in": "108000" }
Cara mendapatkan token refresh
Untuk mendapatkan token refresh, lakukan panggilan API ke endpoint /token
dari proxy edgemicro-auth
. Anda HARUS melakukan panggilan API ini dengan jenis pemberian password
. Ikuti langkah-langkah berikut dalam prosesnya.
- Dapatkan token akses dan refresh dengan
/token
API. Perhatikan bahwa jenis pemberian adalahpassword
:curl -X POST \ https://your_organization-your_environment.apigee.net/edgemicro-auth/token \ -H 'Content-Type: application/json' \ -d '{ "client_id":"mpK6l1Bx9oE5zLdifoDbF931TDnDtLq", "client_secret":"bUdDcFgv3nXffnU", "grant_type":"password", "username":"mpK6lBx9RoE5LiffoDbpF931TDnDtLq", "password":"bUdD2FvnMsXffnU" }'
API menampilkan token akses dan token refresh. Responsnya terlihat mirip dengan ini:
{ "token": "your-access-token", "access_token": "your-access-token", "token_type": "bearer", "expires_in": "108000", "refresh_token": "your-refresh-token", "refresh_token_expires_in": "431999", "refresh_token_issued_at": "1562087304302", "refresh_token_status": "approved" }
- Kini Anda dapat menggunakan token refresh untuk mendapatkan token akses baru dengan memanggil endpoint
/refresh
dari API yang sama. Contoh:curl -X POST \ https://willwitman-test.apigee.net/edgemicro-auth/refresh \ -H 'Content-Type: application/json' \ -d '{ "client_id":"mpK6l1Bx9RoE5zLifoDbpF931TDnDtLq", "client_secret":"bUdDc2Fv3nMXffnU", "grant_type":"refresh_token", "refresh_token":"your-refresh-token" }'
API menampilkan token akses baru. Responsnya terlihat mirip dengan ini:
{ "token": "your-new-access-token" }
Pemantauan selamanya
Forever adalah alat Node.js yang otomatis memulai ulang aplikasi Node.js jika prosesnya turun atau mengalami error. Edge Microgateway memiliki file forever.json yang dapat Anda konfigurasi untuk mengontrol frekuensi dan interval apa Edge Microgateway harus dimulai ulang. File ini mengonfigurasi layanan Forever yang disebut forever-monitor, yang mengelola Forever secara terprogram.
Anda dapat menemukan file forever.json di direktori penginstalan root Edge Microgateway. Lihat Di mana Edge Microgateway diinstal. Untuk detail tentang opsi konfigurasi, lihat dokumentasi pantauan selamanya.
Perintah edgemicro forever
menyertakan flag yang memungkinkan Anda menentukan lokasi file forever.json
(flag -f
), dan memulai/menghentikan proses pemantauan Forever (flag -a
). Contoh:
edgemicro forever -f ~/mydir/forever.json -a start
Untuk mengetahui informasi selengkapnya, lihat Pemantauan selamanya dalam referensi CLI.
Menentukan endpoint file konfigurasi
Jika menjalankan beberapa instance Edge Microgateway, Anda mungkin ingin mengelola konfigurasinya dari satu lokasi. Anda dapat melakukannya dengan menentukan endpoint HTTP tempat Edge Micro dapat mendownload file konfigurasinya. Anda dapat menentukan endpoint ini saat memulai Edge Micro menggunakan flag -u.
Contoh:
edgemicro start -o jdoe -e test -u http://mylocalserver/mgconfig -k public_key -s secret_key
di mana endpoint mgconfig menampilkan
isi file konfigurasi Anda. Ini adalah file yang, secara default, terletak di ~/.edgemicro
dan memiliki konvensi penamaan: org-env-config.yaml
.
Menonaktifkan buffering data koneksi TCP
Anda dapat menggunakan atribut konfigurasi nodelay
guna menonaktifkan buffering data untuk
koneksi TCP yang digunakan oleh Edge Microgateway.
Secara default koneksi TCP menggunakan algoritma
Nagle untuk melakukan buffer data sebelum mengirimnya. Menetapkan nodelay
ke true
,
akan menonaktifkan perilaku ini (data akan segera mengaktifkan data setiap kali
socket.write()
dipanggil). Baca juga dokumentasi Node.js untuk mengetahui detail selengkapnya.
Untuk mengaktifkan nodelay
, edit file konfigurasi Edge Micro sebagai berikut:
edgemicro: nodelay: true port: 8000 max_connections: 1000 config_change_poll_interval: 600 logging: level: error dir: /var/tmp stats_log_interval: 60 rotate_interval: 24
Menjalankan Edge Microgateway dalam mode mandiri
Anda dapat menjalankan Edge Microgateway yang terputus sepenuhnya dari dependensi Apigee Edge apa pun. Skenario ini, yang disebut mode mandiri, memungkinkan Anda menjalankan dan menguji Edge Microgateway tanpa koneksi Internet.
Dalam mode mandiri, fitur berikut tidak berfungsi karena memerlukan koneksi ke Apigee Edge:
- OAuth dan kunci API
- Kuota
- Analytics
Di sisi lain, plugin kustom dan penahanan lonjakan berfungsi secara normal, karena tidak
memerlukan koneksi ke Apigee Edge. Selain itu, plugin baru bernama extauth
memungkinkan Anda mengizinkan panggilan API ke microgateway dengan JWT saat dalam mode mandiri.
Mengonfigurasi dan memulai gateway
Untuk menjalankan Edge Microgateway dalam mode mandiri:
- Pastikan Anda telah menginstal Edge Microgateway versi 3.0.1 atau yang lebih baru. Jika tidak, Anda harus
menjalankan perintah berikut untuk mengupgrade ke versi terbaru:
npm install -g edgemicro
Jika Anda memerlukan bantuan, lihat Menginstal Edge Microgateway.
- Buat file konfigurasi bernama sebagai berikut:
$HOME/.edgemicro/
org_name-
env_name-config.yaml
Contoh:
vi $HOME/.edgemicro/foo-bar-config.yaml
- Tempel kode berikut ke dalam file:
edgemicro: port: 8000 max_connections: 1000 config_change_poll_interval: 600 logging: level: error dir: /var/tmp stats_log_interval: 60 rotate_interval: 24 plugins: sequence: - extauth - spikearrest headers: x-forwarded-for: true x-forwarded-host: true x-request-id: true x-response-time: true via: true extauth: publickey_url: https://www.googleapis.com/oauth2/v1/certs spikearrest: timeUnit: second allow: 10 buffersize: 0
- Ekspor variabel lingkungan berikut dengan nilai "1":
export EDGEMICRO_LOCAL=1
- Jalankan perintah
start
berikut, tempat Anda memasukkan nilai untuk membuat instance proxy lokal:edgemicro start -o org_name -e environment_name -a local_proxy_name \ -v local_proxy_version -t target_url -b base_path
Dengan keterangan:
- your_org adalah nama "org" yang Anda gunakan dalam nama file konfigurasi.
- your_environment adalah nama "env" yang Anda gunakan dalam nama file konfigurasi.
- local_proxy_name adalah nama proxy lokal yang akan dibuat. Anda dapat menggunakan nama apa pun yang diinginkan.
- local_proxy_version adalah nomor versi proxy.
- target_url adalah URL untuk target proxy. (Target adalah layanan yang dipanggil proxy.)
- base_path adalah jalur dasar proxy. Nilai ini harus diawali dengan garis miring. Untuk jalur dasar root, hanya tentukan garis miring; misalnya, "/".
Contoh:
edgemicro start -o local -e test -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
- Uji konfigurasi.
curl http://localhost:8000/echo { "error" : "missing_authorization" }
Karena plugin
extauth
ada dalam filefoo-bar-config.yaml
, Anda akan mendapatkan error "missing_authorization". Plugin ini memvalidasi JWT yang harus ada di header Otorisasi panggilan API. Di bagian berikutnya, Anda akan mendapatkan JWT yang akan memungkinkan panggilan API berjalan tanpa error.
Contoh: Memperoleh token otorisasi
Contoh berikut menunjukkan cara mendapatkan JWT dari endpoint JWT Edge Microgateway di Apigee Edge (edgemicro-auth/jwkPublicKeys
).
Endpoint ini di-deploy saat Anda melakukan penyiapan dan konfigurasi standar Edge Microgateway.
Untuk mendapatkan JWT dari endpoint Apigee, Anda harus melakukan penyiapan Edge Microgateway standar terlebih dahulu dan
terhubung ke Internet. Endpoint Apigee digunakan di sini hanya sebagai contoh dan tidak diperlukan. Anda dapat menggunakan endpoint token JWT lain jika ingin. Jika melakukannya, Anda harus mendapatkan JWT menggunakan API yang disediakan untuk endpoint tersebut.
Langkah-langkah berikut menjelaskan cara mendapatkan token menggunakan endpoint edgemicro-auth/jwkPublicKeys
:
- Anda harus melakukan penyiapan dan konfigurasi
standar Edge Microgateway untuk men-deploy proxy
edgemicro-auth
ke organisasi/lingkungan Anda di Apigee Edge. Jika telah melakukan langkah ini sebelumnya, Anda tidak perlu mengulanginya. - Jika men-deploy Edge Microgateway ke Apigee Cloud, Anda harus terhubung ke internet agar dapat memperoleh JWT dari endpoint ini.
-
Menghentikan Edge Microgateway:
edgemicro stop
- Dalam file konfigurasi yang Anda buat sebelumnya (
$HOME/.edgemicro
/org-env-config.yaml
), arahkan atributextauth:publickey_url
ke endpointedgemicro-auth/jwkPublicKeys
di organisasi/lingkungan Apigee Edge Anda. Contoh:extauth: publickey_url: 'https://your_org-your_env.apigee.net/edgemicro-auth/jwkPublicKeys'
-
Mulai ulang Edge Microgateway seperti yang Anda lakukan sebelumnya, menggunakan nama org/env yang Anda gunakan di nama file konfigurasi. Contoh:
edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
-
Dapatkan token JWT dari endpoint otorisasi. Karena menggunakan endpoint
edgemicro-auth/jwkPublicKeys
, Anda dapat menggunakan perintah CLI ini:
Anda dapat membuat JWT untuk Edge Microgateway menggunakan perintah edgemicro token
atau API. Contoh:
edgemicro token get -o your_org -e your_env \ -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy
Dengan keterangan:
- your_org adalah nama organisasi Apigee tempat Anda sebelumnya mengonfigurasi Edge Microgateway.
- your_env adalah lingkungan dalam organisasi.
- Opsi
i
menentukan Kunci Konsumen dari aplikasi developer yang memiliki produk yang menyertakan proxyedgemicro-auth
. - Opsi
s
menentukan Rahasia Konsumen dari aplikasi developer yang memiliki produk yang menyertakan proxyedgemicro-auth
.
Perintah ini meminta Apigee Edge untuk menghasilkan JWT yang kemudian dapat digunakan untuk memverifikasi panggilan API.
Lihat juga Membuat token.Menguji konfigurasi mandiri
Untuk menguji konfigurasi, panggil API dengan token yang ditambahkan di header Authorization sebagai berikut:
curl http://localhost:8000/echo -H "Authorization: Bearer your_token
Contoh:
curl http://localhost:8000/echo -H "Authorization: Bearer eyJraWQiOiIxIiwidHlwIjo...iryF3kwcDWNv7OQ"
Contoh output:
{ "headers":{ "user-agent":"curl/7.54.0", "accept":"*/*", "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP", "client_received_start_timestamp":"1535134472699", "x-authorization-claims":"eyJhdDbiO...M1OTE5MTA1NDkifQ==", "target_sent_start_timestamp":"1535134472702", "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896", "x-forwarded-proto":"http", "x-forwarded-host":"localhost:8000", "host":"mocktarget.apigee.net", "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513", "via":"1.1 localhost, 1.1 google", "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212", "connection":"Keep-Alive" }, "method":"GET", "url":"/", "body":"" }
Menggunakan mode proxy lokal
Dalam mode proxy lokal, Edge Microgateway tidak memerlukan proxy microgateway untuk di-deploy di Apigee Edge. Sebagai gantinya, Anda akan mengonfigurasi "proxy lokal" dengan memberikan nama proxy lokal, jalur dasar, dan URL target saat memulai microgateway. Panggilan API ke microgateway kemudian dikirim ke URL target proxy lokal. Selain itu, mode proxy lokal berfungsi sama persis seperti menjalankan Edge Microgateway dalam mode normalnya. Cara kerja autentikasi sama, seperti penangkapan lonjakan dan penerapan kuota, plugin kustom, dan sebagainya.
Kasus penggunaan dan contoh
Mode proxy lokal berguna saat Anda hanya perlu mengaitkan satu proxy tunggal dengan instance Edge Microgateway. Misalnya, Anda dapat memasukkan Edge Microgateway ke dalam Kubernetes sebagai proxy file bantuan, dengan microgateway dan layanan masing-masing berjalan dalam satu pod, dan tempat microgateway mengelola traffic ke dan dari layanan pendampingnya. Gambar berikut mengilustrasikan arsitektur ini di mana Edge Microgateway berfungsi sebagai proxy file bantuan di cluster Kubernetes. Setiap instance microgateway hanya berkomunikasi dengan satu endpoint di layanan pendampingnya:
Gaya arsitektur ini bermanfaat karena Edge Microgateway menyediakan pengelolaan API untuk setiap layanan yang di-deploy ke lingkungan container, seperti cluster Kubernetes.
Mengonfigurasi mode proxy lokal
Untuk mengonfigurasi Edge Microgateway agar berjalan dalam mode proxy lokal, ikuti langkah-langkah berikut:
- Pastikan Anda telah menginstal Edge Microgateway versi 3.0.1 atau yang lebih baru. Jika tidak, Anda harus
menjalankan perintah berikut untuk mengupgrade ke versi terbaru:
npm install -g edgemicro
Jika Anda memerlukan bantuan, lihat Menginstal Edge Microgateway.
- Jalankan
edgemicro init
untuk menyiapkan lingkungan konfigurasi lokal Anda, persis seperti yang Anda lakukan dalam penyiapan Edge Microgateway standar. Lihat juga Mengonfigurasi Edge Microgateway. - Jalankan
edgemicro configure
, seperti yang Anda lakukan dalam prosedur penyiapan Edge Microgateway standar. Contoh:edgemicro configure -o your_org -e your_env -u your_apigee_username
Perintah ini men-deploy kebijakan edgemicro-auth ke Edge dan menampilkan kunci dan rahasia yang Anda perlukan untuk memulai microgateway. Jika Anda memerlukan bantuan, lihat Mengonfigurasi Edge Microgateway.
- Di Apigee Edge, buat produk API dan dengan persyaratan konfigurasi wajib berikut (Anda dapat mengelola semua konfigurasi lainnya sesuai keinginan):
- Anda harus menambahkan proxy edgemicro-auth ke produk. Proxy ini di-deploy secara otomatis saat Anda menjalankan
edgemicro configure
. - Anda harus memberikan jalur resource. Apigee merekomendasikan penambahan jalur ini ke produk:
/**
. Untuk mempelajari lebih lanjut, lihat Mengonfigurasi perilaku jalur resource. Lihat juga Membuat produk API dalam dokumentasi Edge.
- Anda harus menambahkan proxy edgemicro-auth ke produk. Proxy ini di-deploy secara otomatis saat Anda menjalankan
Di Apigee Edge, buat developer, atau Anda dapat menggunakan developer yang sudah ada jika ingin. Untuk mendapatkan bantuan, lihat Menambahkan developer menggunakan UI pengelolaan Edge.
- Di Apigee Edge, buat aplikasi developer. Anda harus menambahkan produk API yang baru saja dibuat ke aplikasi. Untuk mendapatkan bantuan, lihat Mendaftarkan aplikasi di UI pengelolaan Edge.
- Pada mesin yang menginstal Edge Microgateway, ekspor variabel lingkungan
berikut dengan nilai "1".
export EDGEMICRO_LOCAL_PROXY=1
- Jalankan perintah
start
berikut:edgemicro start -o your_org -e your_environment -k your_key -s your_secret \ -a local_proxy_name -v local_proxy_version -t target_url -b base_path
Dengan keterangan:
- your_org adalah organisasi Apigee Anda.
- your_environment adalah lingkungan di organisasi Anda.
- your_key adalah kunci yang ditampilkan saat Anda menjalankan
edgemicro configure
. - your_secret adalah rahasia yang ditampilkan saat Anda menjalankan
edgemicro configure
. - local_proxy_name adalah nama proxy lokal yang akan dibuat.
- local_proxy_version adalah nomor versi proxy.
- target_url adalah URL untuk target proxy (layanan yang akan dipanggil oleh proxy).
- base_path adalah jalur dasar proxy. Nilai ini harus diawali dengan garis miring. Untuk jalur dasar root, hanya tentukan garis miring; misalnya, "/".
Contoh:
edgemicro start -o your_org -e test -k 7eb6aae644cbc09035a...d2eae46a6c095f \ -s e16e7b1f5d5e24df...ec29d409a2df853163a -a proxy1 -v 1 \ -t http://mocktarget.apigee.net -b /echo
Menguji konfigurasi
Anda dapat menguji konfigurasi proxy lokal dengan memanggil endpoint proxy. Misalnya,
jika Anda menentukan jalur dasar /echo
, Anda dapat memanggil proxy seperti berikut:
curl http://localhost:8000/echo { "error" : "missing_authorization", "error_description" : "Missing Authorization header" }
Panggilan API awal ini menghasilkan error karena Anda tidak memberikan kunci API yang valid. Anda dapat menemukan kunci di aplikasi Developer yang Anda buat sebelumnya. Buka aplikasi di UI Edge, salin Kunci Konsumen, lalu gunakan kunci tersebut sebagai berikut:
curl http://localhost:8000/echo -H 'x-api-key:your_api_key'
Contoh:
curl http://localhost:8000/echo -H "x-api-key:DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP"
Contoh output:
{ "headers":{ "user-agent":"curl/7.54.0", "accept":"*/*", "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP", "client_received_start_timestamp":"1535134472699", "x-authorization-claims":"eyJhdWQiOi...TQ0YmUtOWNlOS05YzM1OTE5MTA1NDkifQ==", "target_sent_start_timestamp":"1535134472702", "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896", "x-forwarded-proto":"http", "x-forwarded-host":"localhost:8000", "host":"mocktarget.apigee.net", "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513", "via":"1.1 localhost, 1.1 google", "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212", "connection":"Keep-Alive" }, "method":"GET", "url":"/", "body":"" }