Drive and Photo Service:Integrasi aplikasi JWT

Ikhtisar aplikasi JWT

Dalam dokumen ini, aplikasi JWT merujuk pada aplikasi kustom yang menggunakan JSON Web Token (JWT) untuk otentikasi identitas.

Aplikasi JWT dapat menandatangani data dengan kunci privat di sisi server untuk menghasilkan string JWT. String JWT tersebut berfungsi sebagai kredensial untuk mengakses server yang telah dikonfigurasi dengan kunci publik yang sesuai.

Skenario

1. Sebuah perusahaan memiliki sistem perangkat lunak internal dengan sistem akun independen dan ingin memungkinkan pengguna masuk melalui halaman login internalnya, lalu menggunakan fitur PDS.

2. Sebuah perusahaan memiliki sistem akun independen dan portal login, serta ingin mengintegrasikan portal login tersebut dengan PDS untuk membangun sistem penyimpanan cloud bagi akun-akun independennya.

Ikhtisar langkah integrasi

1. Di Konsol PDS, buat domain kustom dan aplikasi JWT.

2. Buat pasangan kunci publik–privat menggunakan algoritma RSA. Simpan kunci publik di sisi server PDS dan kunci privat di sisi server aplikasi JWT.

3. Sisi server aplikasi JWT mengenkode data, menandatangani data tersebut dengan kunci privat untuk menghasilkan string JWT Assertion, lalu mengirim string tersebut ke sisi server PDS.

4. Setelah sisi server PDS memvalidasi string JWT Assertion menggunakan kunci publik, server tersebut mengembalikan token akses ke sisi server aplikasi JWT. Sisi server aplikasi JWT kemudian dapat memanggil API yang disediakan oleh sisi server PDS menggunakan token akses tersebut.

Langkah-langkah detail

1 Konfigurasikan kunci

1.1 Buat atau pilih domain

1.2 Buat atau pilih aplikasi

Buka halaman detail domain. Di halaman daftar aplikasi, buat atau pilih aplikasi:

1.3 Atur kunci publik

Setelah membuat atau memilih aplikasi, klik Set Public Key.

Hasilkan kunci publik dan kunci privat.

Setelah menghasilkan kunci publik dan privat, salin dan simpan kunci privat tersebut, lalu klik OK.

2 Peroleh access_token

2.1 Sisi server aplikasi menghitung string JWT

Enkode data yang akan ditandatangani, lalu tandatangani data tersebut dengan kunci privat menggunakan algoritma enkripsi yang ditentukan untuk menghasilkan string JWT. Contoh kode berikut untuk Node.js menunjukkan cara melakukan operasi ini:

const JWT = require('jsonwebtoken');

function signAssertion({ domain_id, client_id, user_id, privateKeyPEM }) {
  var now_sec = parseInt(Date.now() / 1000);
  var opt = {
    iss: client_id,
    sub: user_id,
    sub_type: "user",
    aud: domain_id,
    jti: Math.random().toString(36).substring(2),
    exp: now_sec + 60,
    // iat: waktu saat ini dalam detik
    // nbf: not before
    auto_create: false,
  };
  return JWT.sign(opt, privateKeyPEM, {
    algorithm: "RS256",
  });
}

parameter opt

Untuk informasi lebih lanjut tentang library pihak ketiga JWT dan metode perhitungannya, kunjungi situs resmi JWT.

2.2 Peroleh access_token menggunakan string JWT

Panggil antarmuka Authorize untuk memperoleh access_token.

POST /v2/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&client_id=${APP_ID}&assertion=xxxxxxxxxx

Parameter permintaan

Contoh tanggapan

{
  "access_token": "eyJh****eQdnUTsEk4",
  "refresh_token": "kL***Lt",
  "expires_in": 7200,
  "token_type": "Bearer"
}

Setelah sisi server aplikasi memperoleh access_token, server tersebut mengembalikan token ke klien web aplikasi. Saat memanggil API PDS, Anda harus menyertakan access_token untuk mengakses sumber daya pengguna di PDS.

2.3 Refresh access_token

Access_token yang diperoleh menggunakan JWT berlaku selama 2 jam. Setelah kedaluwarsa, Anda harus memperoleh access_token baru. Dalam waktu tujuh hari setelah kedaluwarsa, Anda dapat memanggil API PDS untuk memperoleh access_token baru menggunakan access_token yang sudah kedaluwarsa. Jika lebih dari tujuh hari telah berlalu, Anda harus mengulangi Langkah 2.1 dan 2.2.

Kode berikut menunjukkan contoh permintaan untuk memanggil antarmuka Authorize guna memperoleh access_token:

POST /v2/oauth/token
Content-Type: application/x-www-form-urlencoded

client_id=${APPID}&refresh_token=${access_token}&grant_type=refresh_token&redirect_uri=${REDIRECT_URI}

3 Gunakan Basic UI (opsional)

