OAuth

Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi Apigee X.
info

OAuth telah muncul sebagai protokol otorisasi terdepan untuk API. Versi OAuth yang dibahas secara mendetail dalam topik ini dijelaskan dalam Spesifikasi OAuth 2.0.

OAuth adalah protokol yang memungkinkan pengguna akhir aplikasi memberi otorisasi kepada aplikasi untuk bertindak atas nama mereka. Aplikasi melakukannya dengan mendapatkan token akses dari penyedia API. Penyedia API mengautentikasi kredensial pengguna akhir aplikasi, memastikan bahwa pengguna telah memberi otorisasi pada aplikasi, lalu mengeluarkan token akses ke aplikasi. Ketika aplikasi menggunakan API yang dilindungi, Apigee Edge akan memeriksa token akses tersebut untuk memastikan bahwa token tersebut valid dan belum habis masa berlakunya. Sebagai penyedia API, Anda harus mengekspos endpoint yang memungkinkan aplikasi mendapatkan token akses.

Untuk memudahkan Anda dalam mulai menggunakan OAuth, Apigee Edge memungkinkan Anda mengonfigurasi dan menerapkan OAuth menggunakan kebijakan, tanpa mengharuskan Anda menulis kode apa pun. Dalam topik ini, Anda akan mempelajari cara melindungi API, cara mendapatkan token akses, dan cara menggunakan token akses tersebut untuk mengakses API yang dilindungi.

Konfigurasi OAuth default untuk organisasi Anda

Untuk memudahkan, semua organisasi di Apigee Edge telah dikonfigurasi sebelumnya dengan serangkaian endpoint OAuth 2.0 yang menerapkan jenis pemberian kredensial klien. Jenis pemberian kredensial klien menentukan prosedur penerbitan token akses dengan imbalan kredensial aplikasi. Kredensial aplikasi ini hanyalah pasangan kunci dan rahasia konsumen yang dikeluarkan oleh Apigee Edge untuk setiap aplikasi yang terdaftar dalam suatu organisasi. 'Kredensial klien' mengacu pada pasangan kunci dan rahasia konsumen itu sendiri.

Untuk mempelajari lebih lanjut cara menerbitkan kredensial ke aplikasi menggunakan Edge Developer Services, lihat Mendaftarkan aplikasi dan mengelola kunci.

Karena alasan ini, cukup 'meningkatkan' skema keamanan API Anda dari validasi kunci API ke kredensial klien OAuth. Kedua skema menggunakan kunci dan rahasia konsumen yang sama untuk memvalidasi aplikasi klien. Perbedaannya adalah kredensial klien memberikan lapisan kontrol tambahan, karena Anda dapat mencabut token akses dengan mudah saat diperlukan, tanpa harus mencabut kunci konsumen aplikasi. Agar dapat menggunakan endpoint OAuth default, Anda dapat menggunakan kunci dan rahasia konsumen apa pun yang dibuat untuk aplikasi di organisasi Anda guna mengambil token akses dari endpoint token. (Anda bahkan dapat mengaktifkan kredensial klien untuk aplikasi yang sudah memiliki kunci dan rahasia pengguna.)

Spesifikasi lengkap untuk pemberian kredensial klien dapat ditemukan di Spesifikasi OAuth 2.0.

Lindungi API Anda dengan kebijakan

Sebelum dapat menggunakan token akses, Anda harus mengonfigurasi API untuk memvalidasi token akses OAuth saat runtime. Untuk melakukannya, konfigurasikan proxy API untuk validate token akses. Artinya, setiap kali aplikasi membuat permintaan untuk menggunakan salah satu API Anda, aplikasi tersebut harus memberikan token akses yang valid bersama dengan permintaan API. Apigee Edge menangani kompleksitas di balik pembuatan, penyimpanan, dan validasi token akses yang ditampilkan.

Anda dapat dengan mudah menambahkan verifikasi OAuth ke API saat membuat proxy API baru. Ketika membuat proxy API baru, Anda dapat Menambahkan Fitur. Seperti yang ditunjukkan di bawah ini, Anda dapat menambahkan verifikasi token akses OAuth 2.0 dengan memilih tombol pilihan di sebelah Secure with OAuth v2.0 Access Tokens. Jika Anda memilih opsi ini, dua kebijakan akan dikaitkan ke proxy API yang baru dibuat, satu untuk memverifikasi token akses dan satu kebijakan untuk menghapus token akses setelah diverifikasi.

