Proses Otentifikasi dan Otorisasi OAuth API Accurate Online

Konten kali ini adalah lanjutan dari konten Pendaftaran API Accurate Online. Setelah selesai Cara Melakukan API Accurate Online, Anda perlu melakukan Otentifikasi dan Otorisasi OAuth API Accurate Online. Proses OAuth adalah proses protokol terbuka yang memungkinkan pengguna untuk berbagai sumber pribadi (mis. foto, video, daftar alamat, dan database) yang disimpan di suatu website dengan situs lain tanpa perlu menyerahkan nama pengguna dan kata sandi. Proses ini akan dilakukan menggunakan token bukan kata sandi. Token tersebut akan memberikan akses pada aplikasi atau platform tertentu.

Di Accurate Online untuk melakukan API, menggunakan OAuth 2.0 yang menjadi standar framework otorisasi untuk mengizinkan pihak ketiga untuk mendapatkan akses terbatas terhadap data yang dimiliki oleh para pengguna Accurate Online. Hampir seluruh proses Framework berbasis web.

Untuk melakukan proses OAuth, pastikan setiap aplikasi sudah di daftarkan pada area Developer. Setiap aplikasi yang di daftarkan akan mendapatkan credentials, yaitu:

1. Client ID : Digunakan sebagai tanda ID pengenal aplikasi. Dalam OAuth 2.0 API Key digunakan sebagai parameter Client ID.
2. Client Secret: digunakan untuk enukar authorization Code menjadi Access Token pada flow Grant Type: Auhtorization Code. OAUth secret juga digunakan saat proses Refresh Token untuk memperbaiki Access Token yang sudah expired.

Contoh Credential Aplikasi di Area Developer Accurate Online

Berikut contoh credential aplikasi:

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

Proses OAuth 2.0

Dalam proses Otentifikasi dan Otorisasi OAuth API Accurate Online Agar aplikasi pihak ke-3 yang ingin diintegrasikan dapat mengakses data pengguna Accurate Online (AOL), harus melewati proses OAuth 2.0 yang secara garis besar akan dibagi menjadi 3 tahap:

Otorisasi pengguna

Pada tahap ini pengguna Accurate Online perlu melakukan login menggunakan akun aktif AOL dan menyetujui dalam memberikan akses terbatas kepada pihak ke-3 terkait.

Mendapatkan Access Token

Jika pengguna sudah berhasil login dan menyetujui untuk memberikan akses kepada pihak ke-3, maka Accurate Online akan memberikan Access Token kepada aplikasi pihak ke-3 untuk disimpan dan kemudian digunakan untuk melakukan akses API Accurate Online.

Akses API Accurate Online

Ketika sudah menerima Access Token, aplikasi pihak ke-3 sudah bisa diakses Accurate Online.

Diagram API

