คู่มือการผสานรวม OAuth2.0 แบบโหมดรหัสการอนุญาต

ลำดับขั้นตอนการเรียกใช้

ภาพรวม

OAuth 2.0 เป็นโปรโตคอลการอนุญาตที่ใช้กันอย่างแพร่หลาย ซึ่งอนุญาตให้แอปพลิเคชันของบุคคลที่สามเข้าถึงทรัพยากรของผู้ใช้ผ่านการได้รับอนุญาตจากผู้ใช้ โดยไม่ต้องเปิดเผยข้อมูลรับรองของผู้ใช้ ในโหมดรหัสการอนุญาตของ OAuth 2.0 ไคลเอนต์จะต้องนำผู้ใช้ไปยังจุดสิ้นสุดการอนุญาต (Authorization Endpoint) ของเซิร์ฟเวอร์การอนุญาต เพื่อขอรับสิทธิ์การอนุญาตจากผู้ใช้

เอกสารนี้จัดทำขึ้นเพื่ออธิบายรายละเอียดวิธีการสร้างและใช้งาน URL สำหรับการอนุญาตตามโปรโตคอล OAuth 2.0 พร้อมตัวอย่างจริงและข้อควรระวัง

หนึ่ง. การสร้าง URL เพื่อรับรหัสการอนุญาต

โครงสร้างพื้นฐานของ URL สำหรับการอนุญาต

URL สำหรับการอนุญาตคือ URL ที่ไคลเอนต์ใช้ในการส่งคำขอไปยังเซิร์ฟเวอร์การอนุญาต ประกอบด้วยองค์ประกอบต่อไปนี้:

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

คำอธิบายพารามิเตอร์

ขั้นตอนการสร้าง URL สำหรับการอนุญาต

1. กำหนดที่อยู่เซิร์ฟเวอร์การอนุญาต สภาพแวดล้อมแซนด์บ็อกซ์คือ: https://account-sml.esignglobal.com/oauth

   สภาพแวดล้อมจริงคือ: https://account.esignglobal.com/oauth

2. ตั้งค่าค่าพารามิเตอร์ ตามความต้องการใช้งานจริง ให้ตั้งค่าค่าของแต่ละพารามิเตอร์ ตัวอย่างด้านล่างนี้:
   • response_type: code
   • clientId: your-client-id-12345
   • redirectUri: https://your-app.com/callback
   • scope: signature
   • state: random-state-value
3. การต่อพารามิเตอร์การค้นหา หลังจากนำพารามิเตอร์ข้างต้นมาต่อท้ายที่อยู่เซิร์ฟเวอร์การอนุญาตในรูปแบบคู่คีย์-ค่าแล้ว ให้ใช้ & เพื่อเชื่อมแต่ละพารามิเตอร์ โปรดทราบว่าค่าพารามิเตอร์ต้องทำการเข้ารหัส URL

   ตัวอย่างผลลัพธ์การต่อพารามิเตอร์:

   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. ตรวจสอบผลลัพธ์การต่อพารามิเตอร์ ตรวจสอบให้แน่ใจว่าที่อยู่หลังการต่อพารามิเตอร์เป็นไปตามข้อกำหนดต่อไปนี้:
   • ลำดับของพารามิเตอร์สามารถเรียงลำดับใดก็ได้
   • ค่าพารามิเตอร์ได้รับการเข้ารหัส URL อย่างถูกต้องแล้ว
   • พารามิเตอร์ที่จำเป็นทั้งหมดถูกรวมอยู่ครบถ้วนแล้ว

ตัวอย่างโค้ด

ต่อไปนี้คือตัวอย่างโค้ดสำหรับการต่อที่อยู่การอนุญาตในภาษาโปรแกรมทั่วไปบางภาษา:

ตัวอย่าง 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)

ตัวอย่าง 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);

ตัวอย่าง 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);
    }
}

ข้อควรทราบ

เมื่อทำการประกอบและใช้งาน URL สำหรับการอนุญาต ควรระวังประเด็นต่อไปนี้:

