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.
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.
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.
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.
Pengalihan login
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.