Selain itu, jika Anda memilih opsi Secure with OAuth v2.0 Access Tokens, kotak centang Publish API Product dapat dicentang dan otomatis dipilih. Centang ini jika Anda ingin otomatis membuat produk saat membuat proxy API baru. Produk yang dibuat secara otomatis akan dibuat dengan pengaitan ke proxy API baru. Jika Anda sudah memiliki produk yang ingin dikaitkan dengan API baru ini, pastikan Anda menghapus centang pada kotak ini sehingga Anda tidak membuat produk yang tidak diperlukan. Untuk informasi tentang produk, lihat Apa yang dimaksud dengan produk API?

Jika Anda perlu mengaktifkan verifikasi token akses untuk proxy API yang sudah ada, yang perlu Anda lakukan hanyalah melampirkan kebijakan jenis OAuthV2 ke API yang ingin Anda lindungi. Kebijakan OAuthV2 berfungsi dengan menentukan operasi. Jika ingin memvalidasi token akses, tentukan operasi yang disebut VerifyAccessToken. (Jenis operasi lain yang didukung oleh jenis kebijakan OAuthV2 adalah GenerateAccessToken dan GenerateRefreshToken. Anda akan mempelajari operasi tersebut saat menyiapkan endpoint OAuth.)

Kebijakan VerifyOAuthTokens dari jenis OAuthV2

Contoh kebijakan untuk memvalidasi token akses terlihat seperti berikut. (Setelannya dijelaskan dalam tabel di bawah.)

<OAuthV2 name="VerifyOAuthTokens"> 
  <Operation>VerifyAccessToken</Operation> 
</OAuthV2>

Setelan kebijakan

Nama Deskripsi Default Wajib diisi?
OAuthV2 Jenis kebijakan
name Nama kebijakan, yang dirujuk dalam konfigurasi Endpoint proxy API. T/A Ya
Operation Operasi yang akan dijalankan oleh kebijakan OAuthV2. Dengan menentukan VerifyAccessToken, Anda mengonfigurasi kebijakan untuk memeriksa permintaan token akses, dan memverifikasi bahwa token akses valid, belum habis masa berlakunya, dan disetujui untuk menggunakan resource API (URI) yang diminta. (Untuk melakukan pemeriksaan ini, kebijakan membaca produk API yang disetujui untuk digunakan oleh aplikasi.) T/A Ya

Untuk membuat kebijakan ini di UI pengelolaan, buka APIs > API Proxy.

Dari daftar proxy API, pilih weatherapi.

Dari Overview untuk weatherapi, pilih tampilan Develop.

Dari menu drop-down, pilih Kebijakan Baru > OAuth v2.0

Setelah Anda memilih kebijakan OAuth v2.0, menu konfigurasi New Policy akan ditampilkan.

Beri nama yang deskriptif pada kebijakan Anda, dan pastikan untuk memilih Attach Policy, Flow PreFlow, dan Request sebagai setelan lampiran kebijakan.

Pilih Add dan kebijakan akan dibuat dan dilampirkan ke PreFlow permintaan weatherapi.

Setelah Anda menambahkan kebijakan, konfigurasi PreFlow permintaan di bawah akan ditampilkan di panel Designer.

Jika Anda bekerja secara lokal di editor teks atau IDE, lampirkan Kebijakan ke PraFlow permintaan proxy API yang ingin dilindungi:

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthTokens</Name></Step>
  </Request>
</PreFlow>

Dengan melampirkan kebijakan ke PreFlow permintaan, Anda memastikan bahwa kebijakan selalu diterapkan pada semua pesan permintaan.

Anda kini telah mengamankan API dengan kredensial klien OAuth 2.0. Langkah berikutnya adalah mempelajari cara mendapatkan token akses, dan menggunakannya untuk mengakses API yang aman.

Menggunakan token akses untuk mengakses resource yang dilindungi

