Halaman ini diterjemahkan oleh Cloud Translation API.

Menerapkan jenis pemberian kode otorisasi

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Baca dokumentasi Apigee Edge.

Kode otorisasi adalah salah satu jenis pemberian OAuth 2.0 yang paling umum digunakan. Alur kode otorisasi adalah konfigurasi three-legged OAuth. Dalam konfigurasi ini, pengguna mengautentikasi dirinya sendiri dengan server resource dan memberikan izin kepada aplikasi untuk mengakses resource yang dilindungi tanpa mengirimkan nama pengguna/sandi ke aplikasi klien.

Tentang topik ini

Topik ini memberikan deskripsi umum dan ringkasan alur jenis pemberian otorisasi OAuth 2.0 serta membahas cara menerapkan alur ini di Apigee.

Video

Tonton video singkat untuk mempelajari cara menggunakan jenis pemberian otorisasi OAuth 2.0 untuk mengamankan API Anda.

Kasus penggunaan

Jenis hibah ini ditujukan untuk aplikasi yang ditulis oleh developer pihak ketiga yang tidak memiliki hubungan bisnis tepercaya dengan penyedia API. Misalnya, developer yang mendaftar ke program API publik umumnya tidak boleh dipercaya. Dengan jenis pemberian ini, kredensial pengguna di server resource tidak pernah dibagikan ke aplikasi.

Contoh kode

Anda dapat menemukan contoh implementasi lengkap dan berfungsi untuk jenis pemberian kode otorisasi di Apigee dalam repo api-platform-samples di GitHub. Lihat sampel oauth-advanced di direktori api-platform-samples/sample-proxies. Lihat file README untuk detail tentang sampel.

Diagram alir

Diagram alur berikut mengilustrasikan alur OAuth kode otorisasi dengan Apigee yang berfungsi sebagai server otorisasi.

Alur OAuth kode otorisasi.

Langkah-langkah dalam alur kode otorisasi

Berikut adalah ringkasan langkah-langkah yang diperlukan untuk menerapkan jenis pemberian kode otorisasi di mana Apigee berfungsi sebagai server otorisasi. Ingat, kunci dari alur ini adalah klien tidak pernah bisa melihat kredensial pengguna di server resource.

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

1. Pengguna memulai alur

Saat perlu mengakses resource yang dilindungi pengguna dari server resource (misalnya, daftar kontak di situs media sosial), aplikasi akan mengirimkan panggilan API ke Apigee, yang memvalidasi ID klien dan, jika valid, mengalihkan browser pengguna ke halaman login tempat pengguna memasukkan kredensialnya. Panggilan API menyertakan informasi yang diperoleh aplikasi klien saat didaftarkan: client ID dan URI pengalihan.

2. Pengguna memasukkan kredensial

Pengguna kini akan melihat halaman login yang meminta mereka memasukkan kredensial login. Jika login berhasil, kita lanjutkan ke langkah berikutnya.

Halaman login Apigee dengan kolom Alamat email dan Sandi.

3. Pengguna memberikan izin

Pada langkah ini, pengguna memberikan izin kepada aplikasi untuk mengakses resource mereka. Formulir izin biasanya mencakup pemilihan cakupan, yang memungkinkan pengguna memilih tindakan yang diizinkan aplikasi di server resource. Misalnya, pengguna dapat memberikan izin hanya baca, atau izin bagi aplikasi untuk mengupdate resource.

Halaman izin tempat aplikasi contoh meminta untuk Memesan dengan tombol Izinkan dan Tolak.

4. Aplikasi login mengirimkan permintaan Apigee

Jika login dan izin berhasil, aplikasi login akan MEMPOSTING data ke endpoint /Authorizationcode Apigee. Data tersebut mencakup URI pengalihan, client ID, cakupan, informasi khusus pengguna yang ingin disertakan, dan indikasi bahwa login berhasil.

5. Apigee menghasilkan kode otorisasi

