Anda sedang melihat dokumentasi Apigee Edge.
Buka
dokumentasi Apigee X. info
Kode otorisasi adalah salah satu jenis pemberian OAuth 2.0 yang paling umum digunakan. Alur kode otorisasi adalah konfigurasi "OAuth tiga pihak". Dalam konfigurasi ini, pengguna mengautentikasi dirinya sendiri dengan server resource dan memberikan izin kepada aplikasi untuk mengakses resource yang dilindungi tanpa mengungkapkan nama pengguna/sandi ke aplikasi klien.
Tentang topik ini
Topik ini menawarkan deskripsi dan ringkasan umum tentang alur jenis pemberian otorisasi OAuth 2.0 dan membahas cara menerapkan alur ini di Apigee Edge.
Video
Tonton video singkat untuk mempelajari cara menggunakan jenis pemberian otorisasi OAuth 2.0 untuk mengamankan API Anda.
Kasus penggunaan
Jenis pemberian ini ditujukan untuk aplikasi yang ditulis oleh developer pihak ketiga yang tidak memiliki hubungan bisnis tepercaya dengan penyedia API. Misalnya, developer yang mendaftar untuk program API publik umumnya tidak boleh dipercaya. Dengan jenis pemberian ini, kredensial pengguna di server resource tidak pernah dibagikan kepada aplikasi.
Contoh kode
Anda dapat menemukan contoh implementasi lengkap dan berfungsi dari jenis pemberian kode otorisasi di
Apigee Edge di repo api-platform-samples di GitHub. Lihat oauth-advanced
sample di direktori api-platform-samples/sample-proxies. Lihat file
README untuk mengetahui detail tentang contoh.
Diagram alur
Diagram alur berikut menggambarkan alur OAuth kode otorisasi dengan Apigee Edge yang berfungsi sebagai server otorisasi.
Tips: Untuk melihat versi diagram yang lebih besar, klik kanan diagram tersebut dan buka di tab baru, atau simpan dan buka di penampil gambar.
.png?hl=id)
Langkah-langkah dalam alur kode otorisasi
Berikut adalah ringkasan langkah-langkah yang diperlukan untuk menerapkan jenis pemberian kode otorisasi dengan Apigee Edge sebagai server otorisasi. Ingat, kunci alur ini adalah bahwa klien tidak pernah melihat kredensial pengguna di server resource.
Prasyarat: Aplikasi klien harus didaftarkan dengan Apigee Edge untuk mendapatkan kunci client ID dan rahasia klien. Lihat Mendaftarkan aplikasi klien untuk mengetahui detailnya.
1. Pengguna memulai alur
Saat aplikasi perlu mengakses resource terlindungi pengguna dari server resource (misalnya, daftar kontak di situs media sosial), aplikasi akan mengirimkan panggilan API ke Apigee Edge, yang akan memvalidasi ID klien dan, jika valid, mengalihkan browser pengguna ke halaman login tempat pengguna akan memasukkan kredensialnya. Panggilan API mencakup informasi yang diperoleh aplikasi klien saat didaftarkan: ID klien dan URI pengalihan.
2. Pengguna memasukkan kredensial
Pengguna kini melihat halaman login tempat mereka diminta untuk memasukkan kredensial login. Jika login berhasil, kita akan melanjutkan ke langkah berikutnya.
3. Pengguna memberikan izin
Pada langkah ini, pengguna memberikan izin kepada aplikasi untuk mengakses resource mereka. Formulir izin biasanya mencakup pilihan cakupan, tempat pengguna dapat memilih apa yang diizinkan untuk dilakukan aplikasi di server resource. Misalnya, pengguna dapat memberikan izin hanya baca, atau izin bagi aplikasi untuk memperbarui resource.
4. Aplikasi login mengirim permintaan ke Apigee Edge
Jika login dan pemberian izin berhasil, aplikasi login akan mengirimkan data POST ke endpoint /authorizationcode Apigee Edge. Data ini mencakup URI pengalihan, ID klien, cakupan, informasi khusus pengguna yang ingin disertakan, dan indikasi bahwa login berhasil.
5. Apigee Edge menghasilkan kode otorisasi
Saat Edge menerima permintaan POST dari aplikasi login di endpoint /authorizationcode, dua hal akan terjadi. Pertama, Edge menentukan bahwa login berhasil (dengan memeriksa parameter atau header permintaan untuk indikator keberhasilan). Selanjutnya, Edge memeriksa untuk memastikan bahwa URI pengalihan yang dikirim dari aplikasi login cocok dengan URI pengalihan yang ditentukan saat aplikasi didaftarkan ke Apigee Edge. Jika semuanya sudah beres, Edge akan membuat kode otorisasi.
{redirect_uri}?code={authorization_code}&state={some_string}6. Klien mengambil kode otorisasi dan meminta token akses dari Edge
Sekarang dengan kode otorisasi yang valid, klien dapat meminta token akses dari Edge. Hal ini dilakukan dengan mem-POST kunci rahasia klien dan ID klien (yang diperoleh saat aplikasi didaftarkan di Edge), kode otorisasi, jenis pemberian, dan cakupan. Dengan menyertakan client ID dan kunci rahasia, Apigee Edge dapat memverifikasi bahwa aplikasi klien 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'
7. Klien menerima token akses
Jika semuanya berhasil, Edge akan menampilkan token akses ke klien. Token akses akan memiliki masa berlaku, dan hanya akan valid untuk cakupan yang ditentukan oleh pengguna saat mereka memberikan izin kepada aplikasi untuk mengakses resource mereka.
8. Klien memanggil API yang dilindungi
Sekarang, dengan token akses yang valid, klien dapat melakukan panggilan ke API yang dilindungi. 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. 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, Edge perlu memproses sejumlah permintaan OAuth: untuk token akses, kode otorisasi, token refresh, pengalihan halaman login, dll. Ada dua langkah mendasar untuk mengonfigurasi endpoint ini:
- Membuat alur kustom
- Menambahkan dan mengonfigurasi kebijakan OAuthV2
Konfigurasi alur kustom
Biasanya, Anda mengonfigurasi alur jenis pemberian ini sehingga setiap langkah atau "leg" alur ditentukan
oleh alur di proxy Apigee Edge. Setiap alur memiliki endpoint dan kebijakan yang melakukan
tugas khusus OAuth yang diperlukan, seperti membuat kode otorisasi atau token akses. Misalnya, seperti yang ditunjukkan dalam XML di bawah, endpoint /oauth/authorizationcode memiliki kebijakan terkait yang disebut GenerateAuthCode (yang merupakan kebijakan OAuthV2 dengan operasi GenerateAuthorizationCode yang ditentukan).
Cara termudah untuk menunjukkan konfigurasi alur adalah dengan contoh XML. Lihat komentar inline untuk mengetahui informasi tentang setiap alur. Berikut adalah contohnya -- nama alur dan jalur dapat dikonfigurasi sesuai keinginan Anda. Lihat juga Mengonfigurasi endpoint dan kebijakan OAuth untuk mengetahui ringkasan singkat 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 alur dengan kebijakan
Setiap endpoint memiliki kebijakan yang terkait dengannya. Mari kita lihat contoh kebijakan tersebut. Lihat juga Mengonfigurasi endpoint dan kebijakan OAuth untuk mengetahui ringkasan singkat langkah-langkah yang diperlukan untuk menambahkan kebijakan OAuthV2 ke endpoint proxy.
Pengalihan login
Ini adalah jalur /oauth/authorize. Kebijakan terlampir bertanggung jawab untuk
mengarahkan pengguna ke aplikasi login, tempat pengguna akhir dapat melakukan autentikasi dan mengizinkan aplikasi klien dengan aman untuk mengakses resource yang dilindungi tanpa mengungkapkan nama pengguna dan sandi mereka ke aplikasi klien. Anda dapat melakukannya dengan kebijakan panggilan layanan, JavaScript, Node.js, atau cara lainnya.
Panggilan API untuk membuat permintaan adalah GET dan memerlukan parameter kueri client_id, response_type, redirect_uri, scope, dan state.
$ 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. Operasi 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 POST dan memerlukan client_id, response_type, redirect_uri, dan secara opsional scope dan state untuk diteruskan di isi permintaan sebagai parameter formulir, seperti yang ditunjukkan dalam contoh ini:
$ curl http://myorg-test.apigee.net/oauth/authorizationcode -X POST -d 'client_id={consumer_key}&response_type=code&redirect_uri={redirect_uri}&scope=scope1%20scope2&state={some_string}'
Mendapatkan token akses
Kebijakan ini dilampirkan ke jalur /oauth/accesstoken. API ini menggunakan kebijakan OAuthV2
dengan operasi GenerateAccessToken yang ditentukan. Dalam hal ini, parameter grant_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 token akses adalah POST dan harus menyertakan kode otorisasi, client_id, client_secret, grant_type=authorization_code, dan, secara opsional, scope. Contoh:
$ curl https://{org_name}-test.apigee.net/oauth/accesstoken?grant_type=authorization_code -X POST -d 'code={authorization_code}&client_id=bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K&client_secret=hAr4Gn0gA9vAyvI4'
Ini hanya ringkasan dasar. Contoh produksi mencakup banyak kebijakan lain untuk membuat URL, melakukan transformasi, dan melakukan tugas lainnya. Lihat contoh di GitHub untuk project lengkap yang berfungsi.
Melampirkan kebijakan token akses verifikasi
Lampirkan kebijakan VerifyAccessToken (kebijakan OAuthV2 dengan operasi VerifyAccessToken yang ditentukan) di awal alur yang mengakses API yang dilindungi, sehingga kebijakan tersebut dijalankan setiap kali permintaan untuk resource yang dilindungi masuk. Edge memeriksa untuk memastikan setiap permintaan memiliki token akses yang valid. Jika tidak, error akan ditampilkan. Untuk mengetahui 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 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 dalam 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.