Setelah weatherapi diamankan dengan OAuth 2.0, aplikasi harus memberikan token akses untuk menggunakan API tersebut. Untuk mengakses resource yang dilindungi, aplikasi akan menyajikan token akses dalam permintaan sebagai header HTTP"Authorization" sebagai berikut:

$ curl -H "Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

Karena API menyertakan kebijakan OAuthV2, Apigee Edge akan memverifikasi bahwa token akses yang ditampilkan valid, lalu memberikan akses ke API, yang menampilkan laporan cuaca ke aplikasi yang membuat permintaan tersebut.

Namun, bagaimana cara aplikasi mendapatkan token akses? Kita akan membahasnya di bagian berikutnya.

Cara menukar kredensial klien dengan token akses

Aplikasi mendapatkan token akses dengan menampilkan pasangan kunci/rahasia konsumennya ke endpoint token. Endpoint token dikonfigurasi dalam proxy API yang disebut oauth. Jadi, aplikasi perlu memanggil API yang diekspos oleh proxy API oauth untuk mendapatkan token akses. Setelah memiliki token akses, aplikasi dapat memanggil weatherapi berulang kali, hingga masa berlaku token akses berakhir, atau token akses dicabut.

Sekarang Anda perlu mempertimbangkan diri Anda sebagai pengembang aplikasi. Anda ingin memanggil weatherapi sehingga perlu mendapatkan token akses untuk aplikasi. Hal pertama yang perlu Anda lakukan adalah mendapatkan pasangan kunci dan rahasia pengguna (yang juga dikenal sebagai kunci API atau kunci aplikasi).

Anda bisa mendapatkan kunci dan rahasia konsumen dengan mendaftarkan aplikasi dalam organisasi Anda di Apigee Edge.

Anda dapat melihat semua aplikasi di organisasi Anda di UI pengelolaan Apigee Edge.

Daftar aplikasi yang terdaftar di organisasi Anda akan ditampilkan.

(Jika tidak ada aplikasi yang ditampilkan, Anda dapat mempelajari cara mendaftarkan aplikasi dalam topik Mendaftarkan aplikasi dan mengelola kunci API).

Pilih aplikasi dari daftar untuk melihat profil mendetail.

Dalam tampilan detail aplikasi yang dipilih, perhatikan kolom untuk Consumer Key dan Consumer Secret. Kedua nilai tersebut adalah kredensial klien yang akan Anda gunakan untuk mendapatkan token akses OAuth.

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps \
-u myname:mypass 

Panggilan ini menampilkan daftar aplikasi berdasarkan ID aplikasi.

[ "da496fae-2a04-4a5c-b2d0-709278a6f9db", "50e3e831-175b-4a05-8fb6-05a54701af6e" ]

Anda dapat mengambil profil aplikasi dengan melakukan panggilan GET sederhana di ID aplikasi:

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/{app_id} \
-u myname:mypass 

Contoh:

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/da496fae-2a04-4a5c-b2d0-709278a6f9db \
-u myname:mypass 

Panggilan API menampilkan profil aplikasi yang Anda tentukan. Misalnya, profil aplikasi untuk weatherapp memiliki representasi JSON berikut:

{
  "accessType" : "read",
  "apiProducts" : [ ],
  "appFamily" : "default",
  "appId" : "da496fae-2a04-4a5c-b2d0-709278a6f9db",
  "attributes" : [ ],
  "callbackUrl" : "http://weatherapp.com",
  "createdAt" : 1380290158713,
  "createdBy" : "noreply_admin@apigee.com",
  "credentials" : [ {
    "apiProducts" : [ {
      "apiproduct" : "PremiumWeatherAPI",
      "status" : "approved"
    } ],
    "attributes" : [ ],
    "consumerKey" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
    "consumerSecret" : "hAr4Gn0gA9vAyvI4",
    "expiresAt" : -1,
    "issuedAt" : 1380290161417,
    "scopes" : [ ],
    "status" : "approved"
  } ],
  "developerId" : "5w95xGkpnjzJDBT4",
  "lastModifiedAt" : 1380290158713,
  "lastModifiedBy" : "noreply_admin@apigee.com",
  "name" : "weatherapp",
  "scopes" : [ ],
  "status" : "approved"
}

