Anda sedang melihat dokumentasi Apigee Edge.
Lihat dokumentasi Apigee X.
Yang akan Anda pelajari
- Mendownload dan men-deploy contoh proxy API.
- Membuat proxy API yang dilindungi OAuth.
- Buat produk, developer, dan aplikasi.
- Kredensial Exchange 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 untuk memberikan nama pengguna dan sandi mereka.
Dengan OAuth, kredensial keamanan (seperti nama pengguna/sandi atau kunci/rahasia) ditukar dengan token akses. Contoh:
joe:joes_password
(username:password) atau
Nf2moHOASMJeUmXVdDhlMbPaXm2U7eMc:unUOXYpPe74ZfLEb
(key:secret)
menjadi seperti ini:
b0uiYwjRZLEo4lEu7ky2GGxHkanN
Token akses adalah string karakter acak dan bersifat sementara (harus berakhir setelah waktu yang relatif singkat). Jadi, meneruskan token untuk mengautentikasi pengguna dalam alur kerja aplikasi jauh lebih aman daripada meneruskan kredensial yang sebenarnya.
Spesifikasi OAuth 2.0 menentukan mekanisme yang berbeda, yang disebut "jenis pemberian", untuk mendistribusikan token akses untuk aplikasi. Jenis hibah paling dasar yang ditentukan oleh OAuth 2.0 disebut "kredensial klien". Dalam jenis hibah ini, token akses OAuth dibuat untuk ditukar dengan kredensial klien, yang merupakan pasangan kunci konsumen/rahasia konsumen, seperti contoh di atas.
Jenis pemberian kredensial klien di Edge diterapkan menggunakan kebijakan dalam proxy API. Alur OAuth standar mencakup dua langkah:
- Memanggil proxy API 1 untuk membuat token akses OAuth dari kredensial klien. Kebijakan OAuth v2.0 pada 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 Anda butuhkan
- Akun Apigee Edge. Jika belum memilikinya, Anda dapat mendaftar dengan rute di Membuat akun Apigee Edge.
- cURL yang diinstal di komputer Anda untuk melakukan panggilan API dari command line.
Mendownload dan men-deploy proxy API yang menghasilkan 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 memberikan contoh proxy API yang melakukan hal ini. Anda akan mendownload dan men-deploy proxy sekarang, lalu menggunakannya nanti dalam tutorial. (Anda dapat mem-build proxy API ini dengan mudah sendiri. Langkah download dan deploy ini ditujukan untuk memudahkan dan untuk menunjukkan betapa mudahnya membagikan proxy yang telah dibuat.)
- Download file ZIP contoh 'oauth' ke direktori mana pun di sistem file Anda.
- Buka https://apigee.com/edge, lalu login.
- Pilih Develop > API Proxies di menu navigasi sebelah kiri.
- Klik + Proxy.
- Di wizard Buat Proxy, klik Upload paket proxy.
- Pilih file
oauth.zip
yang telah Anda download, lalu klik Next. - Klik Create.
- Setelah proses build selesai, klik Edit proxy untuk melihat proxy baru di editor proxy API.
- Di halaman Ringkasan Proxy API, klik drop-down Deployment lalu pilih test. Ini adalah lingkungan pengujian di organisasi Anda.
Pada perintah konfirmasi, klik Deploy.
Saat Anda mengklik drop-down Deployment lagi, ikon hijau menunjukkan bahwa proxy di-deploy ke lingkungan pengujian.
Selamat! Anda berhasil mendownload dan men-deploy proxy API akses token yang dihasilkan ke organisasi Edge Anda.
Melihat alur dan kebijakan OAuth
Mari kita pelajari lebih lanjut apa yang terdapat dalam proxy API.
- Di editor proxy API, klik tab Develop. Di panel
Navigator, 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>
Flow adalah langkah pemrosesan dalam proxy API. Dalam hal ini, alur dipicu saat suatu kondisi terpenuhi (disebut alur bersyarat). Kondisi, yang ditentukan dalam elemen
<Condition>
, menunjukkan bahwa jika panggilan proxy API dilakukan ke resource/accesstoken
, dan kata kerja permintaan adalahPOST
, maka jalankan kebijakanGenerateAccessTokenClient
, yang menghasilkan token akses. -
Sekarang, mari kita lihat kebijakan yang akan dipicu oleh alur kondisional. Klik ikon kebijakan GenerateAccessTokenClient dalam 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 tersebut mencakup hal berikut:
<Operation>
, yang dapat menjadi salah satu dari beberapa nilai yang telah ditetapkan, menentukan tindakan yang akan dilakukan oleh kebijakan. Dalam hal ini, akan menghasilkan token akses.- Masa berlaku token adalah 1 jam (3600000 milidetik) setelah dibuat.
- Di
<SupportedGrantTypes>
,<GrantType>
OAuth yang diharapkan akan digunakan adalahclient_credentials
(menukar kunci dan rahasia konsumen dengan token OAuth). - Elemen
<GrantType>
kedua memberi tahu kebijakan tentang ke mana harus mencari di panggilan API untuk parameter jenis hibah, seperti yang diwajibkan oleh spesifikasi OAuth 2.0. (Anda akan melihatnya dalam panggilan API nanti). Jenis hibah 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. Namun pertama-tama, Anda perlu melakukan beberapa hal lagi:
- Buat proxy API yang sebenarnya ingin Anda amankan dengan OAuth.
- Buat beberapa artefak lain yang akan menghasilkan kunci konsumen dan rahasia konsumen yang harus 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 mocktarget Apigee untuk menampilkan alamat IP Anda. NAMUN, 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 ke:
/hellooauth2
Jalur Project Base adalah bagian dari URL yang digunakan untuk membuat permintaan ke proxy API.
API yang ada Masukkan:
https://mocktarget.apigee.net/ip
Kolom ini menentukan URL target yang dipanggil Apigee Edge pada permintaan ke proxy API.
Deskripsi Masukkan: hello world protected by OAuth
- Klik Berikutnya.
- Di halaman Kebijakan umum:
Di kolom ini lakukan ini Keamanan: Otorisasi Pilih: OAuth 2.0 - Klik Berikutnya.
- Di halaman Virtual Hosts, klik Next.
- Di halaman Build, pastikan lingkungan test dipilih, lalu klik Create and Deploy.
- Di halaman Summary, Anda 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 "test".
Lihat kebijakannya
Mari kita pelajari lebih lanjut apa yang telah Anda buat.
- Di editor proxy API, klik tab Develop. Anda akan melihat 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.
- Menghapus Otorisasi Header – Kebijakan ConfigureMessage 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 pada tampilan alur, lalu lihat XML di bawahnya dalam 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.
Tambahkan produk API
Untuk menambahkan produk API menggunakan UI Apigee:
- Pilih Publikasikan > Produk API.
- Klik +Produk API.
- Masukkan Detail produk untuk produk API Anda.
Kolom Deskripsi Nama Nama internal produk API. Jangan menentukan karakter khusus dalam nama.
Catatan: Anda tidak dapat mengedit nama setelah produk API dibuat. Misalnya,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 Nama akan digunakan. Kolom ini diisi otomatis menggunakan nilai Nama; Anda dapat mengedit atau menghapus isinya. Nama tampilan dapat menyertakan karakter khusus. Misalnya, helloworld_oauth2-Product
.Deskripsi Deskripsi produk API. Lingkungan Lingkungan tempat produk API akan mengizinkan akses. Pilih lingkungan tempat Anda men-deploy proxy API. Misalnya, test
.Akses Pilih Publik. Setujui permintaan akses secara otomatis Aktifkan persetujuan otomatis untuk permintaan utama produk API ini dari aplikasi apa pun. Kuota Abaikan untuk tutorial ini. Cakupan OAuth yang Diizinkan Abaikan untuk tutorial ini. - Di kolom Proxy API, pilih proxy API yang baru saja Anda buat.
- Di kolom Path, masukkan "/". Abaikan kolom lainnya.
- Klik Simpan.
Tambahkan developer dan aplikasi ke organisasi Anda
Berikutnya, Anda akan menyimulasikan alur kerja developer yang mendaftar untuk menggunakan API Anda. Idealnya, developer mendaftarkan diri 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 dan 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 pada traffic API, karena Edge mengetahui developer dan aplikasi mana yang termasuk dalam token OAuth yang mana.
Membuat developer
Mari kita buat developer bernama Nigel Tufnel.
- Pilih Publikasikan > Developer di menu.
- Klik + Developer.
- Masukkan kode berikut di jendela New Developer:
Di kolom ini Enter Nama Depan Nigel
Nama Belakang Tufnel
Username nigel
Email nigel@example.com
- Klik Create.
Mendaftarkan aplikasi
Mari kita buat aplikasi untuk Nigel.
- Pilih Publikasikan > Aplikasi.
- Klik + Aplikasi.
- Masukkan informasi berikut di jendela New App:
Di kolom ini lakukan ini Nama dan Nama Tampilan Masukkan: nigel_app
Developer Klik Developer, lalu pilih: Nigel Tufnel (nigel@example.com)
URL callback dan Catatan Biarkan kosong - Di bagian Produk, klik Tambahkan Produk.
- Pilih helloworld_oauth2-Product.
- Klik Create.
Dapatkan kunci konsumen 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, pada halaman Apps (Publikasikan > Aplikasi), klik nigel_app.
-
Di halaman nigel_app, klik Show pada kolom Key dan Secret. Perhatikan bahwa kunci/rahasia ini telah dikaitkan dengan "helloworld_oauth2-Product" yang dibuat secara otomatis sebelumnya.
- Pilih dan salin Kunci dan Rahasia. Tempelkan di file teks sementara. Anda akan menggunakannya pada langkah berikutnya, yaitu saat Anda memanggil proxy API yang akan menukar kredensial ini dengan token akses OAuth.
Coba panggil API untuk mendapatkan alamat IP Anda (gagal!)
Untuk memudahkan, coba panggil proxy API yang dilindungi yang akan menampilkan alamat IP Anda. Jalankan perintah cURL berikut di jendela terminal, yang menggantikan nama organisasi
Edge Anda. Kata test
di URL adalah
lingkungan pengujian organisasi Anda, yang digunakan untuk men-deploy proxy Anda. Basebase proxy adalah /hellooauth2
, jalur dasar yang sama dengan yang Anda tetapkan 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 Verifikasi Token Akses OAuth v2.0 yang memeriksa token OAuth yang valid dalam permintaan, panggilan harus gagal dengan pesan berikut:
{"fault":{"faultstring":"Invalid access token","detail":{"errorcode":"oauth.v2.InvalidAccessToken"}}}
Dalam hal ini, kegagalan itu baik. Ini berarti proxy API Anda jauh lebih aman. Hanya aplikasi tepercaya dengan token akses OAuth yang valid yang dapat memanggil API ini dengan sukses.
Mendapatkan token akses OAuth
Sekarang mari kita dapatkan 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 Anda, kunci Anda, dan
secret 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 Isi permintaan
dan harus 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 mendapatkan token akses OAuth. Salin nilai access_token (tanpa tanda kutip) dan tempel ke file teks Anda. Anda akan segera menggunakannya.
Apa yang baru saja terjadi?
Ingat sebelumnya saat Anda melihat alur bersyarat di proxy
oauth, 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 kondisi tersebut, sehingga kebijakan OAuth dieksekusi. Kunci ini memverifikasi kunci konsumen dan rahasia konsumen Anda, dan menukarnya dengan token OAuth yang masa berlakunya berakhir dalam 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 Anda dan token akses.
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 selama 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)