Kiến trúc tổng quát

flowchart LR
    Cli["Công cụ dòng lệnh"] --> Loopback["HTTP server tạm<br/>127.0.0.1:cổng ngẫu nhiên"]
    Cli --> TrinhDuyet["Trình duyệt mặc định"]
    TrinhDuyet --> TrangPheDuyet["Trang phê duyệt<br/>/ezylogin/cli/authorize"]
    Cli --> ApiToken["API đổi token<br/>/ezylogin/api/v1/cli/..."]

    TrangPheDuyet --> KiemTra["Bộ kiểm tra tham số<br/>và cài đặt"]
    ApiToken --> KiemTra
    TrangPheDuyet --> KhoMa["Kho mã uỷ quyền<br/>(meta của tài khoản)"]
    ApiToken --> KhoMa
    ApiToken --> KhoToken["Access token<br/>của EzyPlatform"]
    ApiToken --> KhoPhien["Phiên đăng nhập<br/>của EzyLogin"]

Toàn bộ luồng đăng nhập

sequenceDiagram
    autonumber
    participant Cli as Công cụ dòng lệnh
    participant Browser as Trình duyệt
    participant EzyLogin as EzyLogin
    participant Kho as Kho dữ liệu

    Cli->>Cli: Tạo code_verifier, code_challenge, state
    Cli->>Cli: Mở HTTP server tạm trên 127.0.0.1
    Cli->>Browser: Mở /ezylogin/cli/authorize?...
    Browser->>EzyLogin: GET /ezylogin/cli/authorize
    alt Chưa đăng nhập
        EzyLogin->>Browser: Yêu cầu đăng nhập (kể cả xác thực hai lớp)
        Browser->>EzyLogin: Đăng nhập rồi quay lại trang phê duyệt
    end
    EzyLogin->>EzyLogin: Kiểm tra cài đặt và tham số
    EzyLogin->>Browser: Hiển thị trang phê duyệt
    Browser->>EzyLogin: POST /ezylogin/cli/authorize/approve
    EzyLogin->>EzyLogin: Kiểm tra lại cài đặt và tham số
    EzyLogin->>Kho: Lưu SHA-256 của mã uỷ quyền kèm code_challenge, redirect_uri, hạn 2 phút
    EzyLogin->>Browser: Redirect tới redirect_uri?code=...&state=...
    Browser->>Cli: GET http://127.0.0.1:cổng/callback?code=...&state=...
    Cli->>Cli: So khớp state
    Cli->>EzyLogin: POST API đổi token {code, codeVerifier, redirectUri}
    EzyLogin->>Kho: Lấy và xoá mã uỷ quyền
    EzyLogin->>EzyLogin: Kiểm tra hạn, redirectUri, PKCE, trạng thái tài khoản
    EzyLogin->>Kho: Tạo access token và phiên đăng nhập
    EzyLogin->>Cli: {accessToken, accessTokenExpiredAt, accessTokenStatus}

Chặng phê duyệt trên trình duyệt

Bắt buộc có phiên đăng nhập

Kiểm tra cài đặt và tham số

• Chỉ chấp nhận loopback: danh sách host được cố định trong mã nguồn, không phụ thuộc cấu hình. Kẻ xấu không thể gửi cho nạn nhân một đường dẫn phê duyệt có redirect_uri trỏ về máy chủ của mình, vì EzyLogin sẽ từ chối ngay từ bước hiển thị.
• Chỉ chấp nhận S256: phương thức plain của PKCE bị loại bỏ, vì với plain thì code_challenge chính là code_verifier và việc lộ đường dẫn phê duyệt đồng nghĩa với lộ bí mật.
• code_challenge đúng 43 ký tự: đó là độ dài của SHA-256 (32 byte) khi mã hoá base64url không có =, nên mọi giá trị khác chắc chắn không phải là một challenge hợp lệ.
• Kiểm tra lại khi phê duyệt: các tham số được gửi lại qua form ẩn, nên EzyLogin kiểm tra lại toàn bộ ở request POST thay vì tin vào lần kiểm tra trước.

1. Tên công cụ lấy từ client_name, chỉ dùng để hiển thị và được lưu kèm mã uỷ quyền.
2. Quyền mà công cụ sẽ nhận: tương đương với tài khoản đang phê duyệt.
3. Cảnh báo an toàn nhắc người dùng chỉ phê duyệt khi chính mình vừa chạy lệnh đăng nhập.
4. Địa chỉ nhận kết quả là redirect_uri đã qua kiểm tra, để người dùng tự đối chiếu.
5. Huỷ chỉ quay lại trang trước trên trình duyệt, không tạo mã uỷ quyền nào; Phê duyệt gửi request POST để tạo mã.

Tạo và lưu mã uỷ quyền

flowchart LR
    Ma["Mã uỷ quyền<br/>(chỉ gửi cho trình duyệt)"] --> Bam["SHA-256"]
    Bam --> Khoa["meta_value<br/>= hash của mã"]
    Meta["meta_key<br/>= ezyloginCliAuthorizationCode"] --- Khoa
    Khoa --- NoiDung["meta_text_value<br/>= JSON clientName, redirectUri,<br/>codeChallenge, expiredAt"]

