Menerapkan jenis pemberian kredensial klien

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

Dengan jenis pemberian kredensial klien, aplikasi mengirimkan kredensialnya sendiri (Client ID dan Client Secret) 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 menawarkan deskripsi umum tentang jenis pemberian kredensial klien OAuth 2.0 dan membahas cara menerapkan 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 cloud backend untuk menyimpan dan mengambil data yang digunakan untuk melakukan pekerjaannya, bukan data yang secara khusus dimiliki oleh pengguna akhir. Alur jenis pemberian ini terjadi secara ketat antara aplikasi klien dan server otorisasi. Pengguna akhir tidak berpartisipasi dalam alur jenis pemberian ini.

Peran

Peran menentukan "aktor" yang berpartisipasi dalam alur OAuth. Mari kita telusuri ringkasan singkat peran kredensial klien untuk membantu mengilustrasikan posisi Apigee Edge. Untuk pembahasan lengkap tentang peran OAuth 2.0, lihat spesifikasi IETF OAuth 2.0.

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

Contoh kode

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

Diagram alur

Diagram alur berikut mengilustrasikan 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 terlindungi.


Langkah-langkah dalam alur kredensial klien

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

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

1. Klien meminta token akses

Untuk menerima token akses, klien melakukan POST 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 sebagai string yang dienkode URL base64 di header Authorization. Untuk melakukannya, Anda harus menggunakan alat atau utilitas encoding base64 untuk mengenkode kedua nilai tersebut bersama dengan titik dua yang memisahkannya. Seperti ini: aBase64EncodeFunction(clientidvalue:clientsecret). Jadi, contoh di atas akan dienkode seperti ini:

result = aBase64EncodeFunction(ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI) // Note the colon separating the two values.

Hasil encoding base64 dari 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 dilampirkan untuk memvalidasi kredensial aplikasi. Artinya, kebijakan tersebut 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 kredensialnya valid, Edge akan menampilkan token akses ke klien. Jika tidak, error akan ditampilkan.

4. Klien memanggil API terlindungi

Sekarang, dengan token akses yang valid, klien dapat melakukan panggilan ke API terlindungi. Dalam skenario ini, permintaan dibuat 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 terlindungi di bawah.

Mengonfigurasi alur dan kebijakan

Sebagai server otorisasi, Edge memproses permintaan token akses. Sebagai developer API, Anda harus 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 cara alur proxy API dikonfigurasi adalah dengan menampilkan definisi alur XML. Berikut adalah contoh alur proxy API yang dirancang untuk memproses permintaan token akses. Misalnya, saat permintaan masuk dan akhiran jalur cocok dengan /accesstoken, kebijakan GetAccessToken akan dipicu. Lihat Mengonfigurasi endpoint dan kebijakan OAuth untuk mengetahui ringkasan singkat 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 harus melampirkan kebijakan ke endpoint, sebagai berikut. Lihat Mengonfigurasi endpoint dan kebijakan OAuth untuk mengetahui ringkasan singkat langkah-langkah yang diperlukan untuk menambahkan kebijakan OAuthV2 ke endpoint proxy.

Mendapatkan token akses

Kebijakan ini dilampirkan ke jalur /accesstoken. Kebijakan 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 Authorization dengan client_id + client+secret yang dienkode base64 dan parameter kueri grant_type=client_credentials. Panggilan 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 Anda dengan keamanan OAuth 2.0, Anda harus menambahkan kebijakan OAuthV2 dengan operasi VerifyAccessToken. Kebijakan ini memeriksa apakah permintaan yang masuk memiliki token akses yang valid. Jika tokennya valid, Edge akan memproses permintaan. Jika tidak valid, Edge akan menampilkan error. Untuk langkah-langkah dasarnya, 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 terlindungi

Untuk memanggil API yang dilindungi dengan keamanan OAuth 2.0, Anda harus menampilkan token akses yang valid. Pola yang benar adalah menyertakan token di header Authorization, 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 tambahan

  • 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.