Mengamankan API dengan OAuth 2.0

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 digunakan melakukan panggilan proxy Apigee API. Jika Anda tidak yakin tentang nama host grup lingkungan yang akan digunakan, hubungi administrator Apigee Anda.

Men-deploy proxy OAuth 2.0

Kami menyediakan proxy API di GitHub yang dikonfigurasi untuk menghasilkan token akses OAuth 2.0. Ikuti langkah-langkah berikut untuk download dan deploy proxy API ini ke lingkungan Anda:

1. Download proxy API contoh oauth ke direktori di file Anda sistem file.
2. Buka UI Apigee, lalu login, lalu pilih organisasi Apigee Anda.
3. Pilih Develop > Proxy API di menu navigasi sebelah kiri.
   Catatan: Sebelum melanjutkan, lihat atau telusuri daftar API Anda menggunakan {i>proxy<i}. Jika Anda sudah memiliki oauth, klik dan langsung ke bagian bagian berikutnya untuk memastikannya dikonfigurasi sama seperti yang dijelaskan. Jika milik Anda adalah berbeda, hapus dan lanjutkan langkah ini, atau ubah agar sesuai dengan konfigurasi yang dijelaskan.
4. Klik Buat Baru.
   
5. Di wizard Create Proxy, pilih Upload proxy bundle.
6. Pilih file oauth.zip yang Anda download, lalu klik Berikutnya.
7. Klik Create.
8. Setelah build selesai, klik Edit proxy untuk melihat proxy baru di editor proxy API.
9. Klik Deploy.
10. Pilih revisi dan lingkungan yang akan di-deploy. Anda dapat meninggalkan Kolom Service account kosong.
11. Klik Deploy.

Anda telah berhasil mendownload dan men-deploy API pembuatan token akses ke organisasi Apigee Anda.

Lihat alur dan kebijakan OAuth 2.0

Luangkan waktu sejenak untuk memeriksa konfigurasi kebijakan OAuth 2.0.

Catatan: Apigee memperkenalkan Proxy versi baru Editor, yang akan mempermudah pengelolaan proxy.

Petunjuk pada dua tab pertama di bawah ini menjelaskan cara gunakan Editor Proxy baru atau Editor Proxy klasik.

Editor Proxy Baru

Selanjutnya, Anda akan mempelajari lebih lanjut isi proxy API.

1. Di editor proxy API, klik tab Develop.

   

   Di sebelah kiri Anda akan melihat dua kebijakan. Anda juga akan melihat dua alur POST di Endpoint Proxy bagian.

2. 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>
   

   Flow adalah langkah pemrosesan di proxy API. Dalam hal ini, alur akan terpicu saat kondisi tertentu terpenuhi (disebut "alur bersyarat"). Kondisi, yang didefinisikan dalam elemen <Condition>, menyebutkan bahwa jika panggilan proxy API dilakukan untuk resource /accesstoken, dan kata kerja permintaan adalah POST, lalu mengeksekusi kebijakan GenerateAccessTokenClient, yang menghasilkan akses sebelumnya yang benar.

3. Sekarang, mari kita lihat kebijakan yang akan dipicu oleh alur kondisional. Klik Kebijakan GenerateAccessTokenClient di panel Request:

Editor Proxy Klasik

Selanjutnya, Anda akan mempelajari lebih lanjut isi proxy API.

1. Di editor proxy API, klik tab Develop. Di Navigator kiri Anda akan melihat dua kebijakan. Anda juga akan melihat dua alur POST di Endpoint Proxy bagian.

2. Klik AccessTokenClientCredential di bagian Proxy Endpoints.
   

   Dalam tampilan kode XML, Anda akan melihat Flow yang disebut AccessTokenClientCredential:

   <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 di proxy API. Dalam hal ini, alur akan terpicu saat kondisi tertentu terpenuhi. Kondisi, yang didefinisikan dalam elemen <Condition>, adalah bahwa jika panggilan proxy API dilakukan untuk resource /accesstoken, dan kata kerja permintaan adalah POST, lalu mengeksekusi kebijakan GenerateAccessTokenClient, yang menghasilkan akses sebelumnya yang benar.