Saat Apigee menerima permintaan GET dari aplikasi login di endpoint /Authorizationcode, dua hal akan terjadi. Pertama, Apigee menentukan bahwa login berhasil (dengan memeriksa status HTTP atau cara lainnya). Selanjutnya, Apigee akan memeriksa untuk memastikan bahwa URI pengalihan yang dikirim dari aplikasi login cocok dengan URI pengalihan yang ditentukan saat aplikasi didaftarkan ke Apigee. Jika semuanya baik-baik saja, Apigee akan membuat kode otorisasi. Contoh:

http://myorg-test.apigee.net/oauth/authorizationcode?client_id={consumer_key}&response_type=code&redirect_uri={redirect_uri}&scope=scope1%20scope2&state={some_string}

6. Apigee mengirimkan kode otorisasi kembali ke klien

Apigee mengirimkan pengalihan 302 dengan kode autentikasi yang dilampirkan sebagai parameter kueri ke klien.

7. Klien mengambil kode otorisasi dan meminta kode akses dari Apigee

Sekarang dengan kode autentikasi yang valid, klien dapat meminta token akses dari Apigee. Hal ini dilakukan dengan memposting client ID dan kunci rahasia klien (diperoleh saat aplikasi terdaftar di Apigee), jenis pemberian, dan cakupan. Dengan menyertakan client ID dan kunci rahasia, Apigee dapat memverifikasi bahwa aplikasi klien tersebut adalah aplikasi yang terdaftar. Contoh:

$ curl https://{org_name}-test.apigee.net/my_oauth_proxy/accesstoken?code=Xyz123&grant_type=authorization_code -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpKNhGar6K&client_secret=hAr4GngA9vAyvI4'

8. Klien menerima token akses

Jika semuanya berhasil, Apigee akan menampilkan token akses ke klien. Token akses memiliki masa berlaku, dan hanya valid untuk cakupan yang ditentukan oleh pengguna saat mereka memberikan izin kepada aplikasi untuk mengakses resource mereka.

9. Klien memanggil API yang dilindungi

Kini, dengan kode akses yang valid, klien dapat melakukan panggilan ke API yang dilindungi. Dalam skenario ini, permintaan dibuat ke Apigee (proxy), dan Apigee bertanggung jawab memvalidasi token akses sebelum meneruskan panggilan API ke server resource target. Token akses diteruskan di header Otorisasi. Contoh:

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

Mengonfigurasi alur dan kebijakan

Sebagai server otorisasi, Apigee perlu memproses sejumlah permintaan OAuth: untuk token akses, kode autentikasi, token refresh, pengalihan halaman login, dll. Ada dua langkah mendasar untuk mengonfigurasi endpoint ini:

Membuat flow kustom
Menambahkan dan mengonfigurasi kebijakan OAuthV2

Konfigurasi flow kustom

Biasanya Anda mengonfigurasi alur jenis pemberian izin ini sehingga setiap langkah atau segmen alur ditentukan oleh flow di proxy Apigee. Setiap alur memiliki endpoint dan kebijakan yang melakukan tugas khusus OAuth yang diperlukan, seperti membuat kode otorisasi atau token akses. Misalnya, seperti yang ditunjukkan pada XML di bawah, endpoint /oauth/authorizationcode memiliki kebijakan terkait yang disebut GenerateAuthCode (yang merupakan kebijakan OAuthV2 dengan operasi GenerateAuthorizationCode yang ditentukan).

Cara termudah untuk menampilkan konfigurasi flow adalah dengan contoh XML. Lihat komentar inline untuk mengetahui informasi tentang setiap alur. Ini adalah contohnya -- nama alur dan jalur dapat dikonfigurasi sesuai keinginan Anda. Lihat juga Mengonfigurasi endpoint dan kebijakan OAuth untuk ringkasan langkah-langkah yang diperlukan untuk membuat alur kustom seperti ini.

Lihat juga contoh implementasi di GitHub.

<Flows>
  <Flow name="RedirectToLoginApp">
         <!-- 
         Publish this URI to developers to use for their 'login' link 
         -->
    <Condition>proxy.pathsuffix == "/oauth/authorize"</Condition>
    <Request>
        <Step><Name>RedirectToLoginPage</Name></Step>
    </Request>
  </Flow>
  <Flow name="GetAuthCode">
         <!-- 
         Call this URL from your Login app after you authenticate the user.
         The policy will automatically return the auth code in the response to the 
         redirect_uri registered by the calling app 
         -->
    <Condition>proxy.pathsuffix == "/oauth/authorizationcode"</Condition>
    <Request>
        <Step><Name>GenerateAuthCode</Name></Step>
    </Request>
  </Flow>
  <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>GenerateAccessToken</Name></Step>
    </Request>
  </Flow>
