Anda sedang melihat dokumentasi Apigee Edge.
Buka
dokumentasi Apigee X. info
Yang akan Anda pelajari
- Mendownload dan men-deploy contoh proxy API.
- Buat proxy API yang dilindungi OAuth.
- Buat produk, developer, dan aplikasi.
- Menukarkan kredensial dengan token akses OAuth.
- Memanggil API dengan token akses.
Tutorial ini menunjukkan cara mengamankan API dengan OAuth 2.0.
OAuth adalah protokol otorisasi yang memungkinkan aplikasi mengakses informasi atas nama pengguna tanpa mengharuskan pengguna memberitahukan nama pengguna dan sandi mereka.
Dengan OAuth, kredensial keamanan (seperti nama pengguna/sandi atau kunci/rahasia) akan ditukarkan dengan token akses. Contoh:
joe:joes_password
(username:password) atau
Nf2moHOASMJeUmXVdDhlMbPaXm2U7eMc:unUOXYpPe74ZfLEb
(kunci:rahasia)
menjadi:
b0uiYwjRZLEo4lEu7ky2GGxHkanN
Token akses adalah string karakter acak dan bersifat sementara (masa berlaku token akan berakhir setelah waktu yang relatif singkat), jadi meneruskannya untuk mengautentikasi pengguna dalam alur kerja aplikasi jauh lebih aman daripada meneruskan kredensial yang sebenarnya.
Spesifikasi OAuth 2.0 menentukan berbagai mekanisme, yang disebut "jenis pemberian", untuk mendistribusikan token akses untuk aplikasi. Jenis pemberian paling dasar yang ditetapkan oleh OAuth 2.0 disebut "kredensial klien". Dalam jenis pemberian ini, token akses OAuth dibuat sebagai imbalan atas kredensial klien, yang merupakan pasangan kunci/rahasia konsumen, seperti contoh di atas.
Jenis pemberian kredensial klien di Edge diimplementasikan menggunakan kebijakan dalam proxy API. Alur OAuth umum meliputi dua langkah:
- Call API proxy 1 untuk membuat token akses OAuth dari kredensial klien. Kebijakan OAuth v2.0 di proxy API akan menangani hal ini.
- Memanggil proxy API 2 untuk mengirim token akses OAuth dalam panggilan API. Proxy API memverifikasi token akses menggunakan kebijakan OAuth v2.0.
Yang akan Anda butuhkan
- Akun Apigee Edge. Jika belum memilikinya, Anda dapat mendaftar dengan mengikuti petunjuk di Membuat akun Apigee Edge.
- cURL yang diinstal di komputer Anda untuk melakukan panggilan API dari command line.
Mendownload dan men-deploy proxy API pembuat token
Pada langkah ini, Anda akan membuat proxy API yang menghasilkan token akses OAuth dari kunci konsumen dan rahasia konsumen yang dikirim dalam panggilan API. Apigee menyediakan contoh proxy API yang melakukannya. Anda akan mendownload dan men-deploy proxy sekarang, lalu menggunakannya nanti dalam tutorial. (Anda dapat membangun proxy API ini dengan mudah sendiri. Langkah download dan deploy ini demi kenyamanan dan untuk menunjukkan betapa mudahnya berbagi proxy yang telah dibuat.)
- Download file ZIP proxy API contoh 'oauth' ke direktori mana pun di sistem file Anda.
- Buka https://apigee.com/edge dan login.
- Pilih Develop > API Proxies di menu navigasi sebelah kiri.
- Klik + Proxy.
- Di wizard Create Proxy, klik Upload paket proxy.
- Pilih file
oauth.zip
yang Anda download, lalu klik Next. - Klik Create.
- Setelah build selesai, klik Edit proxy untuk melihat proxy baru di editor proxy API.
- Di halaman Ringkasan API Proxy Editor, klik drop-down Deployment
lalu pilih test. Ini adalah lingkungan pengujian di organisasi Anda.
Pada perintah konfirmasi, klik Deploy.
Jika Anda mengklik kembali drop-down Deployment, ikon hijau menunjukkan bahwa proxy telah di-deploy ke lingkungan pengujian.
Selamat! Anda telah berhasil mendownload dan men-deploy proxy API pembuatan token akses ke organisasi Edge Anda.
Melihat alur dan kebijakan OAuth
Mari kita pelajari lebih lanjut apa saja yang terdapat dalam proxy API.
- Di editor proxy API, klik tab Develop. Di panel Navigator kiri, Anda akan melihat dua kebijakan. Anda juga akan melihat dua alur
POST
di bagianProxy Endpoints
. -
Klik AccessTokenClientCredential di bagian
Proxy Endpoints
.
Dalam tampilan kode XML, Anda akan melihat
Flow
bernamaAccessTokenClientCredential
:<Flow name="AccessTokenClientCredential"> <Description/> <Request> <Step> <Name>GenerateAccessTokenClient</Name> </Step> </Request> <Response/> <Condition>(proxy.pathsuffix MatchesPath "/accesstoken") and (request.verb = "POST")</Condition> </Flow>
Alur adalah langkah pemrosesan di proxy API. Dalam hal ini, alur dipicu saat kondisi tertentu terpenuhi (disebut alur bersyarat). Kondisi yang ditentukan dalam elemen
<Condition>
ini menyatakan bahwa jika panggilan proxy API dilakukan ke resource/accesstoken
, dan verb permintaan adalahPOST
, maka jalankan kebijakanGenerateAccessTokenClient
, yang menghasilkan token akses. -
Sekarang, mari kita lihat kebijakan yang akan dipicu oleh alur bersyarat. Klik ikon kebijakan GenerateAccessTokenClient pada diagram alur.
Konfigurasi XML berikut dimuat ke dalam tampilan kode:<OAuthV2 name="GenerateAccessTokenClient"> <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type --> <Operation>GenerateAccessToken</Operation> <!-- This is in millseconds, so expire in an hour --> <ExpiresIn>3600000</ExpiresIn> <SupportedGrantTypes> <!-- This part is very important: most real OAuth 2.0 apps will want to use other grant types. In this case it is important to NOT include the "client_credentials" type because it allows a client to get access to a token with no user authentication --> <GrantType>client_credentials</GrantType> </SupportedGrantTypes> <GrantType>request.queryparam.grant_type</GrantType> <GenerateResponse/> </OAuthV2>
Konfigurasi ini mencakup:
<Operation>
, yang dapat berupa salah satu dari beberapa nilai yang telah ditentukan, menentukan apa yang akan dilakukan kebijakan. Dalam hal ini, kebijakan akan membuat token akses.- Masa berlaku token akan berakhir dalam 1 jam (3600000 milidetik) setelah dibuat.
- Di
<SupportedGrantTypes>
, OAuth<GrantType>
yang diharapkan akan digunakan adalahclient_credentials
(bertukar kunci dan rahasia konsumen untuk token OAuth). - Elemen
<GrantType>
kedua memberi tahu kebijakan tempat untuk melihat panggilan API untuk parameter jenis pemberian, seperti yang diwajibkan oleh spesifikasi OAuth 2.0. (Anda akan melihatnya di panggilan API nanti). Jenis pemberian juga dapat dikirim di header HTTP (request.header.grant_type
) atau sebagai parameter formulir (request.formparam.grant_type
).
Anda tidak perlu melakukan apa pun dengan proxy API saat ini. Pada langkah selanjutnya, Anda akan menggunakan proxy API ini untuk membuat token akses OAuth. Tapi pertama-tama, Anda perlu melakukan beberapa hal lagi:
- Buat proxy API yang benar-benar ingin Anda amankan dengan OAuth.
- Buat beberapa artefak lain yang akan menghasilkan kunci dan rahasia konsumen yang akan Anda tukarkan dengan token akses.
Membuat proxy API yang dilindungi OAuth
Sekarang Anda akan membuat proxy API yang ingin dilindungi. Ini adalah panggilan API yang menampilkan sesuatu yang Anda inginkan. Dalam hal ini, proxy API akan memanggil layanan tiruan Apigee untuk menampilkan alamat IP Anda. TETAPI, Anda hanya akan melihatnya jika meneruskan token akses OAuth yang valid dengan panggilan API.
Proxy API yang Anda buat di sini akan menyertakan kebijakan yang memeriksa token OAuth dalam permintaan.
- Pilih Develop > API Proxies di menu navigasi sebelah kiri.
- Klik + Proxy.
- Di wizard Build a Proxy, pilih Reverse proxy (paling umum), lalu klik Next.
- Konfigurasikan proxy dengan hal berikut:
Di kolom ini lakukan ini Nama Proxy Masukkan: helloworld_oauth2
Jalur Dasar Project Ubah menjadi:
/hellooauth2
Jalur Dasar Project adalah bagian dari URL yang digunakan untuk membuat permintaan ke proxy API.
API yang sudah ada Masukkan:
https://mocktarget.apigee.net/ip
Atribut ini menentukan URL target yang dipanggil Apigee Edge pada permintaan ke proxy API.
Deskripsi Masukkan: hello world protected by OAuth
- Klik Next.
- Di halaman Kebijakan umum:
Di kolom ini lakukan ini Keamanan: Otorisasi Pilih: OAuth 2.0 - Klik Next.
- Di halaman Virtual Hosts, klik Next.
- Pada halaman Build, pastikan lingkungan test dipilih, lalu klik Create and Deploy.
- Di halaman Summary, Anda akan melihat konfirmasi bahwa proxy API baru berhasil dibuat dan proxy API telah di-deploy ke lingkungan pengujian.
- Klik Edit proxy untuk menampilkan halaman Overview untuk proxy API.
Perhatikan bahwa kali ini proxy API otomatis di-deploy. Klik drop-down Deployment untuk memastikan ada titik deployment hijau di samping lingkungan "pengujian".
Lihat kebijakan
Mari kita lihat lebih dekat apa yang telah Anda buat.
- Di editor proxy API, klik tab Develop. Anda akan melihat bahwa dua kebijakan telah ditambahkan ke alur permintaan proxy API:
- Verifikasi Token Akses OAuth v2.0 – Memeriksa panggilan API untuk memastikan ada token OAuth yang valid.
- Remove Header Authorization – Kebijakan TetapkanMessage yang menghapus token akses setelah diperiksa, sehingga tidak diteruskan ke layanan target. (Jika layanan target memerlukan token akses OAuth, Anda tidak akan menggunakan kebijakan ini).
-
Klik ikon Verify OAuth v2.0 Access Token dalam tampilan alur, lalu lihat XML di bawahnya di panel kode.
<OAuthV2 async="false" continueOnError="false" enabled="true" name="verify-oauth-v2-access-token"> <DisplayName>Verify OAuth v2.0 Access Token</DisplayName> <Operation>VerifyAccessToken</Operation> </OAuthV2>
Perhatikan bahwa
<Operation>
adalahVerifyAccessToken
. Operasi menentukan apa yang seharusnya dilakukan kebijakan. Dalam hal ini, operasi akan memeriksa token OAuth yang valid dalam permintaan.
Menambahkan produk API
Untuk menambahkan produk API menggunakan UI Apigee:
- Pilih Publish > API Products.
- Klik +produk API.
- Masukkan Detail produk untuk produk API Anda.
Kolom Deskripsi Nama Nama internal produk API. Jangan cantumkan karakter khusus dalam nama.
Catatan: Anda tidak dapat mengedit nama setelah produk API dibuat. Contoh,helloworld_oauth2-Product
Nama tampilan Nama tampilan untuk produk API. Nama tampilan digunakan di UI dan Anda dapat mengeditnya kapan saja. Jika tidak ditentukan, nilai Name akan digunakan. Kolom ini diisi secara otomatis menggunakan nilai Name; Anda dapat mengedit atau menghapus kontennya. Nama tampilan dapat berisi karakter khusus. Misalnya, helloworld_oauth2-Product
.Deskripsi Deskripsi produk API. Environment Lingkungan yang akan diizinkan oleh produk API. Pilih lingkungan tempat Anda men-deploy proxy API. Misalnya, test
.Akses Pilih Publik. Menyetujui permintaan akses secara otomatis Aktifkan persetujuan otomatis permintaan kunci untuk produk API ini dari aplikasi apa pun. Kuota Abaikan tutorial ini. Cakupan OAuth yang Diizinkan Abaikan tutorial ini. - Di kolom API proxy, pilih proxy API yang baru saja dibuat.
- Di kolom Jalur, masukkan "/". Abaikan kolom lainnya.
- Klik Simpan.
Tambahkan developer dan aplikasi ke organisasi Anda
Selanjutnya, Anda akan menyimulasikan alur kerja developer yang mendaftar untuk menggunakan API Anda. Idealnya, developer mendaftarkan diri mereka sendiri dan aplikasinya melalui portal developer Anda. Namun, pada langkah ini, Anda akan menambahkan developer dan aplikasi sebagai administrator.
Developer akan memiliki satu atau beberapa aplikasi yang memanggil API Anda, dan setiap aplikasi mendapatkan kunci konsumen serta rahasia konsumen yang unik. Kunci/rahasia per aplikasi ini juga memberi Anda, penyedia API, kontrol yang lebih terperinci atas akses ke API dan pelaporan analisis yang lebih terperinci tentang traffic API, karena Edge mengetahui developer dan aplikasi mana yang termasuk dalam token OAuth.
Membuat developer
Mari kita buat developer bernama Nigel Tufnel.
- Pilih Publikasikan > Developer di menu.
- Klik + Developer.
- Masukkan kode berikut di jendela Developer Baru:
Di kolom ini Enter Nama Depan Nigel
Nama Belakang Tufnel
Username nigel
Email nigel@example.com
- Klik Create.
Daftarkan aplikasi
Mari kita buat aplikasi untuk Nigel.
- Pilih Publikasikan > Aplikasi.
- Klik + Aplikasi.
- Masukkan kode berikut di jendela New App:
Di kolom ini lakukan ini Name dan Display Name Masukkan: nigel_app
Developer Klik Developer dan pilih: Nigel Tufnel (nigel@example.com)
URL Panggilan Balik dan Catatan Biarkan kosong - Di bagian Produk, klik Tambahkan Produk.
- Pilih helloworld_oauth2-Product.
- Klik Create.
Mendapatkan kunci dan rahasia konsumen
Sekarang Anda akan mendapatkan kunci konsumen dan rahasia konsumen yang akan ditukarkan dengan token akses OAuth.
- Pastikan halaman nigel_app ditampilkan. Jika tidak, di halaman Aplikasi (Publish > Apps), klik nigel_app.
-
Pada halaman nigel_app, klik Show di kolom Key dan Secret. Perhatikan bahwa kunci/rahasia ini terkait dengan "helloworld_oauth2-Product" yang otomatis dibuat sebelumnya.
- Pilih dan salin Kunci dan Rahasia. Tempel semuanya dalam file teks sementara. Anda akan menggunakannya di langkah selanjutnya, ketika Anda memanggil proxy API yang akan menukar kredensial ini dengan token akses OAuth.
Coba panggil API untuk mendapatkan alamat IP Anda (gagal!)
Sebagai permulaan, coba panggil proxy API yang dilindungi yang seharusnya menampilkan alamat IP
Anda. Jalankan perintah cURL berikut di jendela terminal, dengan mengganti nama organisasi
Edge Anda. Kata test
di URL adalah lingkungan pengujian organisasi Anda, tempat Anda men-deploy proxy. Basepath proxy adalah /hellooauth2
, basepath yang sama dengan yang Anda tentukan saat membuat proxy.
Perhatikan bahwa Anda tidak meneruskan token akses OAuth dalam panggilan.
curl https://ORG_NAME-test.apigee.net/hellooauth2
Karena proxy API memiliki kebijakan Verify OAuth v2.0 Access Token yang memeriksa token OAuth yang valid dalam permintaan, panggilan akan gagal dengan pesan berikut:
{"fault":{"faultstring":"Invalid access token","detail":{"errorcode":"oauth.v2.InvalidAccessToken"}}}
Dalam hal ini, kegagalan adalah hal yang baik! Artinya proxy API Anda jauh lebih aman. Hanya aplikasi tepercaya dengan token akses OAuth valid yang dapat memanggil API ini.
Mendapatkan token akses OAuth
Sekarang kita mendapatkan hasil yang besar. Anda akan menggunakan kunci dan rahasia yang Anda salin dan tempel ke dalam file teks dan menukarnya dengan token akses OAuth. Sekarang Anda akan melakukan panggilan API ke proxy contoh API yang Anda impor, oauth, yang akan menghasilkan token akses API.
Dengan menggunakan kunci dan rahasia tersebut, lakukan panggilan cURL berikut (perhatikan bahwa protokolnya adalah
https
), dengan mengganti nama organisasi Edge, kunci, dan
rahasia Anda jika ditunjukkan:
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \ "https://ORG_NAME-test.apigee.net/oauth/client_credential/accesstoken?grant_type=client_credentials" \ -d "client_id=CLIENT_KEY&client_secret=CLIENT_SECRET"
Perhatikan bahwa jika Anda menggunakan klien seperti Postman untuk melakukan panggilan, client_id
dan client_secret
akan masuk ke dalam Isi permintaan dan harus berupa x-www-form-urlencoded
.
Anda akan mendapatkan respons seperti ini:
{ "issued_at" : "1466025769306", "application_name" : "716bbe61-f14a-4d85-9b56-a62ff8e0d347", "scope" : "", "status" : "approved", "api_product_list" : "[helloworld_oauth2-Product]", "expires_in" : "3599", //--in seconds "developer.email" : "nigel@example.com", "token_type" : "BearerToken", "client_id" : "xNnREu1DNGfiwzQZ5HUN8IAUwZSW1GZW", "access_token" : "GTPY9VUHCqKVMRB0cHxnmAp0RXc0", "organization_name" : "myOrg", "refresh_token_expires_in" : "0", //--in seconds "refresh_count" : "0" }
Anda telah mendapatkan token akses OAuth. Salin nilai access_token (tanpa tanda kutip) dan tempelkan ke file teks Anda. Anda akan segera menggunakannya.
Apa yang baru saja terjadi?
Ingat sebelumnya, saat Anda melihat alur kondisional di proxy oauth, aliran yang menyatakan jika URI resource adalah /accesstoken
dan kata kerja permintaan adalah POST
, untuk menjalankan kebijakan OAuth GenerateAccessTokenClient
yang menghasilkan token akses? Perintah cURL Anda
memenuhi ketentuan tersebut, sehingga kebijakan OAuth dieksekusi. Proses ini memverifikasi kunci konsumen dan rahasia konsumen Anda, lalu menukarnya dengan token OAuth yang masa berlakunya akan habis dalam waktu 1 jam.
Memanggil API dengan token akses (berhasil)
Setelah memiliki token akses, Anda dapat menggunakannya untuk memanggil proxy API. Lakukan panggilan cURL berikut. Ganti nama organisasi Edge dan token akses Anda.
curl https://ORG_NAME-test.apigee.net/hellooauth2 -H "Authorization: Bearer TOKEN"
Sekarang Anda akan mendapatkan panggilan yang berhasil ke proxy API yang menampilkan alamat IP Anda. Contoh:
{"ip":"::ffff:192.168.14.136"}
Anda dapat mengulangi panggilan API tersebut hampir satu jam, setelah itu masa berlaku token akses akan berakhir. Untuk melakukan panggilan setelah satu jam, Anda harus membuat token akses baru menggunakan langkah-langkah sebelumnya.
Selamat! Anda telah membuat proxy API dan melindunginya dengan mewajibkan token akses OAuth yang valid disertakan dalam panggilan.
Topik terkait
- Beranda OAuth
- Kebijakan OAuthV2
- Download proxy API (yang menunjukkan cara memaketkan proxy API ke dalam file ZIP seperti yang Anda download)