Halaman ini berlaku untuk Apigee dan Apigee Hybrid.
Lihat dokumentasi
Apigee Edge.
Tutorial ini menunjukkan cara mengamankan proxy API menggunakan token akses OAuth 2.0.
Sebelum memulai
Untuk menyelesaikan tutorial ini, Anda harus memiliki akses ke organisasi Apigee tempat Anda memiliki izin untuk:
- Membuat dan men-deploy proxy API
- Membuat produk API
- Membuat aplikasi developer
Anda juga harus memiliki nama host grup lingkungan yang dikonfigurasi dengan benar yang dapat Anda gunakan untuk melakukan panggilan proxy API Apigee. Jika Anda tidak yakin nama host grup lingkungan mana yang harus digunakan, hubungi administrator Apigee Anda.
Men-deploy proxy OAuth 2.0
Kami menyediakan proxy API di GitHub yang dikonfigurasi untuk membuat token akses OAuth 2.0. Ikuti langkah-langkah berikut untuk mendownload dan men-deploy proxy API ini ke lingkungan Anda:
Download proxy API contoh oauth
ke direktori di sistem
file Anda.
Apigee di Konsol Cloud
Di konsol Google Cloud , buka halaman Proxy development > API proxies.
- Di panel API Proxies, klik + Create.
- Di panel Create a proxy, di bagian Proxy template, pilih Upload proxy bundle.
- Pilih file oauth.zip yang Anda download, lalu klik Next.
- Klik Berikutnya.
- Deploy (opsional):
- Lingkungan deployment: Opsional. Gunakan kotak centang untuk memilih satu atau beberapa lingkungan tempat proxy Anda akan di-deploy. Jika Anda memilih untuk tidak men-deploy proxy pada saat ini, biarkan kolom Lingkungan deployment kosong. Anda selalu dapat men-deploy proxy nanti.
- Akun Layanan: Opsional. Lampirkan akun layanan ke deployment Anda untuk mengizinkan proxy Anda mengakses layanan Google Cloud , seperti yang ditentukan dalam peran dan izin akun layanan.
- Klik Buat.
Apigee Klasik
- Buka UI Apigee, login, lalu pilih organisasi Apigee Anda.
- Pilih Develop > API Proxies di menu navigasi sebelah kiri.
- Klik Buat Baru.
- Di wizard Create Proxy, pilih Upload proxy bundle.
- Pilih file oauth.zip yang Anda download, lalu klik Next.
- Klik Buat.
- Setelah build selesai, klik Edit proxy untuk melihat proxy baru di editor proxy API.
- Klik Deploy.
- Pilih revisi dan lingkungan yang menjadi tujuan deployment. Anda dapat mengosongkan kolom Akun layanan.
- Klik Deploy.
Anda telah berhasil mendownload dan men-deploy proxy API yang menghasilkan token akses ke organisasi Apigee Anda.
Melihat alur dan kebijakan OAuth 2.0
Luangkan waktu beberapa saat untuk memeriksa konfigurasi kebijakan OAuth 2.0.
Konsol Apigee Cloud
Selanjutnya, Anda akan melihat lebih dekat isi proxy API.
- Di editor proxy API, klik tab Develop.
Di panel sebelah kiri, Anda akan melihat dua kebijakan. Anda juga akan melihat dua alur POST di bagian Proxy Endpoints.
- Klik AccessTokenClientCredential di bagian Proxy Endpoints.
Editor teks menampilkan kode XML untuk alur bersyarat
AccessTokenClientCredential:
<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 dalam proxy API. Dalam hal ini, alur dipicu saat kondisi tertentu terpenuhi (disebut "alur bersyarat"). Kondisi, yang ditentukan dalam elemen
<Condition>
, menyatakan 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 bersyarat. Klik kebijakan
GenerateAccessTokenClient di panel Request:
Apigee Klasik
Selanjutnya, Anda akan melihat lebih dekat isi 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 bagian Proxy Endpoints.
-
Klik AccessTokenClientCredential di bagian Proxy Endpoints.
Di tampilan kode XML, Anda akan melihat
Flow
yang disebutAccessTokenClientCredential
:<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 dalam proxy API. Dalam hal ini, alur dipicu saat kondisi tertentu terpenuhi. Kondisi, yang ditentukan dalam elemen
<Condition>
, adalah 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 bersyarat. Klik ikon kebijakan GenerateAccessTokenClient dalam diagram alur.
Konfigurasi XML berikut ditampilkan:
<OAuthV2 name="GenerateAccessTokenClient"> <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type --> <Operation>GenerateAccessToken</Operation> <!-- This is in milliseconds, 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 hal berikut:
<Operation>
, yang dapat berupa salah satu dari beberapa nilai yang telah ditentukan sebelumnya, menentukan tindakan yang akan dilakukan kebijakan. Dalam hal ini, kebijakan akan membuat token akses.- Masa berlaku token akan berakhir 1 jam (3600000 milidetik) setelah dibuat.
- Di
<SupportedGrantTypes>
,<GrantType>
yang diharapkan untuk digunakan adalahclient_credentials
(menukarkan kunci dan rahasia konsumen dengan token OAuth 2.0). - Elemen
<GrantType>
kedua memberi tahu kebijakan tempat untuk mencari parameter jenis pemberian di panggilan API, sebagaimana 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 lagi dengan proxy API saat ini. Pada langkah-langkah selanjutnya, Anda akan menggunakan proxy API ini untuk membuat token akses OAuth 2.0. Namun, Anda harus melakukan beberapa hal lagi:
- Buat proxy API yang sebenarnya ingin Anda amankan dengan OAuth 2.0.
- Buat beberapa artefak lagi yang akan menghasilkan kunci konsumen dan rahasia konsumen yang perlu Anda tukarkan dengan token akses.
Membuat proxy API yang dilindungi
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. TETAPI, Anda hanya akan dapat melihatnya jika meneruskan token akses OAuth 2.0 yang valid dengan panggilan API Anda.
Proxy API yang Anda buat di sini akan menyertakan kebijakan yang memeriksa token OAuth 2.0 dalam permintaan.
Apigee di Konsol Cloud
Di konsol Google Cloud , buka halaman Proxy development > API proxies.
- Di panel API Proxies, klik + Create.
- Di panel Create a proxy, di bagian Proxy template, pilih Reverse proxy (most common).
- Konfigurasi proxy dengan hal berikut:
Di kolom ini lakukan ini Nama Proxy Masukkan: helloworld_oauth2
Jalur Dasar Ubah menjadi:
/hellooauth2
Jalur Dasar Project adalah bagian dari URL yang digunakan untuk membuat permintaan ke proxy API.
Deskripsi Masukkan: hello world protected by OAuth 2.0
Target (API yang Ada) Masukkan:
https://mocktarget.apigee.net/ip
Ini menentukan URL target yang dipanggil Apigee pada permintaan ke proxy API.
- Klik Berikutnya.
- Deploy (opsional):
- Lingkungan deployment: Opsional. Gunakan kotak centang untuk memilih satu atau beberapa lingkungan tempat Anda akan men-deploy proxy. Jika Anda memilih untuk tidak men-deploy proxy pada saat ini, biarkan kolom Lingkungan deployment kosong. Anda dapat men-deploy proxy nanti.
- Akun Layanan: Opsional. Lampirkan akun layanan ke deployment Anda untuk memungkinkan proxy Anda mengakses layanan Google Cloud , seperti yang ditentukan dalam peran dan izin akun layanan.
- Klik Buat.
- Klik tab Develop pada proxy helloworld_oauth2.
- Di menu Kebijakan, Klik Tambahkan kebijakan.
- Di panel Create policy, pilih OAuth 2.0.
- Klik Buat.
Apigee Klasik
- Buka UI Apigee, login, lalu pilih organisasi Apigee Anda.
- Pilih Develop > API Proxies di menu navigasi sebelah kiri.
- Klik Buat Baru.
- Di wizard Build a Proxy, pilih Reverse proxy (most common).
- Konfigurasi 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 ada Masukkan:
https://mocktarget.apigee.net/ip
Ini menentukan URL target yang dipanggil Apigee pada permintaan ke proxy API.
Deskripsi Masukkan: hello world protected by OAuth 2.0
- Klik Berikutnya.
- Di halaman Kebijakan umum:
Di kolom ini lakukan ini Keamanan: Otorisasi Pilih: - OAuth 2.0
Opsi ini sangat berguna. Kebijakan ini akan otomatis menambahkan dua kebijakan ke proxy API Anda dan membuat produk API.
- Klik Berikutnya.
- Di halaman Ringkasan, di bagian Deployment Opsional, pilih lingkungan, lalu klik Buat dan Deploy.
- Klik Edit proxy untuk menampilkan
halaman Ringkasan untuk proxy API.
Proxy API akan otomatis di-deploy untuk Anda. (Mungkin perlu beberapa saat hingga deployment selesai.)
Melihat kebijakan
Mari kita lihat lebih dekat apa yang telah Anda buat.
Konsol Apigee Cloud
- 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 token OAuth 2.0 yang valid ada.
- Hapus Otorisasi Header – Kebijakan Tetapkan Pesan yang menghapus token akses setelah diperiksa, sehingga tidak diteruskan ke layanan target. (Jika layanan target memerlukan token akses OAuth 2.0, Anda tidak akan menggunakan kebijakan ini).
-
Klik ikon Verify OAuth v2.0 Access Token di panel sebelah kanan dan lihat XML di bawahnya di editor teks.
Apigee Klasik
- 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 token OAuth 2.0 yang valid ada.
- Hapus Otorisasi Header – Kebijakan Tetapkan Pesan yang menghapus token akses setelah diperiksa, sehingga tidak diteruskan ke layanan target. (Jika layanan target memerlukan token akses OAuth 2.0, Anda tidak akan menggunakan kebijakan ini).
-
Klik ikon Verify OAuth v2.0 Access Token dalam tampilan alur dan 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>
adalah VerifyAccessToken
. Operasi menentukan apa yang seharusnya dilakukan kebijakan. Dalam hal ini, kebijakan akan memeriksa
token OAuth 2.0 yang valid dalam permintaan.
Menambahkan produk API
Untuk mendapatkan token akses OAuth 2.0, Anda perlu membuat tiga entitas Apigee: produk API, developer, dan aplikasi developer.
- Buat produk API:
- Klik + Create.
- Masukkan Detail produk untuk produk API Anda.
Kolom Deskripsi Nama Nama internal produk API. Jangan tentukan karakter khusus dalam nama.
Catatan: Anda tidak dapat mengedit nama setelah produk API dibuat.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. Deskripsi Deskripsi produk API. Lingkungan Lingkungan yang akan diizinkan aksesnya oleh produk API. Pilih lingkungan tempat Anda men-deploy proxy API. Akses Pilih Public. Menyetujui permintaan akses secara otomatis Aktifkan persetujuan otomatis permintaan kunci untuk produk API ini dari aplikasi mana pun. Kuota Abaikan untuk tutorial ini. Cakupan OAuth 2.0 yang Diizinkan Abaikan untuk tutorial ini. - Di bagian Operations, klik Add An Operation.
- Di kolom API Proxy, pilih proxy API yang baru saja Anda buat.
- Di kolom Jalur, masukkan "/". Abaikan kolom lainnya.
- Klik Simpan untuk menyimpan Operasi.
- Klik Simpan untuk menyimpan produk API.
Apigee di Konsol Cloud
Di konsol Google Cloud , buka halaman Produk API > Distribusi.
Apigee Klasik
Di UI Apigee, buka Publikasikan > Produk API.
Menambahkan developer dan aplikasi ke organisasi Anda
Selanjutnya, Anda akan menyimulasikan alur kerja developer yang mendaftar untuk menggunakan API Anda. Idealnya, developer mendaftarkan diri dan aplikasi mereka 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/secret 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 Apigee mengetahui developer dan aplikasi mana yang termasuk dalam token OAuth 2.0 mana.
Membuat developer
Mari kita buat developer bernama Nigel Tufnel.
Apigee di Konsol Cloud
- Buka editor Developer.
-
Di konsol Google Cloud , buka halaman Distribution > Developers.
- Klik + Create.
- Masukkan informasi berikut di jendela Tambahkan Developer:
Di kolom ini Enter Nama Depan Nigel
Nama Belakang Tufnel
Email nigel@example.com
Username nigel
- Klik Tambahkan.
Apigee Klasik
- Buka editor Developer.
-
Di UI Apigee, buka Publikasikan > Developer.
- Klik + Developer.
- Masukkan hal berikut di jendela Create a Developer:
Di kolom ini Enter Nama Depan Nigel
Nama Belakang Tufnel
Email nigel@example.com
Username nigel
- Klik Buat.
Mendaftarkan aplikasi
Mari kita buat aplikasi untuk Niko.
Apigee di Konsol Cloud
-
Di konsol Google Cloud , buka halaman Distribution > Apps.
- Klik + Create.
- Masukkan hal berikut di jendela Aplikasi Baru:
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 - Klik + Tambahkan Kredensial.
- Klik + Tambahkan Produk.
- Pilih produk API yang baru saja Anda buat.
- Klik Tambahkan.
- Klik Buat.
Apigee Klasik
-
Di UI Apigee, buka Publikasikan > Developer.
- Klik + Developer.
- Klik + Aplikasi.
- Masukkan hal berikut di jendela Aplikasi Baru:
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.
- Tambahkan produk API yang baru saja Anda buat.
- Klik Buat.
Dapatkan kunci pengguna dan rahasia pengguna
Sekarang Anda akan mendapatkan kunci konsumen dan rahasia konsumen yang akan ditukar dengan token akses OAuth 2.0.
- Buka halaman nigel_app.
- Pastikan halaman nigel_app ditampilkan. Jika belum, buka halaman Distribution > Apps.
- Di halaman nigel_app, klik di kolom Key dan Secret. Perhatikan bahwa kunci/secret dikaitkan dengan produk API yang Anda buat sebelumnya.
- Pastikan halaman nigel_app ditampilkan. Jika tidak, di halaman Aplikasi (Publikasikan > Aplikasi), klik nigel_app.
-
Di halaman nigel_app, klik Show di kolom Key dan Secret. Perhatikan bahwa kunci/secret dikaitkan dengan produk API yang Anda buat sebelumnya.
-
Pilih dan salin nilai Kunci dan Rahasia. Tempelkan ke dalam file teks sementara. Anda akan menggunakannya pada langkah selanjutnya, saat Anda memanggil proxy API yang akan menukar kredensial ini dengan token akses OAuth 2.0.
Apigee di Konsol Cloud
Apigee Klasik
Coba panggil API untuk mendapatkan alamat IP Anda (gagal!)
Coba panggil proxy API yang dilindungi yang baru saja Anda buat. Perhatikan bahwa Anda tidak meneruskan token akses OAuth 2.0 dalam panggilan.
dengan YOUR ENV_GROUP_HOSTNAME
adalah nama host grup lingkungan. Lihat
Menemukan nama host grup lingkungan.
Karena proxy API memiliki kebijakan Verify OAuth v2.0 Access Token yang memeriksa token OAuth 2.0 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 2.0 yang valid yang dapat berhasil memanggil API ini.
Mendapatkan token akses OAuth 2.0
Selanjutnya, Anda akan menggunakan kunci dan rahasia yang Anda salin dan tempel ke dalam file teks, lalu menukarkannya dengan token akses OAuth 2.0. Sekarang Anda akan membuat panggilan API ke proxy contoh API yang Anda impor, oauth, yang akan membuat token akses API.
Dengan menggunakan kunci dan secret tersebut, lakukan panggilan cURL berikut (perhatikan bahwa protokolnya adalah
https
):
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \ "https://YOUR ENV_GROUP_HOSTNAME/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
masuk ke 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 2.0. Salin nilai access_token
(tanpa tanda petik) dan
tempelkan ke file teks Anda. Anda akan menggunakannya sebentar lagi.
Apa yang baru saja terjadi?
Ingat sebelumnya saat Anda melihat "alur bersyarat" di proxy
oauth, yang mengatakan jika URI resource adalah
/accesstoken
dan kata kerja permintaan adalah POST
, untuk mengeksekusi
kebijakan OAuth 2.0 GenerateAccessTokenClient
yang menghasilkan token akses? Perintah cURL
Anda memenuhi kondisi tersebut, sehingga kebijakan OAuth 2.0 dijalankan. API ini memverifikasi kunci konsumen
dan rahasia konsumen Anda, lalu menukarkannya dengan token OAuth 2.0 yang akan habis masa berlakunya dalam 1 jam.
Panggil API dengan token akses (berhasil!)
Setelah memiliki token akses, Anda dapat menggunakannya untuk memanggil proxy API. Lakukan panggilan cURL berikut. Ganti nama organisasi Apigee dan token akses Anda.
curl https://YOUR ENV_GROUP_HOSTNAME/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 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 2.0 yang valid disertakan dalam panggilan.
Topik terkait
- Beranda OAuth 2.0
- Kebijakan OAuthV2
- Mendownload proxy API (yang menunjukkan cara menggabungkan proxy API ke dalam file ZIP seperti yang Anda download)