Otentikasi dan Otorisasi OAuth

OAuth 2.0 di API Accurate Online

OAuth 2.0 merupakan sebuah standar framework otorisasi yang memungkinkan aplikasi pihak ke-3 untuk mendapatkan akses terbatas terhadap data yang dimiliki oleh pengguna Accurate Online. Framework ini juga digunakan oleh berbagai layanan berbasis web lainnya seperti: Facebook, Google, dll.

Sebelum dapat melakukan proses OAuth, pastikan aplikasi Anda sudah didaftarkan dari Area Developer. Untuk setiap aplikasi yang didaftarkan, Anda akan memperoleh beberapa credentials yaitu:

1. 1. Client ID
      Client ID digunakan sebagai ID unik pengenal aplikasi. Dalam OAuth 2.0, API Key ini digunakan sebagai parameter Client ID
   2. Client Secret
      Client Secret digunakan untuk menukar Authorization Code menjadi Access Token pada flow Grant Type: Authorization Code. OAuth Secret juga digunakan saat proses Refresh Token untuk memperbarui Access Token yang sudah expire

Berikut ini contoh credential aplikasi yang sudah didaftarkan di Area Developer Accurate Online:

Nama Aplikasi
Demo Example
Platform
Website
URL Website
https://example.com
URL OAuth Callback
https://example.com/aol-oauth-callback
Client ID
42f12a10-08df-4b91-b1e4-c4465d686072
Client Secret
e133410eb632596255adfbe5a49990fe

1. 1. Otorisasi Pengguna
      Pada tahap ini pengguna AOL akan melakukan login menggunakan akun AOL dan menyetujui untuk memberikan akses terbatas kepada aplikasi pihak ke-3 terkait
   2. Mendapatkan Access Token
      Pada tahap ini apabila pengguna AOL sudah berhasil login dan menyetujui untuk memberikan akses kepada aplikasi pihak ke-3, maka AOL akan memberikan Access Token kepada aplikasi pihak ke-3 untuk disimpan dan kemudian digunakan untuk mengakses API AOL
   3. Mengakses API AOL
      Setelah menerima Access Token, aplikasi pihak ke-3 sudah dapat mengakses API AOL

Berikut ini diagram yang menggambarkan garis besar interaksi antara aplikasi pihak ke-3 (Application), pengguna AOL (User) dan Server AOL (Authorization & Resource Server) dalam proses OAuth 2.0:

Untuk memulai tahap Otorisasi Pengguna, aplikasi pihak ke-3 harus menampilkan form otorisasi terlebih dahulu. Biasanya pada aplikasi pihak-3, ditambahkan sebuah tombol “Integrasi dengan Accurate Online“, dimana jika tombol tersebut diklik oleh pengguna maka akan membuka pop-up web browser yang akan menampilkan form otorisasi pengguna Accurate Online.

Untuk menampilkan form Otorisasi Pengguna, pada pop-up web browser diarahkan ke URL berikut ini:
https://account.accurate.id/oauth/authorize

dengan rincian parameter sebagai berikut:

Apabila parameter yang digunakan untuk menampilkan form Otorisasi Pengguna sudah benar, maka akan tampil form login AOL, dan setelah pengguna login menggunakan akun AOL nya, akan ditampilkan Halaman Otorisasi untuk memberikan akses kepada applikasi pihak ke-3 terhadap data pengguna di AOL. Untuk melanjutkan tekan tombol Beri Akses.

Ada 2 jenis Grant Type dalam proses OAuth 2.0 yang didukung oleh AOL (yang dibedakan pada nilai parameter response_type saat menampilkan form otorisasi pengguna) yaitu:

1. Implicit (response_type=token)

Jenis ini digunakan untuk platform aplikasi mobile atau web (yang berjalan di perangkat pengguna) dimana tidak ada mekanisme penyimpanan data yang aman. Pada flow Implicit ini, saat selesai proses Otorisasi Pengguna, aplikasi pihak ke-3 akan langsung menerima Access Token, namun Access Token tersebut tidak dapat diperbaruhi setelah expire. Berikut ini diagram yang menggambarkan flow Implicit:

Apabila pengguna memberikan akses pada tahap otorisasi, maka web browser akan melakukan redirect ke redirect_uri yang ditentukan, dengan parameter tambahan dimana pada parameter tersebut terdapat Access Token yang dapat digunakan untuk mengakses API AOL. Berikut ini contoh URL redirect di web browser:
https://example.com/aol-oauth-callback#access_token=e8446369-bd56-4731-acea-c0a9e0cc46fa&token_type=bearer&user=%7Bname=John%20Doe,%[email protected]%7D