• meta_key cố định là ezyloginCliAuthorizationCode.
• meta_value là SHA-256 của mã uỷ quyền, dùng làm khoá tra cứu duy nhất. Kể cả khi cơ sở dữ liệu bị lộ, kẻ xấu cũng không thể khôi phục lại mã từ giá trị này.
• meta_text_value là JSON chứa clientName, redirectUri, codeChallenge và expiredAt (thời điểm tạo cộng 2 phút).

Chặng đổi mã uỷ quyền lấy access token

Thứ tự kiểm tra

flowchart TD
    BatDau["POST API đổi token"] --> CaiDat{"Cài đặt CLI login<br/>đang bật?"}
    CaiDat -- "Không" --> Loi403["403 cliLogin: notAllowed"]
    CaiDat -- "Có" --> DinhDang{"code, codeVerifier, redirectUri<br/>đúng định dạng?"}
    DinhDang -- "Không" --> Loi400a["400 theo từng trường"]
    DinhDang -- "Có" --> LayMa["Giải mã chủ sở hữu từ code,<br/>tìm theo SHA-256 của code<br/>và XOÁ bản ghi ngay"]
    LayMa --> TonTai{"Tìm thấy?"}
    TonTai -- "Không" --> Loi400b["400 code: invalid"]
    TonTai -- "Có" --> HetHan{"Còn hạn 2 phút?"}
    HetHan -- "Không" --> Loi400b
    HetHan -- "Có" --> Uri{"redirectUri trùng khớp?"}
    Uri -- "Không" --> Loi400b
    Uri -- "Có" --> Pkce{"BASE64URL(SHA256(codeVerifier))<br/>= codeChallenge?"}
    Pkce -- "Không" --> Loi400b
    Pkce -- "Có" --> Owner{"Tài khoản còn<br/>hoạt động?"}
    Owner -- "Không" --> Loi400c["400 owner: invalid"]
    Owner -- "Có" --> CapToken["Tạo access token và phiên đăng nhập"]

• code_verifier được kiểm tra định dạng trước: dài từ 43 đến 128 ký tự và chỉ gồm A-Z a-z 0-9 - . _ ~, đúng như RFC 7636 quy định.
• Mã bị xoá trước khi kiểm tra: EzyLogin lấy và xoá bản ghi trong cùng một bước, sau đó mới so hạn, redirectUri và PKCE. Vì vậy mỗi mã chỉ có đúng một cơ hội: một request đổi token sai (dù sai codeVerifier) cũng làm mã mất hiệu lực, kẻ xấu không thể thử đi thử lại nhiều code_verifier với cùng một mã.
• So sánh PKCE trong thời gian không đổi: code_challenge tính lại từ code_verifier được so với giá trị đã lưu bằng phép so sánh constant-time, tránh rò rỉ thông tin qua thời gian phản hồi.
• Lỗi gộp chung: mã không tồn tại, hết hạn, đã dùng, sai redirectUri hay sai PKCE đều trả về cùng một lỗi code: invalid, để không tiết lộ cho bên gọi biết điều kiện nào đã sai.
• Trạng thái tài khoản được kiểm tra lúc đổi token: nếu tài khoản bị khoá trong khoảng thời gian giữa lúc phê duyệt và lúc đổi token, EzyLogin từ chối với owner: invalid.

Phát hành access token

• Loại token là access token thông thường của EzyPlatform (người dùng hoặc quản trị viên), nên mọi API, bộ lọc xác thực và phân quyền hiện có đều hoạt động với token này mà không cần thay đổi gì. Token của quản trị viên mang đúng các vai trò và quyền của tài khoản đó.
• Thời hạn lấy theo cài đặt Thời gian token hết hạn của EzyPlatform, dành cho người dùng hoặc dành cho quản trị viên.
• Trạng thái là ACTIVATED_2FA nếu tài khoản đã bật xác thực hai lớp, ngược lại là ACTIVATED. Token được đánh dấu đã qua xác thực hai lớp vì để phê duyệt, người dùng bắt buộc phải có phiên đăng nhập trên trình duyệt, mà phiên đó đã đi qua bước xác thực hai lớp.

Ghi phiên đăng nhập

• Địa chỉ IP được lấy theo cấu hình proxy của EzyPlatform (đọc từ header của reverse proxy khi máy chủ chạy sau proxy) và cắt tối đa 64 ký tự.
• User-Agent là header công cụ gửi lên, cắt tối đa 1200 ký tự. Đây là thông tin giúp người dùng và quản trị viên nhận ra phiên nào là của công cụ nào, vì vậy công cụ nên gửi một User-Agent có tên và phiên bản rõ ràng.

1. Phiên đăng nhập từ dòng lệnh xuất hiện trong EzyLogin → Các phiên người dùng như mọi phiên khác, với cột Tác nhân người dùng là User-Agent của công cụ. Đăng xuất phiên này sẽ thu hồi token tương ứng, mọi request sau đó dùng token này nhận lỗi 401.

Khác biệt giữa phía người dùng và phía quản trị viên

Các lớp bảo vệ