3. Sekarang, mari kita lihat kebijakan yang akan dipicu oleh alur kondisional. 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, mendefinisikan apa yang akan dilakukan oleh kebijakan tersebut. Dalam hal ini, ini akan menghasilkan akses sebelumnya yang benar.
• Masa berlaku token akan berakhir 1 jam (3600000 milidetik) setelah dibuat.
• Di <SupportedGrantTypes>, OAuth 2.0 <GrantType> yang diperkirakan akan digunakan adalah client_credentials (bertukar kunci dan rahasia konsumen untuk token OAuth 2.0).
• Elemen <GrantType> kedua memberi tahu kebijakan tempat untuk memeriksa panggilan API untuk parameter jenis pemberian, seperti yang diwajibkan oleh spesifikasi OAuth 2.0. (Anda akan melihat ini di panggilan API nanti). Jenis pemberian izin juga dapat dikirim dalam bentuk header (request.header.grant_type) atau sebagai parameter formulir (request.formparam.grant_type).

Saat ini, Anda tidak perlu melakukan apa pun terhadap proxy API. Pada langkah selanjutnya, Anda akan menggunakan proxy API ini untuk membuat token akses OAuth 2.0. Tapi pertama-tama, Anda perlu melakukan beberapa hal lainnya:

• Buat proxy API yang sebenarnya ingin Anda amankan dengan OAuth 2.0.
• Buat beberapa artefak lain yang akan menghasilkan kunci konsumen dan rahasia konsumen Anda harus menukar sebuah token akses.

Catatan: Alur dan kebijakan RefreshAccessToken di proxy API tidak digunakan dalam tutorial ini dan tidak didukung oleh pemberian kredensial klien OAuth 2.0 jenis ini.

Membuat proxy API yang dilindungi

Sekarang Anda akan membuat proxy API yang ingin dilindungi. Ini adalah panggilan API yang menghasilkan sesuatu yang Anda inginkan. Dalam hal ini, proxy API akan memanggil layanan mocktarget Apigee untuk mengembalikan alamat IP Anda. TETAPI, Anda akan melihatnya hanya jika Anda meneruskan akses OAuth 2.0 yang valid token akses dengan panggilan API Anda.

Proxy API yang Anda buat di sini akan menyertakan kebijakan yang memeriksa token OAuth 2.0 di permintaan.

1. Pilih Develop > Proxy API di menu navigasi sebelah kiri.
2. Klik Buat Baru.
   
3. Di wizard Build a Proxy, pilih Reverse proxy (paling umum).
4. 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 API {i>proxy<i}.
   API yang sudah ada	Masukkan: https://mocktarget.apigee.net/ip Ini menentukan URL target yang dipanggil Apigee pada permintaan ke API {i>proxy<i}.
   Deskripsi	Masukkan: hello world protected by OAuth 2.0

5. Klik Next.
6. Di halaman Kebijakan umum:

   Di kolom ini	lakukan ini
   Keamanan: Otorisasi	Pilih: OAuth 2.0 Opsi ini sangat berguna. Mereka akan secara otomatis menambahkan dua kebijakan ke Proxy API dan buat produk API.

7. Klik Next.
8. Di halaman Ringkasan, di bagian Deployment Opsional, pilih lingkungan, lalu klik Create and Deploy.
9. Klik Edit proxy untuk menampilkan Halaman utama untuk proxy API.
   Proxy API di-deploy secara otomatis untuk Anda. (Mungkin perlu beberapa saat untuk deployment untuk diselesaikan.)

Lihat kebijakan

Mari kita lihat lebih dekat apa yang telah Anda buat.

Editor Proxy Baru

