Mengamankan API dengan OAuth

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

  1. Download file ZIP proxy API contoh 'oauth' ke direktori mana pun di sistem file Anda.
  2. Buka https://apigee.com/edge dan login.
  3. Pilih Develop > API Proxies di menu navigasi sebelah kiri.
  4. Klik + Proxy.
    Tombol buat proxy
  5. Di wizard Create Proxy, klik Upload paket proxy.
  6. Pilih file oauth.zip yang Anda download, lalu klik Next.
  7. Klik Create.
  8. Setelah build selesai, klik Edit proxy untuk melihat proxy baru di editor proxy API.
  9. 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.

  1. 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.
  2. Klik AccessTokenClientCredential di bagian Proxy Endpoints.

    Dalam tampilan kode XML, Anda akan melihat Flow bernama 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> ini menyatakan bahwa jika panggilan proxy API dilakukan ke resource /accesstoken, dan verb permintaan adalah POST, maka jalankan kebijakan GenerateAccessTokenClient, yang menghasilkan token akses.

  3. 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 adalah client_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

Tentang 'mocktarget'

Layanan mocktarget dihosting di Apigee dan menampilkan data sederhana. Bahkan, Anda dapat mengaksesnya di browser web. Cobalah dengan mengklik berikut ini:

http://mocktarget.apigee.net/ip

Target menampilkan apa yang akan Anda lihat ketika akhirnya memanggil proxy API ini.

Anda juga dapat menekan http://mocktarget.apigee.net/help untuk melihat resource API lain yang tersedia di mocktarget.

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.

  1. Pilih Develop > API Proxies di menu navigasi sebelah kiri.
  2. Klik + Proxy.
    Tombol buat proxy
  3. Di wizard Build a Proxy, pilih Reverse proxy (paling umum), lalu klik Next.
  4. 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
  5. Klik Next.
  6. Di halaman Kebijakan umum:
    Di kolom ini lakukan ini
    Keamanan: Otorisasi Pilih: OAuth 2.0
  7. Klik Next.
  8. Di halaman Virtual Hosts, klik Next.
  9. Pada halaman Build, pastikan lingkungan test dipilih, lalu klik Create and Deploy.
  10. Di halaman Summary, Anda akan melihat konfirmasi bahwa proxy API baru berhasil dibuat dan proxy API telah di-deploy ke lingkungan pengujian.
  11. 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.

  1. 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).
  2. 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> adalah VerifyAccessToken. 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:

  1. Pilih Publish > API Products.
  2. Klik +produk API.
  3. 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.
  4. Di kolom API proxy, pilih proxy API yang baru saja dibuat.
  5. Di kolom Jalur, masukkan "/". Abaikan kolom lainnya.
  6. 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.

  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 nigel@example.com
  4. Klik Create.

Daftarkan aplikasi

Mari kita buat aplikasi untuk Nigel.

  1. Pilih Publikasikan > Aplikasi.
  2. Klik + Aplikasi.
  3. 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
  4. Di bagian Produk, klik Tambahkan Produk.
  5. Pilih helloworld_oauth2-Product.
  6. Klik Create.

Mendapatkan kunci dan rahasia konsumen

Sekarang Anda akan mendapatkan kunci konsumen dan rahasia konsumen yang akan ditukarkan dengan token akses OAuth.

  1. Pastikan halaman nigel_app ditampilkan. Jika tidak, di halaman Aplikasi (Publish > Apps), klik nigel_app.
  2. 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.

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