Panduan Integrasi OAuth2.0 Alur Kode Otorisasi

Urutan Pemanggilan

Gambaran Umum

OAuth 2.0 adalah protokol otorisasi yang banyak digunakan, yang memungkinkan aplikasi pihak ketiga mengakses sumber daya pengguna melalui persetujuan pengguna tanpa harus mengekspos kredensial pengguna. Dalam mode kode otorisasi OAuth 2.0, klien perlu mengarahkan pengguna ke titik akhir otorisasi (Authorization Endpoint) pada server otorisasi untuk memperoleh izin dari pengguna.

Dokumen ini bertujuan untuk menjelaskan secara rinci cara menyusun dan menggunakan URL otorisasi sesuai dengan protokol OAuth 2.0, serta memberikan contoh praktis dan hal-hal yang perlu diperhatikan.

I. Menyusun URL untuk Mendapatkan Kode Otorisasi

Struktur Dasar URL Otorisasi

URL otorisasi adalah URL yang digunakan oleh klien ketika mengirimkan permintaan ke server otorisasi. URL ini terdiri dari beberapa bagian berikut:

https://<authorization-server-domain>/oauth?
    response_type=<response_type>&
    clientId=<client_id>&
    redirectUri=<redirect_uri>&
    scope=<scope>&
    state=<state>

Penjelasan Parameter

Langkah penyusunan alamat otorisasi

1. Tentukan alamat server otorisasi Lingkungan sandbox adalah: https://account-sml.esignglobal.com/oauth

   Lingkungan produksi adalah: https://account.esignglobal.com/oauth

2. Atur nilai parameter Berdasarkan kebutuhan sebenarnya, atur nilai setiap parameter. Berikut adalah contohnya:
   • response_type: code
   • clientId: your-client-id-12345
   • redirectUri: https://your-app.com/callback
   • scope: signature
   • state: random-state-value
3. Menggabungkan parameter kueri Setelah menambahkan parameter di atas dalam bentuk pasangan kunci-nilai ke alamat server otorisasi, gunakan & untuk menghubungkan setiap parameter. Perhatikan bahwa nilai parameter perlu dikodekan URL.

   Contoh hasil penggabungan:

   https://account-sml.esignglobal.com/oauth?
       response_type=code&
       clientId=your-client-id-12345&
       redirectUri=https%3A%2F%2Fyour-app.com%2Fcallback&
       scope=signature&
       state=random-state-value

4. Verifikasi hasil penggabungan Pastikan alamat yang telah digabungkan memenuhi persyaratan berikut:
   • Urutan parameter dapat bersifat bebas
   • Nilai parameter telah dikodekan URL dengan benar
   • Semua parameter wajib telah disertakan

Kode contoh

Berikut adalah kode contoh untuk menggabungkan alamat otorisasi dalam beberapa bahasa pemrograman umum:

Contoh Python

import urllib.parse

# 定义参数
base_url = "https://account-sml.esignglobal.com/oauth"
params = {
    "response_type": "code",
    "clientId": "your-client-id-12345",
    "redirectUri": "https://your-app.com/callback",
    "scope": "signature",
    "state": "random-state-value"
}

# 拼接地址
query_string = urllib.parse.urlencode(params)
authorization_url = f"{base_url}?{query_string}"
print(authorization_url)

Contoh JavaScript

// 定义参数
const baseUrl = "https://account-sml.esignglobal.com/oauth";
const params = new URLSearchParams({
    response_type: "code",
    clientId: "your-client-id-12345",
    redirectUri: "https://your-app.com/callback",
    scope: "signature",
    state: "random-state-value"
});

// 拼接地址
const authorizationUrl = `${baseUrl}?${params.toString()}`;
console.log(authorizationUrl);

Contoh Java

import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

public class OAuthUrlBuilder {

    public static void main(String[ ] args) throws Exception {

        // 定义参数
        String baseUrl = "https://account-sml.esignglobal.com/oauth";
        String responseType = "code";
        String clientId = "your-client-id-12345";
        String redirectUri = "https://your-app.com/callback";
        String scope = "signature";
        String state = "random-state-value";

        // 拼接查询参数
        String queryString = String.format(
            "response_type=%s&clientId=%s&redirectUri=%s&scope=%s&state=%s",
            URLEncoder.encode(responseType, StandardCharsets.UTF_8),
            URLEncoder.encode(clientId, StandardCharsets.UTF_8),
            URLEncoder.encode(redirectUri, StandardCharsets.UTF_8),
            URLEncoder.encode(scope, StandardCharsets.UTF_8),
            URLEncoder.encode(state, StandardCharsets.UTF_8)
        );

        // 生成完整的授权地址
        String authorizationUrl = baseUrl + "?" + queryString;
        System.out.println(authorizationUrl);
    }
}

Catatan Penting

Saat menyusun dan menggunakan alamat otorisasi, perhatikan poin-poin berikut:

1. Kebenaran pengkodean URL Semua nilai parameter harus melalui pengkodean URL (percent-encoding）， agar karakter khusus (seperti :、/、? dll.) tidak merusak struktur URL. Misalnya, https://your-app.com/callback harus dikodekan menjadi https%3A%2F%2Fyour-app.com%2Fcallback。
2. Konsistensi alamat callbackredirect_uri Nilai parameter harus sepenuhnya konsisten dengan alamat callback yang terdaftar klien di server otorisasi, termasuk protokol (http atau https）、 nama host, port, dan jalur. Jika tidak, server otorisasi akan menolak permintaan.
3. state Keamanan parameterstate Parameter digunakan untuk mencegah serangan pemalsuan permintaan lintas situs (CSRF). Klien harus menghasilkan string acak dan tidak dapat diprediksi, dan memverifikasi dalam callback setelah pengguna menyelesaikan otorisasi bahwa state apakah nilainya konsisten dengan nilai yang awalnya dikirim.
4. Kewajaran cakupan izinscope Parameter mendefinisikan cakupan izin yang diminta klien. Cakupan izin minimal harus dipilih sesuai kebutuhan aktual untuk menghindari permintaan berlebihan atas sumber daya pengguna, sehingga meningkatkan kepercayaan pengguna.
5. Pembedaan Lingkungan Pada tahap pengembangan dan pengujian, biasanya menggunakan lingkungan sandbox (sepika account-sml.esignglobal.com）， setelah peluncuran resmi, perlu beralih ke lingkungan produksi (sepika account.esignglobal.com）， pastikan menggunakan alamat server otorisasi yang benar di berbagai lingkungan.
6. Pemrosesan Informasi Setelah Otorisasi Berhasil Setelah otorisasi selesai, layanan otorisasi eSignGlobal akan melaluiredirect_urimenyambungkan dan mengembalikancodedanbaseUrl， melaluibaseUrldapat mengidentifikasi pusat data tempat data pemberi otorisasi berada. Saat melakukan permintaan openapi, permintaan harus dikirimkan sesuai dengan pusat data yang relevan.
7. Penanganan Kesalahan Jika pengguna menolak otorisasi atau terjadi kesalahan lain, server otorisasi akan melalui redirect_uri mengembalikan informasi kesalahan (sepika error dan error_description parameter), klien harus menangani kesalahan ini dengan baik dan memberikan umpan balik yang jelas kepada pengguna.