1. Di editor proxy API, klik tab Develop. Anda akan melihat bahwa kebijakan telah ditambahkan ke alur permintaan proxy API:
   • Verifikasi Token Akses OAuth v2.0 – Memeriksa panggilan API yang akan dilakukan memastikan token OAuth 2.0 yang valid ada.
   • Remove Header Authorization – kebijakan Tetapkan Pesan yang menghapus token akses setelah diperiksa, sehingga tidak diteruskan ke target layanan. (Jika layanan target memerlukan token akses OAuth 2.0, Anda tidak akan menggunakan kebijakan ini).

2. Klik ikon Verify OAuth v2.0 Access Token di di panel sebelah kanan lihat XML di bawahnya pada editor teks.

Editor Proxy Klasik

1. Di editor proxy API, klik tab Develop. Anda akan melihat bahwa kebijakan telah ditambahkan ke alur permintaan proxy API:
   • Verifikasi Token Akses OAuth v2.0 – Memeriksa panggilan API yang akan dilakukan memastikan token OAuth 2.0 yang valid ada.
   • Remove Header Authorization – kebijakan Tetapkan Pesan yang menghapus token akses setelah diperiksa, sehingga tidak diteruskan ke target layanan. (Jika layanan target memerlukan token akses OAuth 2.0, Anda tidak akan menggunakan kebijakan ini).

2. Klik ikon Verify OAuth v2.0 Access Token di 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. Tujuan Operasi mendefinisikan apa yang seharusnya dilakukan oleh kebijakan. Dalam hal ini, ia akan memeriksa untuk token OAuth 2.0 yang valid dalam permintaan.

Menambahkan produk API

Untuk mendapatkan token akses OAuth 2.0, Anda perlu membuat tiga entity Apigee: produk API, pengembang, dan aplikasi pengembang. Pertama, buat produk API:

1. Pilih Publikasikan > Produk API.
2. Klik +Create.
3. 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 secara otomatis menggunakan nilai Name; Anda dapat mengedit atau menghapus isinya. Nama tampilan dapat berisi karakter khusus.
   Deskripsi	Deskripsi produk API.
   Lingkungan	Lingkungan yang akan diizinkan aksesnya oleh produk API. Pilih lingkungan tempat Anda telah men-deploy proxy API.
   Akses	Pilih Public.
   Menyetujui permintaan akses secara otomatis	Aktifkan persetujuan otomatis permintaan kunci untuk produk API ini dari aplikasi apa pun.
   Kuota	Abaikan untuk tutorial ini.
   Cakupan OAuth 2.0 yang Diizinkan	Abaikan untuk tutorial ini.

4. Di bagian Operations, klik Add An Operation.
5. Pada bidang Proxy API, pilih proxy API yang baru saja Anda buat.
6. Di kolom Jalur, masukkan "/". Abaikan kolom lainnya.
7. Klik Save untuk menyimpan Operasi.
8. Klik Save untuk menyimpan produk API.

Tambahkan developer dan aplikasi ke organisasi

Selanjutnya, Anda akan menyimulasikan alur kerja developer yang mendaftar untuk menggunakan API Anda. Idealnya, developer mendaftarkan diri dan aplikasi mereka melalui portal developer Anda. Di sini meskipun demikian, Anda akan menambahkan pengembang dan aplikasi sebagai administrator.

Developer akan memiliki satu atau beberapa aplikasi yang memanggil API Anda, dan setiap aplikasi akan mendapatkan kunci konsumen dan rahasia konsumen. Kunci/rahasia-per-aplikasi ini juga memberi Anda, penyedia API, kontrol yang lebih terperinci atas akses ke API Anda dan pelaporan analisis yang lebih terperinci terkait API traffic, karena Apigee tahu developer dan aplikasi mana yang termasuk dalam token OAuth 2.0.

Membuat developer

Mari kita buat developer bernama Nigel Tufnel.

1. Pilih Publikasikan > Developer di menu.
2. Klik + Developer.
3. Masukkan kode berikut di jendela Developer Baru:
   

   Di kolom ini	Enter
   Nama Depan	Nigel
   Nama Belakang	Tufnel
   Username	nigel
   Email	[e-mail]

