Gabay sa Integrasyon para sa OAuth2.0 Authorization Code Flow

Sunod-sunod na tawag

Pangkalahatang-ideya

Ang OAuth 2.0 ay isang malawakang ginagamit na authorization protocol na nagpapahintulot sa mga third-party application na ma-access ang mga resource gamit ang pahintulot ng gumagamit nang hindi kailangang ilantad ang kanilang credentials. Sa authorization code mode ng OAuth 2.0, kailangang gabayan ng client ang gumagamit na puntahan ang Authorization Endpoint ng authorization server upang makuha ang pahintulot.

Layunin ng dokumentong ito na detalyadong ipaliwanag kung paano buuin at gamitin ang authorization URL base sa OAuth 2.0 protocol, kasama ang mga praktikal na halimbawa at mga paalala.

I. Pagbuo ng URL para Makakuha ng Authorization Code

Pangunahing istruktura ng authorization URL

Ang authorization URL ay ang URL na ginagamit ng client kapag nagpapadhana ng request sa authorization server. Binubuo ito ng mga sumusunod na bahagi:

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

Paliwanag sa mga Parameter

Mga Hakbang sa Pagbuo ng Authorization URL

1. Tukuyin ang address ng authorization server Para sa sandbox environment: https://account-sml.esignglobal.com/oauth

   Para sa production environment: https://account.esignglobal.com/oauth

2. Magtakda ng halaga ng parameter Ayon sa aktwal na pangangailangan, itakda ang halaga ng bawat parameter. Narito ang isang halimbawa:
   • response_type: code
   • clientId: your-client-id-12345
   • redirectUri: https://your-app.com/callback
   • scope: signature
   • state: random-state-value
3. Pagsasama ng mga query parameter Pagkatapos i-konekta ang mga nabanggit na parameter sa anyong key-value pair sa authorization server address, gamitin ang & para ikonekta ang bawat parameter. Tandaan, kailangang i-URL encode ang mga value ng parameter.

   Halimbawa ng resulta ng pagbuo:

   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. I-validate ang resulta ng pagbuo Siguraduhing ang pinag-isang address ay sumusunod sa mga sumusunod na requirement:
   • Maaaring kahit anong order ng mga parameter
   • Tamang na-URL encode ang mga value ng parameter
   • Kasama ang lahat ng required na parameter

Halimbawa ng code

Narito ang mga halimbawa ng code para sa pagbuo ng authorization address sa iba't ibang karaniwang programming language:

Halimbawa sa 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)

Halimbawa sa 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);

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

Mga Paalala

Sa pagbuo at paggamit ng authorization address, tandaan ang mga sumusunod na punto:

1. Pagiging tama ng URL encoding Ang lahat ng halaga ng parameter ay dapat i-URL encode (percent-encoding), upang matiyak na ang mga espesyal na karakter (tulad ng ":、/、? atbp.) ay hindi masisira ang istruktura ng URL. Halimbawa,https://your-app.com/callback dapat i-encode bilang https%3A%2F%2Fyour-app.com%2Fcallback。
2. Pagkakapareho ng callback addressredirect_uri Ang halaga ng parameter ay dapat ganap na tugma sa callback address na nakarehistro ng client sa authorization server, kabilang ang protocol (http o https), hostname, port, at path. Kung hindi, tatanggihan ng authorization server ang request.
3. state Kaligtasan ng parameterstate Ginagamit ang parameter upang pigilan ang Cross-Site Request Forgery (CSRF) attacks. Dapat bumuo ang client ng random at hindi maiaasahang string, at pagkatapos makumpleto ng user ang authorization, suriin ang state halaga ay tugma sa orihinal na ipinadala na halaga.
4. Katwiran ng saklaw ng permissionsscope Ang parameter ay nagdefine ng saklaw ng permissions na hinihingi ng client. Dapat pumili ng pinakamaliit na saklaw ng permissions base sa aktwal na pangangailangan upang maiwasan ang sobrang paghingi ng resources ng user, kaya't mapapataas ang tiwala ng user.
5. Pagkakaiba ng Environment Sa yugto ng pag-unlad at pagsusuri, karaniwang ginagamit ang sandbox environment (tulad ng account-sml.esignglobal.com）， pagkatapos itong ilunsag nang buo, kailangang lumipat sa production environment (tulad ng account.esignglobal.com）， siguraduhing gumamit ng tamang address ng authorization server sa bawat environment.
6. Pagproseso ng Impormasyon Pagkatapos ng Matagumpay na Authorization Pagkatapos matapos ang authorization, ang eSignGlobal authorization service ay magpasa sa pamamagitan ngredirect_uripagbuo at pagbabalik ngcodeatbaseUrl， sa pamamagitan ngbaseUrlmaaaring kilalanin ang data center kung saan matatagpuan ang datos ng nag-authorize; kapag gumagawa ng openapi request, kailangang i-initiate ang request base sa katumbas na data center.
7. Pagtrato sa Error Kung tumanggi ang user sa authorization o mangyari ang ibang error, ang authorization server ay magpasa sa pamamagitan ng redirect_uri ang impormasyon ng error (tulad ng error at error_description parameter), dapat maayos na tratuhin ng client ang mga error na ito at magbigay ng malinaw na feedback sa user.