Mengimplementasikan jenis pemberian kredensial klien

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

Dengan jenis pemberian kredensial klien, aplikasi mengirim kredensialnya sendiri (Client ID dan Rahasia Klien) ke endpoint di Apigee yang disiapkan untuk membuat token akses. Jika kredensial valid, Apigee akan menampilkan token akses ke aplikasi klien.

Tentang topik ini

Topik ini memberikan deskripsi umum tentang jenis pemberian kredensial klien OAuth 2.0 dan membahas cara menerapkan alur ini di Apigee.

Kasus penggunaan

Biasanya, jenis hibah ini digunakan saat aplikasi juga merupakan pemilik resource. Misalnya, aplikasi mungkin perlu mengakses layanan penyimpanan berbasis cloud backend untuk menyimpan dan mengambil data yang digunakannya untuk menjalankan pekerjaannya, bukan data yang dimiliki secara khusus oleh pengguna akhir. Alur jenis pemberian ini terjadi hanya antara aplikasi klien dan server otorisasi. Pengguna akhir tidak berpartisipasi dalam alur jenis hibah ini.

Peran

Peran menentukan "aktor" yang berpartisipasi dalam alur OAuth. Mari kita lakukan ringkasan singkat tentang peran kredensial klien untuk membantu menggambarkan kesesuaian Apigee. Untuk pembahasan lengkap tentang peran OAuth 2.0, baca spesifikasi IETF OAuth 2.0.

  • Aplikasi Klien -- Aplikasi yang memerlukan akses ke resource yang dilindungi milik pengguna. Biasanya, dengan alur ini, aplikasi akan berjalan di server, bukan secara lokal di laptop atau perangkat pengguna.
  • Apigee -- Dalam alur ini, Apigee adalah server otorisasi OAuth. Perannya adalah untuk menghasilkan token akses, memvalidasi token akses, dan meneruskan permintaan yang diizinkan untuk resource yang dilindungi ke server resource.
  • Server Resource -- Layanan backend yang menyimpan data yang dilindungi dan perlu izin untuk diakses oleh aplikasi klien. Jika Anda melindungi proxy API yang dihosting di Apigee, maka Apigee juga merupakan server resource.

Contoh kode

Anda dapat menemukan contoh implementasi jenis pemberian kredensial klien yang lengkap dan berfungsi di GitHub. Lihat Referensi tambahan di bawah untuk link ke contoh lainnya.

Diagram alir

Diagram alur berikut menggambarkan alur kredensial klien dengan Apigee yang berfungsi sebagai server otorisasi. Secara umum, Apigee juga merupakan server resource dalam alur ini -- yaitu, proxy API merupakan resource yang dilindungi.

Alur kredensial klien.

Langkah-langkah dalam alur kredensial klien

Berikut adalah ringkasan langkah-langkah yang diperlukan untuk menerapkan jenis pemberian kode kredensial klien dengan Apigee berfungsi sebagai server otorisasi. Ingat, dengan alur ini, aplikasi klien hanya menyajikan client ID dan rahasia klien-nya, dan jika valid, Apigee akan menampilkan token akses.

Prasyarat: Aplikasi klien harus terdaftar di Apigee untuk mendapatkan client ID dan kunci rahasia klien. Lihat Mendaftarkan aplikasi klien untuk mengetahui detailnya.

1. Klien meminta token akses