1. ความถูกต้องของการเข้ารหัส URL ค่าพารามิเตอร์ทั้งหมดต้องผ่านการเข้ารหัส URL （percent-encoding）เพื่อให้แน่ใจว่าอักขระพิเศษ（เช่น :、/、? ฯลฯ）ไม่ทำลายโครงสร้างของ URL ตัวอย่างเช่นhttps://your-app.com/callback ควรเข้ารหัสเป็น https%3A%2F%2Fyour-app.com%2Fcallback。
2. ความสอดคล้องของที่อยู่การเรียกกลับ (Redirect URI)redirect_uri ค่าของพารามิเตอร์ต้องตรงกับที่อยู่การเรียกกลับที่ลงทะเบียนไว้กับเซิร์ฟเวอร์การอนุญาตอย่างสมบูรณ์ รวมถึงโปรโตคอล（http หรือ https) ชื่อโฮสต์ พอร์ต และพาธ มิฉะนั้น เซิร์ฟเวอร์การอนุญาตจะปฏิเสธคำขอ。
3. state ความปลอดภัยของพารามิเตอร์state พารามิเตอร์นี้ใช้เพื่อป้องกันการโจมตีแบบ Cross-Site Request Forgery (CSRF) ไคลเอนต์ควรสร้างสตริงแบบสุ่มและคาดเดาไม่ได้ และหลังจากผู้ใช้ดำเนินการอนุญาตเสร็จสิ้น ให้ตรวจสอบค่าในจุดเรียกกลับว่า state ตรงกับค่าที่ส่งไปตอนแรกหรือไม่。
4. ความเหมาะสมของขอบเขตสิทธิ์ (Scope)scope พารามิเตอร์นี้กำหนดขอบเขตสิทธิ์ที่ไคลเอนต์ร้องขอ ควรเลือกขอบเขตสิทธิ์ที่น้อยที่สุดตามความต้องการจริง เพื่อหลีกเลี่ยงการร้องขอทรัพยากรของผู้ใช้เกินจำเป็น ซึ่งจะช่วยเพิ่มความไว้วางใจจากผู้ใช้。
5. การจำแนกสภาพแวดล้อม ในช่วงการพัฒนาและทดสอบ มักจะใช้สภาพแวดล้อมแบบแซนด์บ็อกซ์ (เช่น account-sml.esignglobal.com）หลังจากการเปิดให้บริการจริง จำเป็นต้องสลับไปใช้สภาพแวดล้อมการผลิต (เช่น ,account.esignglobal.com）เพื่อให้มั่นใจว่าใช้ที่อยู่เซิร์ฟเวอร์การอนุญาตที่ถูกต้องในแต่ละสภาพแวดล้อม
6. การประมวลผลข้อมูลหลังการอนุญาตสำเร็จ หลังจากการอนุญาตเสร็จสิ้น บริการอนุญาตของ eSignGlobal จะดำเนินการผ่านredirect_uriการต่อพ่วงและส่งกลับcodeและbaseUrl โดยผ่านbaseUrlสามารถระบุศูนย์ข้อมูลที่จัดเก็บข้อมูลของผู้ได้รับอนุญาตได้ เมื่อทำการส่งคำขอ OpenAPI จะต้องส่งคำขอไปยังศูนย์ข้อมูลที่สอดคล้องกัน
7. การจัดการข้อผิดพลาด หากผู้ใช้ปฏิเสธการอนุญาตหรือเกิดข้อผิดพลาดอื่น ๆ เซิร์ฟเวอร์การอนุญาตจะส่งข้อมูลกลับมาผ่าน redirect_uri เพื่อแจ้งข้อมูลข้อผิดพลาด (เช่น error และ error_description พารามิเตอร์) ไคลเอนต์ควรจัดการข้อผิดพลาดเหล่านี้อย่างเหมาะสม และแสดงข้อความตอบกลับที่ชัดเจนให้แก่ผู้ใช้