Panduan Integrasi Mod Kod Kebenaran OAuth2.0

Jujukan panggilan

Gambaran keseluruhan

OAuth 2.0 ialah protokol kebenaran yang digunakan secara meluas, membolehkan aplikasi pihak ketiga mengakses sumber pengguna melalui kebenaran pengguna tanpa mendedahkan kelayakan pengguna. Dalam mod kod kebenaran OAuth 2.0, klien perlu mengarahkan pengguna untuk mengakses titik akhir kebenaran (Authorization Endpoint) pelayan pengesahan bagi mendapatkan kebenaran pengguna.

Dokumen ini bertujuan untuk menerangkan secara terperinci cara menyusun dan menggunakan URL kebenaran mengikut protokol OAuth 2.0, serta menyediakan contoh praktikal dan nota penting.

Satu. Menyusun URL untuk mendapatkan kod kebenaran

Struktur asas URL kebenaran

URL kebenaran ialah URL yang digunakan oleh klien semasa menghantar permintaan kepada pelayan pengesahan. Ia terdiri daripada beberapa bahagian berikut:

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

Penerangan parameter

Langkah menyusun alamat pengesahan

1. Tentukan alamat pelayan pengesahan Persekitaran sandbok ialah: https://account-sml.esignglobal.com/oauth

   Persekitaran pengeluaran ialah: https://account.esignglobal.com/oauth

2. Tetapkan nilai parameter Berdasarkan keperluan sebenar, tetapkan nilai setiap parameter. Berikut adalah contoh:
   • response_type: code
   • clientId: your-client-id-12345
   • redirectUri: https://your-app.com/callback
   • scope: signature
   • state: random-state-value
3. Sambungkan parameter pertanyaan Selepas menyambungkan parameter di atas dalam bentuk pasangan kunci-nilai ke alamat pelayan pengesahan, gunakan & untuk menyambungkan setiap parameter. Perhatikan bahawa nilai parameter perlu dikodkan URL.

   Contoh hasil penyambungan:

   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. Sahkan hasil penyambungan Pastikan alamat yang telah disambungkan memenuhi syarat berikut:
   • Susunan parameter adalah fleksibel
   • Nilai parameter telah dikodkan URL dengan betul
   • Semua parameter wajib telah disertakan

Kod contoh

Berikut adalah kod contoh untuk menyambungkan alamat pengesahan dalam beberapa bahasa pengaturcaraan biasa:

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);
    }
}

Perhatian

Semasa membina dan menggunakan URL pengesahan, sila ambil perhatian kepada perkara berikut:

1. Ketepatan pengekodan URL Semua nilai parameter mesti melalui pengekodan URL (percent-encoding) untuk memastikan aksara khas (seperti :、/、? dll.) tidak akan merosakkan struktur URL. Sebagai contoh, https://your-app.com/callback perlu dienkod sebagai https%3A%2F%2Fyour-app.com%2Fcallback。
2. Keselarasan alamat pelayar balikredirect_uri Nilai parameter mesti sama sepenuhnya dengan alamat pelayar balik yang didaftarkan oleh klien pada pelayan pengesahan, termasuk protokol (http atau https) nama hos, port dan laluan. Jika tidak, pelayan pengesahan akan menolak permintaan tersebut.
3. state Keselamatan parameter state Parameter digunakan untuk mencegah serangan pemalsuan permintaan merentas laman web (CSRF). Klien harus menjana rentetan rawak dan tidak dapat diramal, dan mengesahkan dalam panggilan balik selepas pengguna menyelesaikan pengesahan bahawa state nilai sama dengan nilai yang dihantar pada mulanya.
4. Kesesuaian julat keizinanscope Parameter menentukan julat keizinan yang diminta oleh klien. Julat keizinan minimum harus dipilih berdasarkan keperluan sebenar untuk mengelakkan permintaan berlebihan terhadap sumber pengguna, sekaligus meningkatkan kepercayaan pengguna.
5. Pembezaan Persekitaran Pada peringkat pembangunan dan pengujian, biasanya menggunakan persekitaran sandbok (seperti account-sml.esignglobal.com）， selepas pelancaran rasmi, perlu beralih ke persekitaran pengeluaran (seperti account.esignglobal.com）， pastikan alamat pelayan kebenaran yang tepat digunakan dalam persekitaran yang berbeza.
6. Pemprosesan Maklumat Selepas Kebenaran Berjaya Setelah proses kebenaran selesai, perkhidmatan kebenaran eSignGlobal akan melaluiredirect_uridigabungkan dan dipulangkancodedanbaseUrl， melaluibaseUrlboleh mengenal pasti pusat data tempat data pihak yang memberi kebenaran berada, semasa melaksanakan permintaan openapi, permintaan mesti dibuat berdasarkan pusat data yang berkaitan.
7. Pengendalian Ralat Jika pengguna menolak kebenaran atau berlaku ralat lain, pelayan kebenaran akan melalui redirect_uri memulangkan maklumat ralat (seperti error dan error_description parameter), klien perlu mengendalikan ralat ini dengan sewajarnya dan memberikan maklum balas yang jelas kepada pengguna.