Halaman ini diterjemahkan oleh Cloud Translation API.

Menerapkan jenis pemberian kode otorisasi

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 "three-legged OAuth". Dalam konfigurasi ini, pengguna mengautentikasi dirinya sendiri dengan server resource dan memberikan izin pada 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 Edge.

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 dapat dipercaya. Dengan jenis pemberian ini, kredensial pengguna di server resource tidak akan pernah dibagikan ke aplikasi.

Contoh kode

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

Diagram alir

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 dan buka di tab baru, atau simpan dan buka di penampil gambar.

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 dari alur ini adalah bahwa klien tidak pernah melihat kredensial pengguna di server resource.

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

1. Pengguna memulai alur

Ketika perlu mengakses resource yang dilindungi milik pengguna dari server resource (misalnya, daftar kontak di situs media sosial), aplikasi akan mengirimkan panggilan API ke Apigee Edge, yang memvalidasi ID klien dan, jika valid, akan mengalihkan browser pengguna ke halaman login tempat pengguna memasukkan kredensial. Panggilan API menyertakan informasi yang diperoleh aplikasi klien saat terdaftar: 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 pilihan cakupan, sehingga pengguna dapat memilih tindakan yang diizinkan aplikasi pada server resource. Misalnya, pengguna mungkin memberikan izin hanya baca, atau izin bagi aplikasi untuk mengupdate resource.

4. Aplikasi login mengirimkan permintaan Apigee Edge

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

5. Apigee Edge menghasilkan kode otorisasi

Saat Edge menerima permintaan GET dari aplikasi login pada endpoint /authorizationcode-nya, terjadi dua hal. Pertama, Edge menentukan bahwa login berhasil (dengan memeriksa status HTTP atau cara lain). Next Edge akan memeriksa untuk memastikan bahwa URI pengalihan yang dikirim dari aplikasi login cocok dengan URI pengalihan yang ditentukan saat aplikasi didaftarkan dengan Apigee Edge. Jika semuanya baik-baik saja, Edge 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. Edge mengirimkan kode otorisasi kembali ke klien

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

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

Kini dengan kode autentikasi yang valid, klien dapat meminta token akses dari Edge. Hal ini dilakukan dengan MEMPOSTING client ID dan kunci rahasia klien (diperoleh saat aplikasi didaftarkan di Edge), 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'

8. Klien menerima token akses

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

9. Klien memanggil API yang dilindungi

Sekarang, dengan kode akses yang valid, klien dapat melakukan panggilan ke API yang dilindungi. Dalam skenario ini, permintaan diajukan 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 flow dan kebijakan

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

Membuat flow kustom
Menambahkan dan mengonfigurasi kebijakan OAuthV2

Konfigurasi alur kustom

Biasanya, Anda harus mengonfigurasi alur jenis pemberian izin ini sehingga setiap langkah atau "segmen" 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 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 alur 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 guna mendapatkan ringkasan langkah-langkah yang diperlukan untuk menambahkan kebijakan OAuthV2 ke endpoint proxy.

Ini adalah jalur /oauth/authorize. Kebijakan yang terlampir bertanggung jawab untuk mengalihkan pengguna ke aplikasi login, tempat pengguna akhir dapat mengautentikasi dan mengizinkan aplikasi klien dengan aman untuk mengakses resource yang dilindungi tanpa memberitahukan nama pengguna dan sandi mereka ke aplikasi klien. Anda dapat melakukannya dengan kebijakan pemanggilan layanan, JavaScript, Node.js, atau cara lainnya.

Panggilan API untuk melakukan 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. Contoh 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 (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 ke jalur /oauth/accesstoken. Contoh ini menggunakan kebijakan OAuthV2 dengan operasi GenerateAccessCode yang ditentukan. Dalam hal ini, parameter Grants_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 melakukan tugas lainnya. Lihat contoh di GitHub untuk mengetahui project yang lengkap dan berfungsi.

Melampirkan kebijakan verifikasi token akses

Lampirkan kebijakan VerifyAccessToken (kebijakan OAuthV2 dengan operasi VerifyAccessToken yang ditetapkan) di awal alur yang mengakses API yang dilindungi, sehingga kebijakan tersebut dijalankan setiap kali permintaan untuk resource yang dilindungi masuk. Edge 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, 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.