4. Klik Simpan.

Daftarkan aplikasi

Mari buat aplikasi untuk Nigel.

1. Pilih Publikasikan > Aplikasi.
2. Klik + App.
3. Masukkan hal berikut di jendela New App:
   

   Di kolom ini	lakukan ini
   Name dan Display Name	Masukkan: nigel_app
   Developer	Klik Developer lalu pilih: Nigel Tufnel ([e-mail])
   URL Callback dan Catatan	Biarkan kosong

4. Di bagian Produk, klik Tambahkan produk.
5. Tambahkan produk API yang baru saja Anda buat.
6. Klik Create.

Dapatkan kunci konsumen dan rahasia konsumen

Sekarang Anda akan mendapatkan kunci konsumen dan rahasia konsumen yang akan ditukarkan dengan OAuth 2.0 token masing-masing.

1. Pastikan halaman nigel_app ditampilkan. Jika belum, pada halaman Aplikasi (Publish > Apps), klik nigel_app.

2. Di halaman nigel_app, klik Show di Key dan Secret. Perhatikan bahwa kunci/rahasia adalah yang terkait dengan produk API yang Anda buat sebelumnya.

3. Pilih dan salin {i>Key<i} dan {i>Secret<i}. Tempelkan dalam file teks. Anda akan menggunakannya di langkah selanjutnya, di mana Anda memanggil proxy API yang akan menukar kredensial ini dengan token akses OAuth 2.0.

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 Temukan nama host grup lingkungan.

Karena proxy API memiliki kebijakan Verifikasi Token Akses OAuth v2.0 memeriksa token OAuth 2.0 yang valid dalam permintaan, panggilan akan gagal dengan pesan:

{"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 tepercaya aplikasi dengan token akses OAuth 2.0 yang valid berhasil memanggil API ini.

Mendapatkan token akses OAuth 2.0

Selanjutnya, Anda akan menggunakan kunci dan rahasia disalin dan ditempelkan ke file teks dan tukarkan dengan token akses OAuth 2.0. Anda sekarang 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 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 {i>Postman<i} untuk melakukan panggilan, client_id dan client_secret masuk ke bagian Isi 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" : "[e-mail]",
  "token_type" : "BearerToken",
  "client_id" : "xNnREu1DNGfiwzQZ5HUN8IAUwZSW1GZW",
  "access_token" : "GTPY9VUHCqKVMRB0cHxnmAp0RXc0",
  "organization_name" : "myOrg",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

Anda sudah mendapatkan token akses OAuth 2.0. Salin nilai access_token (tanpa tanda kutip) dan menempelkannya ke dalam file teks Anda. Anda akan segera menggunakannya.

Apa yang baru saja terjadi?

Ingat sebelumnya ketika Anda melihat "alur bersyarat" itu di Proxy oauth, yang bertuliskan jika URI resource /accesstoken dan kata kerja permintaannya adalah POST, untuk mengeksekusi GenerateAccessTokenClient Kebijakan OAuth 2.0 yang membuat token akses? cURL Anda memenuhi ketentuan tersebut, sehingga kebijakan OAuth 2.0 dijalankan. Google Analytics 4 memverifikasi kunci konsumen rahasia konsumen dan menukarnya dengan token OAuth 2.0 yang kedaluwarsa dalam 1 jam.

Panggil API dengan token akses (berhasil)

Setelah memiliki token akses, Anda dapat menggunakannya untuk memanggil proxy API. Jadikan setelah panggilan cURL. Ganti nama organisasi Apigee Anda dan token akses.

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 bisa 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 akan disertakan dalam panggilan.

Topik terkait

• Beranda OAuth 2.0
• Kebijakan OAuthV2
• Mendownload proxy API (yang menunjukkan cara memaketkan proxy API ke dalam file ZIP seperti yang Anda download)