Halaman ini diterjemahkan oleh Cloud Translation API.

Menerapkan jenis pemberian kredensial klien

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

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

Tentang topik ini

Topik ini berisi deskripsi umum tentang jenis pemberian kredensial klien OAuth 2.0 dan membahas cara mengimplementasikan alur ini di Apigee Edge.

Kasus penggunaan

Biasanya, jenis pemberian ini digunakan saat aplikasi juga merupakan pemilik resource. Misalnya, aplikasi mungkin perlu mengakses layanan penyimpanan berbasis {i> cloud<i} backend untuk menyimpan dan mengambil data yang yang digunakannya untuk melakukan pekerjaannya, bukan data yang secara khusus dimiliki oleh pengguna akhir. Jenis pemberian ini alur 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 gambaran singkat tentang peran kredensial klien untuk membantu menggambarkan kesesuaian Apigee Edge. Untuk diskusi tentang peran OAuth 2.0, lihat spesifikasi IETF OAuth 2.0.

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

Contoh kode

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

Diagram alir

Diagram alur berikut mengilustrasikan alur kredensial klien dengan Apigee Edge yang berfungsi sebagai server otorisasi. Secara umum, Edge juga merupakan server sumber daya 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 di mana Apigee Edge berfungsi sebagai server otorisasi. Ingat, dengan alur ini, aplikasi klien hanya menyajikan client ID dan rahasia klien, dan jika valid, Apigee Edge menampilkan token masing-masing.

Prasyarat: Aplikasi klien harus terdaftar di Apigee Edge untuk mendapatkan {i>client ID<i} dan kunci rahasia klien. Lihat Mendaftarkan aplikasi klien untuk spesifikasi pendukung.

1. Klien meminta token akses

Untuk menerima token akses, klien MEMPOSTING panggilan API ke Edge dengan nilai untuk client ID rahasia klien yang diperoleh dari aplikasi pengembang terdaftar. Selain itu, parameter hibah_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 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 kueri parameter seperti yang ditunjukkan di atas, sebaiknya teruskan sebagai string berenkode URL base64 di header Otorisasi. Untuk melakukannya, Anda perlu menggunakan utilitas atau alat encoding base64 untuk mengenkode kedua nilai itu bersama-sama dengan titik dua yang memisahkannya. Seperti ini: aBase64EncodeFunction(clientidvalue:clientsecret). Jadi, contoh di atas akan dienkode seperti ini:

result = aBase64EncodeFunction(ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI) // Perhatikan 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 yang melekat padanya yang memvalidasi kredensial aplikasi. Artinya, kebijakan tersebut membandingkan kunci dengan kunci yang dibuat Apigee Edge saat aplikasi didaftarkan. Jika Anda ingin Pelajari endpoint OAuth di Edge lebih lanjut, lihat Mengonfigurasi OAuth endpoint, dan kebijakan.

3. Edge menampilkan respons

Jika kredensial tidak bermasalah, Edge akan menampilkan token akses ke klien. Jika tidak, pesan {i>error<i} dikembalikan.

4. Klien memanggil metode API yang dilindungi

Sekarang, dengan token akses yang valid, klien dapat melakukan panggilan ke API yang dilindungi. Di sini ini, permintaan dibuat ke Apigee Edge (proxy), dan Edge bertanggung jawab untuk memvalidasi token akses sebelum meneruskan panggilan API ke server resource target. Sebagai contoh, lihat Memanggil API yang dilindungi di bawah.

Mengonfigurasi alur dan kebijakan

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

Konfigurasi alur kustom

Cara termudah untuk menunjukkan bagaimana alur proxy API dikonfigurasi adalah dengan menampilkan alur XML definisi. Berikut adalah contoh alur proxy API yang didesain untuk memproses permintaan token akses. Sebagai misalnya, ketika sebuah permintaan masuk dan akhiran jalur cocok dengan /accesstoken, maka kebijakan akan dipicu. Lihat Mengonfigurasi OAuth endpoint dan kebijakan untuk mendapatkan ringkasan singkat tentang 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, sebagai berikut. Lihat Mengonfigurasi OAuth endpoint dan kebijakan guna mendapatkan ringkasan singkat tentang langkah-langkah yang diperlukan untuk menambahkan kebijakan OAuthV2 ke endpoint proxy.

Mendapatkan token akses

Kebijakan ini disertakan pada jalur /accesstoken. Protokol ini menggunakan OAuthV2 kebijakan 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 berenkode base64 + client+secret dan parameter kueri grant_type=client_credentials. Fungsi 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'

Lampiran kebijakan token verifikasi akses

Untuk melindungi API Anda 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. Jika tidak valid, Edge akan menampilkan error. Sebagai 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 akses yang valid sebelumnya yang benar. Pola yang benar adalah menyertakan token di header Authorization, sebagai berikut: Catatan token akses juga disebut sebagai "{i>bearer token<i}".

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

Lihat juga Mengirim akses token tersebut.

Referensi lainnya

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