Catat nilai untuk consumerKey dan consumerSecret. Anda menggunakan kredensial ini untuk mendapatkan token akses dengan menampilkannya sebagai kredensial Autentikasi Dasar dalam permintaan HTTP, seperti yang ditunjukkan di bawah ini. Jenis pemberian ditampilkan sebagai parameter kueri ke permintaan. (Pastikan untuk mengubah nilai variabel {org_name} untuk mencerminkan nama organisasi Anda di Apigee Edge.)

Membuat permintaan untuk mendapatkan token akses

Dalam permintaan berikut, ganti nilai consumerKey Anda dengan client_id. Ganti nilai consumerSecret yang terkait dengan client_secret.

$ curl https://{org_name}-test.apigee.net/oauth/client_credential/accesstoken?grant_type=client_credentials -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K&client_secret=hAr4Gn0gA9vAyvI4'

Layanan API memverifikasi kunci dan rahasia konsumen, lalu membuat respons yang berisi token akses untuk aplikasi ini:

{
  "issued_at" : "1380892555397",
  "application_name" : "957aa73f-25c2-4ead-8021-adc01f0d2c6b",
  "scope" : "",
  "status" : "approved",
  "api_product_list" : "[oauth-test]",
  "expires_in" : "3599",
  "developer.email" : "tesla@weathersample.com",
  "organization_id" : "0",
  "client_id" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
  "access_token" : "ylSkZIjbdWybfs4fUQe9BqP0LH5Z",
  "organization_name" : "rqa",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

Perhatikan nilai access_token dalam respons di atas. Ini adalah token akses yang akan digunakan aplikasi untuk mendapatkan akses runtime ke resource yang dilindungi. Token akses untuk aplikasi ini adalah ylSkZIjbdWybfs4fUQe9BqP0LH5Z.

Anda kini memiliki token akses valid, ylSkZIjbdWybfs4fUQe9BqP0LH5Z, yang dapat digunakan untuk mengakses API yang dilindungi.

Menggunakan konfigurasi OAuth default

Setiap organisasi (bahkan organisasi uji coba gratis) di Apigee Edge disediakan dengan endpoint token OAuth. Endpoint telah dikonfigurasi sebelumnya dengan kebijakan dalam proxy API yang disebut oauth. Anda dapat mulai menggunakan endpoint token segera setelah membuat akun di Apigee Edge.

Endpoint OAuth default mengekspos URI endpoint berikut:

/oauth/client_credential/accesstoken

Publikasikan URI ini kepada developer yang perlu mendapatkan token akses. Developer aplikasi mengonfigurasi aplikasi mereka untuk memanggil endpoint ini, menampilkan pasangan kunci dan rahasia konsumen untuk memperoleh token akses.

Endpoint token kredensial klien default diekspos melalui jaringan di URL berikut:

https://{org_name}-{env_name}.apigee.net/oauth/client_credential/accesstoken

Misalnya, jika nama organisasi Anda adalah "apimakers", URL-nya adalah:

https://apimakers-test.apigee.net/oauth/client_credential/accesstoken

Ini adalah URL yang dipanggil developer untuk mendapatkan token akses.

Konfigurasi 3-legged OAuth

Konfigurasi OAuth bercabang tiga (kode otorisasi, jenis pemberian sandi, dan implisit) mengharuskan Anda, sebagai penyedia API, untuk mengautentikasi pengguna akhir aplikasi. Karena setiap organisasi mengautentikasi pengguna dengan cara yang berbeda, beberapa kode atau penyesuaian kebijakan diperlukan untuk mengintegrasikan OAuth dengan toko pengguna Anda. Misalnya, semua pengguna Anda mungkin disimpan di Active Directory, di LDAP, atau beberapa toko pengguna lainnya. Untuk mengaktifkan dan menjalankan OAuth bercabang tiga, Anda perlu mengintegrasikan pemeriksaan terhadap toko pengguna ini ke dalam alur OAuth secara keseluruhan.

OAuth 1.0a

Untuk mengetahui detail tentang kebijakan OAuth 1.0a, lihat kebijakan OAuth v1.0a.

Mendapatkan bantuan

Untuk mendapatkan bantuan, lihat Dukungan Pelanggan Apigee.