Pada tahap ini aplikasi pihak ke-3 harus bisa melakukan parsing URL browser untuk bisa mendapatkan Access Token yang disertakan di URL, yang pada contoh ini adalah e8446369-bd56-4731-acea-c0a9e0cc46fa. Aplikasi pihak ke-3 harus dapat menyimpan Access Token tersebut untuk dipergunakan pada saat mengakses API AOL

2. Authorization Code (response_type=code)

Jenis ini digunakan untuk plaftorm server-side web application, dimana aplikasi dapat menyimpan data (Client Secret) dengan aman di server (tidak dapat langsung diakses oleh user). Flow Authorization Code ini lebih aman daripada flow Implicit. Pada flow Authorization Code ini, saat selesai proses Otorisasi Pengguna, aplikasi pihak ke-3 hanya akan menerima Authorization Code, dimana selanjutnya kode tersebut dapat ditukar menjadi Access Token dengan melakukan request dari server aplikasi pihak ke-3 ke server AOL menggunakan credential Client ID dan Client Secret. Berikut ini diagram yang menggambarkan flow Authorization Code:

Apabila pengguna memberikan akses pada tahap otorisasi, maka web browser akan melakukan redirect ke redirect_uri yang ditentukan, dengan parameter tambahan dimana pada parameter tersebut terdapat Authorization Code yang perlu ditukarkan untuk mendapatkan Access Token. Berikut ini contoh URL redirect di web browser:
https://example.com/aol-oauth-callback?code=2S8F64jJTOJi1vuCxG8G

Pada tahap ini aplikasi pihak ke-3 harus bisa melakukan parsing URL browser untuk bisa mendapatkan Authorization Code yang disertakan di URL, yang pada contoh ini adalah 2S8F64jJTOJi1vuCxG8G. Selanjutnya dari server aplikasi pihak ke-3, lakukan HTTP POST Request ke server AOL dengan rincian sebagai berikut:

Jika diperhatikan untuk request diatas harus menyertakan header Authorization: Basic dimana valuenya diisi dengan nilai Base64 Encode dari Client ID:Client Secret (Cth: 42f12a10-08df-4b91-b1e4-c4465d686072:e133410eb632596255adfbe5a49990fe). Metode menambahkan informasi Authorization di Header seperti ini dikenal dengan metode HTTP Basic Authentication dengan API Key sebagai user dan OAuth Secret sebagai password.

Jika berhasil menukar Authorization Code akan mendapatkan response sebagai berikut:

{
  "access_token": "a83278c3-6018-4374-9f12-4c5b6a09ab16",
  "token_type": "bearer",
  "refresh_token": "5f32ef57-a3ba-4c6d-a763-c83c67350c73",
  "scope": "item_view item_save sales_invoice_view",
  "user": {
    "name": "John Doe",
    "email": "[email protected]"
   }
}

Sampai tahap ini proses OAuth telah selesai dan sudah didapatkan Akses Token a83278c3-6018-4374-9f12-4c5b6a09ab16, aplikasi pihak ke-3 perlu menyimpan Access Token tersebut untuk selanjutnya digunakan saat mengakses API AOL.

Refresh Token

Setiap Access Token yang diterima oleh aplikasi pihak ke-3 akan expire dalam waktu 15 hari sejak dibuat. Jika expire, Access Token tidak lagi dapat digunakan untuk mengakses API. Untuk flow Grant Type: Authorization Code, aplikasi pihak ke-3 juga menerima Refresh Token pada response Access Token, dimana Refresh Token ini dapat digunakan untuk mendapatkan Access Token baru. Best practice yang kami sarankan adalah aplikasi melakukan Refresh Token apabila Access Token sudah expire atau minimal 1 hari sebelum expire.

Untuk melakukan Refresh Token, server aplikasi dapat melakukan request ke server AOL sbb:

Apabila Refresh Token berhasil dilakukan, maka akan mendapatkan response yang berisi Access Token baru, dimana untuk contoh dibawah ini adalah v034ns92-5280-4103-4dna-2nc893nac06y. Aplikasi pihak ke-3 harus menyimpan Access Token baru ini untuk menggantikan Access Token lama yang sudah expire dan digunakan untuk menakses API AOL selanjutnya.

{
  "access_token": "v034ns92-5280-4103-4dna-2nc893nac06y",
  "token_type": "bearer",
  "refresh_token": "5f32ef57-a3ba-4c6d-a763-c83c67350c73",
  "scope": "item_view item_save sales_invoice_view",
  "user": {
    "name": "John Doe",
    "email": "[email protected]"
   }
}