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 Anda gunakan untuk melakukan panggilan proxy Apigee API. Jika Anda tidak yakin dengan nama host grup lingkungan yang akan digunakan, lihat 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:

  1. Download contoh proxy API oauth ke direktori di sistem file Anda.
  2. Buka UI Apigee, lalu login dan pilih organisasi Apigee Anda.
  3. Pilih Develop > API Proxies di menu navigasi sebelah kiri.
  4. Klik Buat Baru.
    Tombol Buat proxy
  5. Di wizard Create Proxy, pilih Upload proxy bundle.
  6. Pilih file oauth.zip yang Anda download, lalu klik Next.
  7. Klik Buat.
  8. Setelah build selesai, klik Edit proxy untuk melihat proxy baru di editor proxy API.
  9. Klik Deploy.
  10. Pilih revisi dan lingkungan yang menjadi tujuan deployment. Anda dapat mengosongkan kolom Service account.
  11. Klik Deploy.

Anda telah berhasil mendownload dan men-deploy proxy API yang membuat token akses ke organisasi Apigee.

Melihat alur dan kebijakan OAuth 2.0

Luangkan waktu beberapa saat untuk memeriksa konfigurasi kebijakan OAuth 2.0.

Editor Proxy Baru

Selanjutnya, Anda akan melihat lebih dekat konten proxy API.

  1. Di editor proxy API, klik tab Mengembangkan.

    Kebijakan yang ditampilkan di tab Develop.

    Di panel kiri, Anda akan melihat dua kebijakan. Anda juga akan melihat dua alur POST di bagian Proxy Endpoints.

  2. Klik AccessTokenClientCredential di bagian Proxy Endpoints. Editor teks menampilkan kode XML untuk alur kondisional 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 di 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 adalah POST, jalankan kebijakan GenerateAccessTokenClient, yang menghasilkan token akses.

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

Editor Proxy Klasik

Selanjutnya, Anda akan melihat lebih dekat konten proxy API.

  1. Di editor proxy API, klik tab Mengembangkan. Di panel Navigator sebelah kiri, Anda akan melihat dua kebijakan. Anda juga akan melihat dua alur POST di bagian Proxy Endpoints.

  2. Klik AccessTokenClientCredential di bagian Endpoint Proxy.
    Kode XML untuk alur bersyarat.

    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>

    Alur adalah langkah pemrosesan di 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 adalah POST, jalankan kebijakan GenerateAccessTokenClient, yang menghasilkan token akses.

  3. Sekarang, mari kita lihat kebijakan yang akan dipicu oleh alur kondisional. Klik ikon kebijakan GenerateAccessTokenClient dalam diagram alur.

    Ikon kebijakan GenerateAccessTokenClient dalam diagram alur.

Konfigurasi XML berikut akan 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 standar, menentukan tindakan 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>, <GrantType> OAuth 2.0 yang diharapkan akan digunakan adalah client_credentials (menukar kunci dan secret konsumen untuk token OAuth 2.0).
  • Elemen <GrantType> kedua memberi tahu kebijakan tempat mencari parameter jenis pemberian dalam panggilan API, seperti yang diwajibkan oleh spesifikasi OAuth 2.0. (Anda akan melihatnya dalam panggilan API nanti). Jenis pemberian juga dapat dikirim dalam 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 berikutnya, Anda akan menggunakan proxy API ini untuk membuat token akses OAuth 2.0. Namun, pertama-tama, Anda perlu 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 secret konsumen yang perlu Anda tukar 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. NAMUN, Anda hanya akan 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.

  1. Pilih Develop > API Proxies di menu navigasi sebelah kiri.
  2. Klik Buat Baru.
    Tombol Buat proxy
  3. Di wizard Build a Proxy, pilih Reverse proxy (most common).
  4. Konfigurasikan proxy dengan hal berikut:
    Di kolom ini lakukan hal ini
    Nama Proxy Masukkan: helloworld_oauth2
    Jalur Dasar Project

    Ubah menjadi: /hellooauth2

    Project Base Path 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
  5. Klik Berikutnya.
  6. Di halaman Kebijakan umum:
    Di kolom ini lakukan hal ini
    Keamanan: Otorisasi Pilih:
    • OAuth 2.0

    Opsi ini sangat berguna. Tindakan ini akan otomatis menambahkan dua kebijakan ke proxy API Anda dan membuat produk API.
  7. Klik Berikutnya.
  8. Di halaman Ringkasan, pada bagian Deployment Opsional, pilih lingkungan, lalu klik Buat dan Deploy.
  9. Klik Edit proxy untuk menampilkan halaman Ringkasan untuk proxy API.
    Proxy API di-deploy secara otomatis untuk Anda. (Mungkin perlu waktu beberapa saat hingga deployment selesai.)

