Halaman ini diterjemahkan oleh Cloud Translation API.

Mengamankan API dengan OAuth 2.0

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Baca 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 yang 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 untuk melakukan panggilan proxy Apigee API. Jika tidak yakin dengan nama host grup lingkungan yang harus 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:

Download proxy API contoh oauth ke direktori di sistem file Anda.
Buka UI Apigee, lalu login, lalu pilih organisasi Apigee Anda.
Pilih Develop > API Proxies di menu navigasi sebelah kiri.
Catatan: Sebelum melanjutkan, lihat atau telusuri daftar proxy API Anda. Jika Anda sudah memiliki oauth, klik perintah tersebut dan lanjutkan ke bagian berikutnya untuk memastikan objek tersebut dikonfigurasi sama dengan yang dijelaskan. Jika milik Anda berbeda, hapus dan lanjutkan langkah-langkah ini, atau ubah agar sesuai dengan konfigurasi yang dijelaskan.
Klik Create New.
Di wizard Create Proxy, pilih Upload paket proxy.
Pilih file oauth.zip yang Anda download, lalu klik Next.
Klik Create.
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 Service account.
Klik Deploy.

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

Melihat alur dan kebijakan OAuth 2.0

Luangkan waktu sejenak untuk memeriksa konfigurasi kebijakan OAuth 2.0.

Editor Proxy Baru

Selanjutnya, Anda akan mempelajari lebih lanjut apa saja yang terdapat dalam 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 jika kondisi tertentu terpenuhi (disebut "alur bersyarat"). Kondisi yang ditentukan dalam elemen <Condition> ini menyatakan bahwa jika panggilan proxy API dilakukan ke resource /accesstoken, dan kata kerja permintaannya adalah POST, maka jalankan kebijakan GenerateAccessTokenClient yang menghasilkan token akses.
Sekarang, mari kita lihat kebijakan yang akan dipicu oleh alur bersyarat. Klik kebijakan GenerateAccessTokenClient di panel Request:

Editor Proxy Klasik

Selanjutnya, Anda akan mempelajari lebih lanjut apa saja yang terdapat dalam proxy API.

Di editor proxy API, klik tab Develop. Di panel Navigator sebelah kiri, Anda akan melihat dua kebijakan. Anda juga akan melihat dua alur POST di bagian Proxy Endpoints.
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 dalam proxy API. Dalam hal ini, alur dipicu jika kondisi tertentu terpenuhi. Kondisi yang ditentukan dalam elemen <Condition> adalah jika panggilan proxy API dilakukan ke resource /accesstoken, dan kata kerja permintaannya adalah POST, maka eksekusi kebijakan GenerateAccessTokenClient yang menghasilkan token akses.
Sekarang, mari kita lihat kebijakan yang akan dipicu oleh alur bersyarat. Klik ikon kebijakan GenerateAccessTokenClient pada 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>

Konfigurasinya mencakup hal berikut:

<Operation>, yang dapat berupa salah satu dari beberapa nilai yang telah ditetapkan, menentukan apa yang akan dilakukan kebijakan. Dalam hal ini, kebijakan akan menghasilkan token akses.
Masa berlaku token akan berakhir 1 jam (3600000 milidetik) setelah dibuat.
Dalam <SupportedGrantTypes>, OAuth 2.0 <GrantType> yang diharapkan akan digunakan adalah client_credentials (bertukar kunci dan rahasia konsumen untuk token OAuth 2.0).
Elemen <GrantType> kedua memberi tahu kebijakan tempat untuk mencari di 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 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. Di langkah berikutnya, Anda akan menggunakan proxy API ini untuk membuat token akses OAuth 2.0. Namun sebelumnya, Anda perlu melakukan beberapa hal lagi:

Buat proxy API yang benar-benar 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 melihatnya jika meneruskan token akses OAuth 2.0 yang valid dengan panggilan API.

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

Pilih Develop > API Proxies di menu navigasi sebelah kiri.
Klik Create New.
Di wizard Build a Proxy, pilih Reverse proxy (paling umum).

Konfigurasikan proxy dengan hal berikut:

Di kolom ini	lakukan ini
Nama Proxy	Masukkan: `helloworld_oauth2`
Jalur Dasar Project	Ubah ke: `/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` Ini menentukan URL target yang dipanggil Apigee pada permintaan ke proxy API.
Deskripsi	Masukkan: `hello world protected by OAuth 2.0`

Klik Next.

Di halaman Kebijakan umum:

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

Di kolom ini