Untuk menerima token akses, klien MEMPOSTING panggilan API ke Apigee dengan nilai untuk client ID dan rahasia klien yang diperoleh dari aplikasi developer terdaftar (dalam contoh ini, nilai dienkode Base64 dan diteruskan di header Authorization. Selain itu, parameter grant_type=client_credentials harus diteruskan sebagai parameter kueri. (Namun, Anda dapat mengonfigurasi kebijakan OAuthV2 untuk menerima parameter ini di header atau isi permintaan -- lihat kebijakan OAuthV2 untuk mengetahui detailnya).

Contoh:

curl -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" \
  -X POST "https://apitest.acme.com/oauth/token" \
  -d "grant_type=client_credentials"

Lihat juga Menggunakan jenis pemberian kredensial klien.

2. Apigee memvalidasi kredensial

Perhatikan bahwa panggilan API dikirim ke endpoint /oauth/token. Endpoint ini memiliki kebijakan terlampir yang memvalidasi kredensial aplikasi. Artinya, kebijakan akan membandingkan kunci yang dikirimkan dengan kunci yang dibuat Apigee saat aplikasi didaftarkan. Jika Anda ingin mempelajari lebih lanjut endpoint OAuth di Apigee, lihat Mengonfigurasi endpoint dan kebijakan OAuth.

3. Apigee menampilkan respons

Jika kredensial tidak bermasalah, Apigee akan menampilkan token akses ke klien. Jika tidak, error akan ditampilkan.

4. Klien memanggil API yang dilindungi

Sekarang, dengan token akses yang valid, klien dapat melakukan panggilan ke API yang dilindungi. Dalam skenario ini, permintaan diajukan ke Apigee (proxy), dan Apigee bertanggung jawab untuk memvalidasi token akses sebelum meneruskan panggilan API ke server resource target. Untuk contohnya, lihat Memanggil API yang dilindungi di bawah.

Mengonfigurasi flow dan kebijakan

Sebagai server otorisasi, Apigee memproses permintaan token akses. Sebagai developer API, Anda perlu membuat proxy dengan alur kustom untuk menangani permintaan token serta menambahkan dan mengonfigurasi kebijakan OAuthV2. Bagian ini menjelaskan cara mengonfigurasi endpoint tersebut.

Konfigurasi alur kustom

Cara termudah untuk menunjukkan konfigurasi alur proxy API adalah dengan menampilkan definisi alur XML. Berikut adalah contoh alur proxy API yang dirancang untuk memproses permintaan token akses. Misalnya, jika ada permintaan masuk dan akhiran jalur cocok dengan /oauth/token, kebijakan GetAccessToken akan dipicu. Lihat Mengonfigurasi endpoint dan kebijakan OAuth untuk mengetahui ringkasan langkah-langkah yang diperlukan untuk membuat alur kustom seperti ini.

<Flows>
  <Flow name="GetAccessToken">
         <!-- This policy flow is triggered when the URI path suffix
         matches /oauth/token. Publish this URL to app developers
         to use when obtaining an access token using an auth code
         -->
    <Condition>proxy.pathsuffix == "/oauth/token"</Condition>
    <Request>
        <Step><Name>GetAccessToken</Name></Step>
    </Request>
  </Flow>
</Flows>

Mengonfigurasi alur dengan kebijakan

Anda perlu melampirkan kebijakan ke endpoint, seperti berikut. Lihat Mengonfigurasi endpoint dan kebijakan OAuth guna mendapatkan ringkasan langkah-langkah yang diperlukan untuk menambahkan kebijakan OAuthV2 ke endpoint proxy.

Dapatkan token akses

Kebijakan ini disertakan ke jalur /oauth/token. Versi ini menggunakan kebijakan OAuthV2 dengan operasi GenerateAccessToken yang ditentukan.

<OAuthV2 name="GetAccessToken">
  <Operation>GenerateAccessToken</Operation>
  <ExpiresIn>3600000</ExpiresIn>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GenerateResponse/>
</OAuthV2>

Panggilan API untuk mendapatkan token akses adalah POST dan mencakup header Otorisasi dengan client_id + client_secret berenkode Base64 dan parameter kueri grant_type=client_credentials. Class ini juga dapat menyertakan parameter opsional untuk cakupan dan status. Contoh:

curl -i \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials' \
  -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVgT1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ'

Melampirkan kebijakan verifikasi token akses

Untuk melindungi API dengan keamanan OAuth 2.0, Anda perlu menambahkan kebijakan OAuthV2 dengan operasi VerifyAccessToken. Kebijakan ini memeriksa apakah permintaan masuk memiliki token akses yang valid. Jika token valid, Apigee akan memproses permintaan tersebut. Jika tidak valid, Apigee akan menampilkan error. Untuk mengetahui langkah-langkah dasar, lihat Memverifikasi token akses. 

<OAuthV2 async="false" continueOnError="false" enabled="true" name="VerifyAccessToken">
    <DisplayName>VerifyAccessToken</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <SupportedGrantTypes/>
    <GenerateResponse enabled="true"/>
    <Tokens/>
</OAuthV2>

Memanggil API yang dilindungi

Untuk memanggil API yang dilindungi dengan keamanan OAuth 2.0, Anda harus memberikan token akses yang valid. Pola yang benar adalah menyertakan token di header Otorisasi, sebagai berikut: Perhatikan bahwa token akses juga disebut sebagai "token pembawa". 

$ curl -H "Authorization: Bearer UAj2yiGAcMZGxfN2DhcUbl9v8WsR" \
  http://myorg-test.apigee.net/v0/weather/forecastrss?w=12797282

Lihat juga Mengirim token akses.

Referensi lain

  • Apigee menawarkan pelatihan online untuk developer API, termasuk kursus tentang keamanan API, yang mencakup OAuth.
  • Kebijakan OAuthV2 -- Memiliki banyak contoh yang menunjukkan cara membuat permintaan ke server otorisasi dan cara mengonfigurasi kebijakan OAuthV2.