Melihat kebijakan

Mari kita lihat lebih dekat apa yang telah Anda buat.

Editor Proxy Baru

  1. Di editor proxy API, klik tab Mengembangkan. Anda akan melihat bahwa dua kebijakan telah ditambahkan ke alur permintaan proxy API:
    • Verify OAuth v2.0 Access Token – 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).

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

Editor Proxy Klasik

  1. Di editor proxy API, klik tab Mengembangkan. Anda akan melihat bahwa dua kebijakan telah ditambahkan ke alur permintaan proxy API:
    • Verify OAuth v2.0 Access Token – 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).

  2. Klik ikon Verify OAuth v2.0 Access Token di tampilan alur dan lihat XML di bawahnya di panel kode.

    Memverifikasi kode Token Akses OAuth v2.0

<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 harus 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. 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 Name akan digunakan. Kolom ini diisi secara otomatis menggunakan nilai Nama; Anda dapat mengedit atau menghapus kontennya. Nama tampilan dapat menyertakan karakter khusus.
    Deskripsi Deskripsi produk API.
    Lingkungan Lingkungan yang akan mengizinkan akses produk API. Pilih lingkungan tempat Anda men-deploy proxy API.
    Akses Pilih Public.
    Menyetujui permintaan akses secara otomatis Mengaktifkan 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.
  4. Di bagian Operations, klik Add An Operation.
  5. Di kolom API Proxy, pilih proxy API yang baru saja Anda buat.
  6. Di kolom Jalur, masukkan "/". Abaikan kolom lainnya.
  7. Klik Simpan untuk menyimpan Operasi.
  8. Klik Simpan untuk menyimpan 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 secret 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 Apigee mengetahui developer dan aplikasi mana yang memiliki token OAuth 2.0.

Membuat developer

Mari kita buat developer bernama Nigel Tufnel.

  1. Pilih Publikasikan > Developer di menu.
  2. Klik + Developer.
  3. Masukkan hal berikut di jendela New Developer:
    Di kolom ini Enter
    Nama Depan Nigel
    Nama Belakang Tufnel
    Username nigel
    Email nigel@example.com
  4. Klik Simpan.

Mendaftarkan aplikasi

Mari kita buat aplikasi untuk Nigel.

  1. Pilih Publikasikan > Aplikasi.
  2. Klik + Aplikasi.
  3. Masukkan hal berikut di jendela New App:
    Di kolom ini lakukan hal ini
    Nama dan Nama Tampilan Masukkan: nigel_app
    Developer Klik Developer, lalu pilih: Nigel Tufnel (nigel@example.com)
    URL Callback dan Catatan Biarkan kosong
  4. Di bagian Produk, klik Tambahkan produk.
  5. Tambahkan produk API yang baru saja Anda buat.
  6. Klik Buat.

Mendapatkan kunci pengguna dan rahasia pengguna

Sekarang Anda akan mendapatkan kunci konsumen dan secret konsumen yang akan ditukar dengan token akses OAuth 2.0.

  1. Pastikan halaman nigel_app ditampilkan. Jika belum, di halaman Aplikasi (Publikasikan > Aplikasi), klik nigel_app.

  2. Di halaman nigel_app, klik Tampilkan di kolom Kunci dan Rahasia. Perhatikan bahwa kunci/rahasia dikaitkan dengan produk API yang Anda buat sebelumnya.

  3. Pilih dan salin Kunci dan Rahasia. Tempelkan dalam file teks sementara. Anda akan menggunakannya pada langkah berikutnya, saat 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 Menemukan nama host grup lingkungan.

Karena proxy API memiliki kebijakan Verifikasi Token Akses OAuth v2.0 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 berhasil memanggil API ini.

Mendapatkan token akses OAuth 2.0

Selanjutnya, Anda akan menggunakan kunci dan secret yang disalin dan ditempel ke dalam file teks, lalu menukarnya dengan token akses OAuth 2.0. Sekarang Anda akan melakukan panggilan API ke proxy contoh API yang Anda impor, oauth, yang akan menghasilkan 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 akan berada di 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 dalam file teks Anda. Anda akan menggunakannya sebentar lagi.

Apa yang baru saja terjadi?

Ingat sebelumnya saat Anda melihat "alur kondisional" di proxy oauth, yang menyatakan bahwa 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 secret konsumen Anda, lalu menukarnya dengan token OAuth 2.0 yang akan berakhir masa berlakunya 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 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 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 2.0 yang valid disertakan dalam panggilan.

Topik terkait