Jika Anda tidak ingin mengembangkan UI sendiri dan Basic UI resmi memenuhi kebutuhan Anda, Anda dapat langsung menggunakan Basic UI tersebut.

Metode 1:

Gunakan window.open untuk membuka Basic UI, lalu kirimkan token akses menggunakan postMessage.

Kode contoh:

const endpoint = `https://${domain_id}.apps.aliyunpds.com`
const url = `${endpoint}/accesstoken?origin=${location.origin}`
var win = window.open(url)

window.addEventListener('message', onMessage, false)
async function onMessage(e) {
  if (e.data.code == 'token' && e.data.message == 'ready') {
    var result = await getToken(); // Peroleh AccessToken dari sisi server
    //result = {"access_token": ...}
    win.postMessage({
      code: 'token',
      message: result
    }, endpoint || '*')

    window.removeEventListener('message', onMessage)
  }
}

Metode 2:

BasicUI menyematkan halaman login kustom menggunakan iframe.

Dalam konfigurasi sistem, tetapkan URL halaman login kustom dan ID aplikasi JWT agar Basic UI dapat melakukan refresh token secara otomatis.

Saat pengguna login, halaman login kustom yang disematkan dalam iframe akan menggantikan halaman login default Basic UI.

Setelah pengguna berhasil login, kirimkan token ke halaman host menggunakan postMessage.

if(parent!=self){
  let origin = ''
  parent.postMessage({
    code: 'token',
    message: {
       access_token: 'xxxx',
       refresh_token: 'xxxx',
       ...
    }
  }, endpoint || "*")
}

Lampiran 1: Implementasi kode Node.js

Kode contoh berikut menunjukkan cara aplikasi JWT memperoleh dan merefresh access_token:

const fs = require('fs')
const JWT = require('jsonwebtoken');
const axios = require('axios')

const DOMAIN_ID = '' // ID Domain
const APP_ID = '' // ID Aplikasi
const USER_ID = '' // UID Pengguna
const PRIVATE_KEY_PEM = '' // Kunci privat, dikonfigurasi di langkah 1.3
const PRE = `https://${domain_id}.api.aliyunpds.com`

async function init() {
  try {
    // Variabel-variabel ini perlu diisi berdasarkan kondisi aktual
    var params = {
      domain_id: DOMAIN_ID,
      client_id: APP_ID,
      user_id: USER_ID,
      privateKeyPEM: PRIVATE_KEY_PEM,
    };
    var assertion = signAssertion(params)
    var obj = await getToken(assertion)
    return obj.data
  } catch (e) {
    if (e.response) {
      console.log(e.response.status)
      console.log(e.response.headers)
      console.log(e.response.data)
    } else {
      console.error(e)
    }
  }
}

function signAssertion({ domain_id, client_id, user_id, privateKeyPEM }) {
  var now_sec = parseInt(Date.now()/1000)
  var opt = {
    iss: client_id,
    sub: user_id,
    sub_type: 'user',
    aud: domain_id,
    jti: Math.random().toString(36).substring(2),
    exp: now_sec + 300,
    // iat: waktu saat ini dalam detik
    // nbf: not before
    auto_create: true,
  };
  return JWT.sign(opt, privateKeyPEM, {
    algorithm: 'RS256'
  });
}

async function getToken(assertion) {
  return await axios({
    method: 'post',
    url: PRE + '/v2/oauth/token',
    // Catatan: Atur content-type permintaan menjadi application/x-www-form-urlencoded
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    // Catatan: Letakkan parameter permintaan di body
    data: params({
      grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
      client_id: APP_ID,
      assertion
    })
  })
}

async function refreshToken(refresh_token) {
  return await axios({
    method: 'post',
    url: PRE + '/v2/oauth/token',
    // Catatan: Atur content-type permintaan menjadi application/x-www-form-urlencoded
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    // Catatan: Letakkan parameter permintaan di body
    data: params({
      grant_type: 'refresh_token',
      client_id: APP_ID,
      refresh_token,
    })
  })
}

function params(m){
  const params = new URLSearchParams();
  for(var k in m){
     params.append(k, m[k]);
  }
  return params;
}

// Panggilan uji
;(async ()=>{
  let result = await init()
  console.log(result) // Mengembalikan objek token {access_token:...}. Untuk struktur objek, lihat Lampiran 2.
  // Setelah access_token kedaluwarsa
  refreshToken(result.refreshToken) // Mengembalikan objek token baru {access_token:...}. Untuk struktur objek, lihat Lampiran 2.
})();

Lampiran 2: Struktur objek token

Data contoh

{
  access_token: 'eyJhbG.....g7M0p28',
  refresh_token: '62f1acc.......9b781f3',
  expires_in: 7200,
  token_type: 'Bearer',
  ......
}

Untuk informasi lebih lanjut tentang parameter-parameter tersebut, lihat Token - Peroleh token akses.