Halaman ini diterjemahkan oleh Cloud Translation API.

Mengimplementasikan jenis pemberian kredensial klien

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

Dengan jenis pemberian kredensial klien, aplikasi mengirim kredensialnya sendiri (Client ID dan Rahasia Klien) ke endpoint di Apigee Edge yang disiapkan untuk membuat token akses. Jika kredensialnya valid, Edge 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 Edge.

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 Edge. 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 Edge -- Dalam alur ini, Apigee Edge 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 Edge, maka Apigee Edge 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 Edge yang berfungsi sebagai server otorisasi. Secara umum, Edge juga merupakan server resource dalam alur ini -- yaitu, proxy API adalah resource yang dilindungi.

Langkah-langkah dalam alur kredensial klien

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

Prasyarat: Aplikasi klien harus terdaftar di Apigee Edge 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 Edge dengan nilai untuk client ID dan rahasia klien yang diperoleh dari aplikasi developer terdaftar. 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 -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials&client_id=ns4fQc14Zg4hKFCNaSzArVuwszX95X&client_secret=ZIjFyTsNgQNyxI'

Catatan: Meskipun Anda dapat meneruskan nilai client_id dan client_secret sebagai parameter kueri seperti yang ditunjukkan di atas, sebaiknya teruskan nilai tersebut sebagai string berenkode URL base64 di header Authorization. Untuk melakukannya, Anda perlu menggunakan utilitas atau alat encoding base64 untuk mengenkode kedua nilai bersama dengan titik dua yang memisahkannya. Seperti ini: aBase64EncodeFunction(clientidvalue:clientsecret). Jadi, contoh di atas akan dienkode seperti ini:

result = aBase64EncodeFunction(ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI) // Catat titik dua yang memisahkan kedua nilai tersebut.

Hasil encoding base64 string di atas adalah: bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==

Kemudian, buat permintaan token seperti ini:

$ 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 bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg=='

2. Edge memvalidasi kredensial

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

3. Edge menampilkan respons

Jika kredensial tidak bermasalah, Edge 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 Edge (proxy), dan Edge 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, Edge 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 /accesstoken, 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/accesstoken. Publish this URL to app developers 
         to use when obtaining an access token using an auth code   
         -->
    <Condition>proxy.pathsuffix == "/oauth/accesstoken"</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 /accesstoken. 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 menyertakan header Otorisasi dengan client_id + client+secret berenkode base64 dan parameter kueri generate_type=client_credentials. 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, Edge akan memproses permintaan tersebut. Jika tidak valid, Edge 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 lainnya

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.