lakukan ini

Keamanan: Otorisasi

Pilih:

OAuth 2.0

Opsi ini sangat berguna. Mereka akan otomatis menambahkan dua kebijakan ke proxy API Anda dan membuat produk API.

Klik Next.
Di halaman Summary, di bagian Optional Deployment, pilih lingkungan, lalu klik Create and Deploy.
Klik Edit proxy untuk menampilkan halaman Ringkasan untuk proxy API.
Proxy API otomatis di-deploy untuk Anda. (Mungkin perlu waktu beberapa saat hingga deployment selesai.)

Lihat kebijakan

Mari kita lihat lebih dekat apa yang telah Anda buat.

Editor Proxy Baru

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 2.0 yang valid.
- Remove Header Authorization – Kebijakan Tetapkan Pesan yang menghapus token akses setelah dicentang, sehingga tidak diteruskan ke layanan target. (Jika layanan target memerlukan token akses OAuth 2.0, Anda tidak perlu menggunakan kebijakan ini).
Klik ikon Verify OAuth v2.0 Access Token di panel sebelah kanan dan lihat XML di bawahnya di editor teks.

Editor Proxy 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 ada token OAuth 2.0 yang valid.
- Remove Header Authorization – Kebijakan Tetapkan Pesan yang menghapus token akses setelah dicentang, sehingga tidak diteruskan ke layanan target. (Jika layanan target memerlukan token akses OAuth 2.0, Anda tidak perlu menggunakan kebijakan ini).
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. Operasi akan menetapkan apa yang seharusnya dilakukan kebijakan. Dalam hal ini, akan memeriksa token OAuth 2.0 yang valid dalam permintaan.

Menambahkan produk API

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

Pilih Publish > API Products.
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 Name akan digunakan. Kolom ini diisi secara otomatis menggunakan nilai Nama; Anda dapat mengedit atau menghapus kontennya. Nama tampilan dapat berisi 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 atas permintaan kunci untuk produk API ini dari aplikasi apa pun.
Kuota	Abaikan tutorial ini.
Cakupan OAuth 2.0 yang Diizinkan	Abaikan tutorial ini.

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

Menambahkan developer dan aplikasi ke organisasi Anda

Berikutnya, Anda akan menyimulasikan alur kerja developer yang mendaftar untuk menggunakan API Anda. Idealnya, developer mendaftarkan diri mereka sendiri 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 akan 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 tentang traffic API, karena Apigee mengetahui token OAuth 2.0 milik developer dan aplikasi mana.

Membuat developer

Mari kita buat developer bernama Nigel Tufnel.

Pilih Publish > Developers di menu.
Klik + Developer.

Masukkan teks berikut di jendela Developer Baru:

Di kolom ini	Enter
Nama Depan	`Nigel`
Nama Belakang	`Tufnel`
Username	`nigel`
Email	`nigel@example.com`

Klik Save.

Daftarkan aplikasi

Mari membuat aplikasi untuk Nigel.

Pilih Publikasikan > Aplikasi.
Klik + Aplikasi.

Masukkan teks berikut di jendela New App:

Di kolom ini	lakukan ini
Name dan Display Name	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 Create.

Dapatkan kunci konsumen dan rahasia konsumen

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

Pastikan halaman nigel_app ditampilkan. Jika tidak, di halaman Apps (Publish > Apps), klik nigel_app.
Pada halaman nigel_app, klik Show di kolom Key dan Secret. Perhatikan bahwa kunci/rahasia ini terkait dengan produk API yang Anda buat sebelumnya.
Pilih dan salin Kunci dan Rahasia. Tempel semuanya 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 terlindungi 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 valid yang dapat memanggil API ini.

Mendapatkan token akses OAuth 2.0

Selanjutnya, Anda akan menggunakan kunci dan rahasia yang disalin dan ditempel ke dalam file teks, lalu ditukarkan 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 kunci dan rahasia 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 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 mendapatkan token akses OAuth 2.0. 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 "flow kondisional" di proxy oauth, yang menyatakan jika URI resource adalah /accesstoken dan kata kerja permintaannya adalah POST, untuk mengeksekusi kebijakan OAuth 2.0 GenerateAccessTokenClient yang menghasilkan token akses? Perintah cURL Anda memenuhi ketentuan tersebut, sehingga kebijakan OAuth 2.0 dijalankan. Klien tersebut memverifikasi kunci konsumen dan rahasia konsumen Anda, lalu menukarnya dengan token OAuth 2.0 yang akan habis 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

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