</Flows>

Mengonfigurasi flow dengan kebijakan

Setiap endpoint memiliki kebijakan yang terkait dengannya. Mari kita lihat contoh kebijakannya. Lihat juga Mengonfigurasi endpoint dan kebijakan OAuth untuk ringkasan singkat tentang langkah-langkah yang diperlukan untuk menambahkan kebijakan OAuthV2 ke endpoint proxy.

Ini adalah jalur /oauth/authorize. Kebijakan yang disertakan bertanggung jawab untuk mengalihkan pengguna ke aplikasi login, tempat pengguna akhir dapat dengan aman mengautentikasi dan memberi otorisasi aplikasi klien untuk mengakses resource yang dilindungi tanpa membocorkan nama pengguna dan sandi mereka ke aplikasi klien. Anda dapat melakukannya dengan kebijakan info layanan, JavaScript, atau cara lainnya.

Panggilan API untuk melakukan permintaan adalah GET dan memerlukan parameter kueri client_id, response_type, redirect_uri, cakupan, dan status.

$ curl http://myorg-test.apigee.net/oauth/authorize?client_id={consumer_key}&response_type=code&redirect_uri={redirect_uri}&scope=scope1%20scope2&state={some_string}

Dapatkan kode autentikasi

Ini adalah jalur /oauth/authorizationcode. Metode ini menggunakan kebijakan OAuthV2 dengan operasi GenerateAuthorizationCode yang ditentukan.

<OAuthV2 async="false" continueOnError="false" enabled="true" name="GetAuthCode">
    <DisplayName>GetAuthCode</DisplayName>
    <Operation>GenerateAuthorizationCode</Operation>
    <ExpiresIn>600000</ExpiresIn>
    <GenerateResponse/>
</OAuthV2>

Panggilan API untuk mendapatkan kode otorisasi adalah GET dan memerlukan parameter kueri client_id, response_type, serta cakupan dan status secara opsional, seperti yang ditunjukkan dalam contoh berikut:

$curl http://myorg-test.apigee.net/oauth/authorizationcode?client_id={consumer_key}&response_type=code&scope=scope1%20scope2&state={some_string}

Dapatkan token akses

Kebijakan ini disertakan pada jalur /oauth/accesstoken. Kebijakan ini menggunakan kebijakan OAuthV2 dengan operasi GenerateAccessCode yang ditentukan. Dalam hal ini, parameter provide_type diharapkan sebagai parameter kueri:

<OAuthV2 name="GetAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>360000000</ExpiresIn> 
    <SupportedGrantTypes> 
        <GrantType>authorization_code</GrantType> 
    </SupportedGrantTypes> 
    <GrantType>request.queryparam.grant_type</GrantType> 
    <GenerateResponse/> 
</OAuthV2>

Panggilan API untuk mendapatkan kode akses adalah POST dan harus menyertakan client_id, client_secret, grant_type=authorization_code, dan, jika perlu, cakupan. Contoh:

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

Ini hanyalah ringkasan dasar. Contoh produksi mencakup banyak kebijakan lain untuk membuat URL, melakukan transformasi, dan menjalankan tugas lainnya. Lihat contoh di GitHub untuk mengetahui project yang lengkap dan berfungsi.

Melampirkan kebijakan token verifikasi akses

Lampirkan kebijakan VerifyAccessToken (kebijakan OAuthV2 dengan operasi VerifyAccessToken yang telah ditentukan) ke awal alur yang mengakses API yang dilindungi, sehingga API tersebut akan dijalankan setiap kali ada permintaan untuk resource yang dilindungi. Apigee akan memeriksa untuk memastikan setiap permintaan memiliki token akses yang valid. Jika tidak, error akan ditampilkan. 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, seperti 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.