Berikut ini diagram yang menggambarkan garis besar interaksi antara pihak ketiga (Application), Pengguna Accurate Online (User), dan Server Accurate Online (Authorization & Resource Server dalam proses OAuth 2.0:

Dalam memulai tahap otorisasi pengguna, aplikasi pihak ke-3 harus menampilkan form otorisasi terlebih dahulu. Biasanya pada aplikasi pihak ke-3, akan ditambahkan tombol “Integrasi dengan Accurate Online”, ketika tombol tersebut di klik maka pengguna akan membuka pop-up web browser yang akan menampilkan form otorisasi pengguna Accurate Online.

Form otorisasi, pengguna akan diarahkan ke web browser dan URL berikut ini:

https://account.accurate.id/oauth/authorize

Akan muncul rincian parameter seperti pada table dibawah ini:

URL	https://account.accurate.id/oauth/authorize
Method	HTML Request
Parameter
Client_ID	Isi menggunakan Credential Client ID Cth: 41h12a10-07df-3b91-c4468d765908
Response_type	Isi dengan nilai token atau code tergantung dari jenis platform yang digunakan Cth: Token
Redirect URL	Isi menggunakan URL OAuth Callback yang digunakan dan sudah di daftarkan pada setting aplikasi di Area Developer. Cth : https://contoh.com/aol-oauth-callback
Scope	Scope diisi menggunakan akses data yang ingin diharapkan. Setiap Scope dipisahkan menggunakan spasi seperti pada penjelasan pada Sub bab Scope pada proses OAuth. Cth: item_viewitem_save sales_Laporan_View

Jika parameter yang digunakan sudah sesuai dalam menampilkan Form Otorisasi Pengguna, akan muncul form login Accurate Online, dan setelah pengguna Login menggunakan Accurate Online, akan memunculkan halaman otorisasi untuk memberikan akses kepada pihak ketiga seperti gambar dibawah ini:

2 Jenis Grand Type

Pada Accurate Online terdapat 2 Jenis Grand Type proses OAuth 2.0 yang didukung (Dibedakan melalui nilai parameter response_type saat menampilkan form otorisasi pengguna) yaitu:

Implicit (Response_Type=Token)

Digunakan pada aplikasi mobile atau web (yang berjalan pada perangkat pengguna) dimana tidak ada mekanisme penyimpanan yang aman. Pada flow Implicit, saat selesai proses Otorisasi Pengguna, aplikasi pihak ke-3 akan menerima Access Token, namun Access Token tersebut tidak bisa diperbarui setelah expired. Berikut diagram flow implicit:

Apabila pengguna memberikan akses pada tahap otorisasi, web browser akan melakukan redirect ke redirect_URL yang telah ditentukan sebelumnya, dengan parameter tambahan yang memiliki Access Token yang dapat digunakan dalam mengakses API Accurate Online. Contoh URL Redirect:

https://contoh.com/aol-oauth-callback#access_token=e8786369-bc91-4731-abcd-c0n8e0dd79fa&token_type=bearer&user=%7Bname=toni%20alfa,%[email protected]%7D

pada tahap ini aplikasi yang akan di integrasikan harus mampu melakukan parsing URL browser untuk bisa mendapatkan Access Token yang disertakan URL, pada contoh ini e8786369-bc91-4731-abcd-c0n8e0dd79fa. Aplikasi pihak ke-3 harus bisa menyimpan Access Token tersebut untuk dipergunakan saat Akses API Accurate Online.

Authorization Code (response_type=code)

Jenis ini digunakan dalam platform server-side web application, dimana aplikasi dapat menyimpan data (client secret) dengan aman pada server penyimpanan (tidak bisa diakses langsung user). Flow Authorization User lebih aman daripada file Implicit.

Pada file Authorization Code, dimana selanjutnya kode ditukar menjadi Access Token dengan melakukan request dari server pihak ke-3 ke server Accurate Online menggunakan credential Client ID dan Client Secret. Berikut diagram Authorization Code:

Jika pengguna membuka akses dalam tahap otorisasi, web browser akan melakukan redirect ke redirect URL yang sudah ditentukan, dengan parameter tambahan dimana parameter tersebut memiliki Authorization Code yang perlu ditukarkan untuk mendapatkan Access Token. Contoh URL Redirect:

https://contoh.com/aol-oauth-callback?code=2S9F53jJZBJi1vuCxG8G

Dalam tahap ini aplikasi pihak ke-3 perlu bisa melakukan parsing URL browser untuk bisa mendapatkan Authorization Code yang disertakan pada URL, pada contoh diatas adalah 2S9F53jJZBJi1vuCxG8G. Selanjutnya perlu melakukan HTTP POST request ke server AOL dengan rincian:

URL	https://account.accurate.id/oauth/token
Method	HTTP Post
Header
Authorization	Basic NDJmMHGhMTAtMDhkZi00YjkxLWIxZTQtYzQ0NjVkNjg2MDcyOmUxMzM0NMB9YjYzMjU7NjI2NWFkKmJlCEW0OTk5MGZl
Request Body
Code	2S9F53jJZBJi1vuCxG8G
Grand_type	Authorization Code
Redirect_URL	https://contoh.com/aol-oauth-callback

 

Apabila diperhatikan untuk request diatas perlu menyertakan header Authorization: Basic dimana valuenya diisi dengan nilai Base64 Encode dari Client ID: Client Secret. Metode penambahan informasi Authorization di Header seperti ini dikenal dengan HTTP Basic Authentication dengan API Key sebagai user dan OAuth Secret sebagai Password.

Jika berhasil, Anda akan mendapatkan Authorization Code seperti response 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”: “Toni Alfa”,

“email”: “[email protected]”

}

}

Sampai tahap ini proses OAuth telah selesai dan sudah mendapatkan Akses Token. Aplikasi pihak ke-3 perlu menyimpan akses token tersebut untuk digunakan saat akses API Accurate Online.

Refresh Token

Setiap Access Token yang diterima oleh aplikasi pihak ke-3 akan expire dalam waktu 15 hari sejak dibuat. Jika Expire, Acess Token tidak bisa lagi digunakan untuk akses API. Untuk flow Grant Type: Authorization Code, aplikasi pihak ke-3 perlu menerima Refresh Token pada Response Access Token. Refresh Token  dapat digunakan untuk mendapatkan Access Token baru. Best practice yang kami sarankan adalah aplikasi Refresh Token jika Access Token sudah expire atau minimal 1 hari sebelum expire.

Untuk Refresh Token, Server aplikasi dapat melakukan request ke Server AOL :

URL	https://account.accurate.id/oauth/token
Method	HTTP Post
Header
Authorization	Basic NDJmGHJhMTAtMDhkZi00YjzyIOIxZTQtYzQ0NjVkNjg2MDcyOmUxMzM0MTBlYjYzMjU5BjI1NWFkZmJlNWE0OTk5MGZl
Request Body
Grant-Type	Refresh_token
Refresh_Token	5f67ef90-h2cv-4c7l-a233-s54b67350c73

 

Jika Refresh Token berhasil dilakukan, Anda akan mendapatkan response yang berisi Access Token baru. Aplikasi pihak ke-3 perlu menyimpan Access Token baru ini untuk menggantikan Access Token lama yang sudah expire dan digunakan untuk mengakses API Accurate Online selanjutnya.

{

“access_token”: “v034ns92-5280-4103-4dna-2nc893nac06y”,

“token_type”: “bearer”,

“refresh_token”: “5f67ef90-h2cv-4c7l-a233-s54b67350c73”,

“scope”: “item_view item_save sales_invoice_view”,

“user”: {

“name”: “Toni Alfa”,

“email”: “[email protected]”

}

}

Penutup

Nah demikianlah proses otentifikasi dan otorisasi OAuth API Accurate Online yang bisa dilakukan. Jika Anda masih bingung, bisa bertanya kepada tim kami.