Mobile-ID · Digital Trust
ISO/IEC 27001 · FIDO2 · OpenID — Xem phạm vi
Mobile-ID Sign · TÍCH HỢP VÀ TÀI LIỆU

Trusted SIC — Cấp quyền và ký hash

Tài liệu biên tập theo bản Compact 1.7.261001, có migration, nguồn từng operation và giới hạn contract.

Mức bao phủ và điều kiện tích hợp

Tài liệu có dẫn nguồn; mức xác nhận đặc tả, thử nghiệm sandbox và nghiệm thu production là các bước độc lập. Việc đổi phiên bản website không thay thế xác nhận tích hợp.

Xem mức bao phủ của từng operation
Trạng thái theo operation
OperationMức tài liệuĐặc tảSandbox
POST /v2/auth/loginTrường chọn lọcChưa có xác nhận triển khaiChưa kiểm thử
POST /v2/auth/revokeTrường chọn lọcChưa có xác nhận triển khaiChưa kiểm thử
POST /v2/credentials/issueTrường chọn lọcChưa có xác nhận triển khaiChưa kiểm thử
POST /v2/credentials/listTrường chọn lọcChưa có xác nhận triển khaiChưa kiểm thử
POST /v2/credentials/infoTrường chọn lọcChưa có xác nhận triển khaiChưa kiểm thử
POST /v2/credentials/authorizeTrường chọn lọcChưa có xác nhận triển khaiChưa kiểm thử
POST /v2/signatures/signHashTrường chọn lọcChưa có xác nhận triển khaiChưa kiểm thử
POST /v2/owner/managementTrường chọn lọcChưa có xác nhận triển khaiChưa kiểm thử
Tải OpenAPI đúng phạm vi · Tải Postman đọc đặc tả

Phạm vi bản Compact

Nguồn: Trusted SIC 1.7.261001, “Compact document”. Danh mục có 8 REST operation, 3 view, 3 loại redirect và 4 loại callback. OpenAPI biên tập các trường chọn lọc, chưa phải cấu trúc dữ liệu đầy đủ hoặc hợp đồng API vận hành thực tế đã nghiệm thu.

Từ credential tới tài liệu đã kiểm chứng

  1. Chọn credential và kiểm tra cơ chế cấp quyền
  2. Tạo digest từ đúng phiên bản tài liệu
  3. authorize: Nhận token giao diện, chưa có chữ ký
  4. Người dùng xác nhận; backend nhận SAD theo contract
  5. signHash: Nhận signature data hoặc mã theo dõi
  6. Assembling → kiểm chứng → lưu tài liệu và bằng chứng

202 Accepted ở authorize chỉ xác nhận yêu cầu đã được tiếp nhận. Passkey là cơ chế xác thực/cấp quyền trong hành trình được mô tả; không phải chứng thư hoặc chữ ký số.

Migration từ 1.7.260928

SIC migration
OperationBản mớiHành động
/v2/auth/login, /v2/auth/revokeCó trong CompactBổ sung danh mục và trường chọn lọc; chưa có fixture bí mật.
/v2/credentials/issue, list, info, authorizeCó trong CompactĐối chiếu lại schema, mode và namespace theo bản mới.
/v2/signatures/signHash, /v2/owner/managementCó trong CompactTách cấp quyền khỏi ký và hoàn thiện tài liệu.
providers / package / issueCheck / authorizeCheck / signPolling / historyKhông được mô tả trong CompactGiữ tài liệu 1.7.260928 riêng; không kết luận đã loại bỏ.

Đặc tả API có nguồn

POST/v2/auth/login

Xác thực ứng dụng

Có nguồn · Đặc tả triển khai chưa xác nhận · Chưa kiểm thử sandbox

Nguồn: Trusted SIC 1.7.261001 (Compact document) · PDF 6 · trường chọn lọc

Điều kiện: Xác nhận phạm vi triển khai, cách xác thực và quyền sử dụng với Mobile-ID. Giữ token và dữ liệu ký phía máy chủ; không chạy từ trang demo.

Xác thực theo nguồn: Basic

Đầu vào — Trường được mô tả

Content-Type: application/json

Các trường được biên tập từ nguồn
TrườngKiểu dữ liệuĐiều kiệnÝ nghĩa và giới hạn
refresh_tokenstringCó điều kiệnThông tin làm mới có điều kiện; cần xác nhận cách chọn Basic hoặc refresh.
rememberMestringTùy chọnBảng nguồn ghi String nhưng ví dụ dùng Boolean.

HTTP 200

Các trường được biên tập từ nguồn
TrườngKiểu dữ liệuĐiều kiệnÝ nghĩa và giới hạn
access_tokenstringBắt buộcToken ứng dụng; lưu phía máy chủ.
refresh_tokenstringTùy chọnToken làm mới.
expires_inintegerTùy chọnThời hạn access_token tính bằng giây; nguồn §3.1.1, PDF 7.

Điểm cần xác nhận: SIC12-LOGIN

POST/v2/auth/revoke

Thu hồi token ứng dụng

Có nguồn · Đặc tả triển khai chưa xác nhận · Chưa kiểm thử sandbox

Nguồn: Trusted SIC 1.7.261001 (Compact document) · PDF 8 · trường chọn lọc

Điều kiện: Xác nhận phạm vi triển khai, cách xác thực và quyền sử dụng với Mobile-ID. Giữ token và dữ liệu ký phía máy chủ; không chạy từ trang demo.

Xác thực theo nguồn: Bearer

Đầu vào — Trường được mô tả

Content-Type: application/json

Các trường được biên tập từ nguồn
TrườngKiểu dữ liệuĐiều kiệnÝ nghĩa và giới hạn
tokenstringBắt buộcToken cần thu hồi.
token_type_hintstringTùy chọnGợi ý loại token.
POST/v2/credentials/issue

Phát hành credential

Có nguồn · Đặc tả triển khai chưa xác nhận · Chưa kiểm thử sandbox

Nguồn: Trusted SIC 1.7.261001 (Compact document) · PDF 9 · trường chọn lọc

Điều kiện: Xác nhận phạm vi triển khai, cách xác thực và quyền sử dụng với Mobile-ID. Giữ token và dữ liệu ký phía máy chủ; không chạy từ trang demo.

Xác thực theo nguồn: Bearer

Đầu vào — Trường được mô tả

Content-Type: application/json

Các trường được biên tập từ nguồn
TrườngKiểu dữ liệuĐiều kiệnÝ nghĩa và giới hạn
aliasstringTùy chọnTên thay thế tùy chọn.
citizenIdstringCó điều kiệnBắt buộc có điều kiện khi phát hành đồng bộ; mã chế độ đang mâu thuẫn.
packageIdstringCó điều kiệnBắt buộc có điều kiện khi phát hành đồng bộ.
operationModestring · S, ATùy chọnBảng issue: S bất đồng bộ / A đồng bộ; bảng kết quả có mô tả khác.
sharedModestringTùy chọnMô hình chia sẻ theo cấu hình đã thống nhất.
SCALstring · 1, 2Tùy chọnMức liên kết theo nguồn; không phải tuyên bố chứng nhận.
agreementUUIDstringTùy chọnDữ liệu thỏa thuận phía gọi.
viewobjectTùy chọn
view.langstring · VI, ENTùy chọnNgôn ngữ giao diện.
view.expiresInintegerTùy chọnĐơn vị chưa rõ trong nguồn; không tự suy thời hạn.
view.callbackUrlstringTùy chọnURL nhận kết quả tại máy chủ.
view.redirectUrlstringTùy chọnURL chuyển hướng trình duyệt; không phải bằng chứng hoàn tất.
view.fontSizestringTùy chọnCỡ chữ trong giao diện.
view.templateUiIdstringTùy chọnMã mẫu giao diện.

HTTP default

Các trường được biên tập từ nguồn
TrườngKiểu dữ liệuĐiều kiệnÝ nghĩa và giới hạn
tokenstringCó điều kiệnToken giao diện khi dùng UI; điều kiện trả về cần xác nhận.

Điểm cần xác nhận: SIC12-MODE, SIC12-VIEW

POST/v2/credentials/list

Liệt kê credential của chủ thể

Có nguồn · Đặc tả triển khai chưa xác nhận · Chưa kiểm thử sandbox

Nguồn: Trusted SIC 1.7.261001 (Compact document) · PDF 13 · trường chọn lọc

Điều kiện: Xác nhận phạm vi triển khai, cách xác thực và quyền sử dụng với Mobile-ID. Giữ token và dữ liệu ký phía máy chủ; không chạy từ trang demo.

Xác thực theo nguồn: Bearer

Tham số

Tham số thao tác API
TênVị tríBắt buộcKiểu dữ liệu
x-page-noheaderKhôngstring
x-records-per-pageheaderKhôngstring

Đầu vào — Trường được mô tả

Content-Type: application/json

Các trường được biên tập từ nguồn
TrườngKiểu dữ liệuĐiều kiệnÝ nghĩa và giới hạn
userIDstringBắt buộcMã định danh chủ thể credential.
credentialInfobooleanTùy chọnKèm thông tin credential.
certificatesstring · none, single, chainTùy chọnLựa chọn chuỗi chứng thư.
certInfobooleanTùy chọnKèm trường thông tin chứng thư.
authInfobooleanTùy chọnKèm cơ chế cấp quyền.
onlyValidbooleanTùy chọnLọc credential có thể sử dụng; không phải kết quả kiểm chứng chữ ký.
langstring · VI, ENTùy chọnNgôn ngữ kết quả.

HTTP 200

Các trường được biên tập từ nguồn
TrườngKiểu dữ liệuĐiều kiệnÝ nghĩa và giới hạn
credentialIDsarrayBắt buộcCác mã credential.
credentialInfosarrayCó điều kiệnThông tin credential có điều kiện; schema một phần.
Ví dụ tổng hợp — Không gọi API
{
  "userID": "DEMO-OWNER",
  "certificates": "single",
  "onlyValid": true
}

Điểm cần xác nhận: SIC12-NAMESPACE

POST/v2/credentials/info

Kiểm tra credential trước cấp quyền

Có nguồn · Đặc tả triển khai chưa xác nhận · Chưa kiểm thử sandbox

Nguồn: Trusted SIC 1.7.261001 (Compact document) · PDF 18 · trường chọn lọc

Điều kiện: Xác nhận phạm vi triển khai, cách xác thực và quyền sử dụng với Mobile-ID. Giữ token và dữ liệu ký phía máy chủ; không chạy từ trang demo.

Xác thực theo nguồn: Bearer

Đầu vào — Trường được mô tả

Content-Type: application/json

Các trường được biên tập từ nguồn
TrườngKiểu dữ liệuĐiều kiệnÝ nghĩa và giới hạn
credentialIDstringBắt buộcMã credential; phân biệt với chứng thư và giao dịch.
certificatesstring · none, single, chainTùy chọnLựa chọn chuỗi chứng thư.
certInfobooleanTùy chọnKèm thông tin chứng thư.
authInfobooleanTùy chọnKèm cơ chế cấp quyền.
langstringTùy chọnNgôn ngữ kết quả.

HTTP 200

Các trường được biên tập từ nguồn
TrườngKiểu dữ liệuĐiều kiệnÝ nghĩa và giới hạn
multisignstringTùy chọnSố chữ ký tối đa: Bảng ghi String nhưng ví dụ dùng số.
SCALstring · 1, 2Tùy chọnMức liên kết hash/SAD.
Ví dụ tổng hợp — Không gọi API
{
  "credentialID": "DEMO-CREDENTIAL",
  "certInfo": true
}

Điểm cần xác nhận: SIC12-MULTISIGN

POST/v2/credentials/authorize

Cấp quyền cho đúng các digest

Có nguồn · Đặc tả triển khai chưa xác nhận · Chưa kiểm thử sandbox

Nguồn: Trusted SIC 1.7.261001 (Compact document) · PDF 22 · trường chọn lọc

Điều kiện: Xác nhận phạm vi triển khai, cách xác thực và quyền sử dụng với Mobile-ID. Giữ token và dữ liệu ký phía máy chủ; không chạy từ trang demo.

Xác thực theo nguồn: Bearer

Đầu vào — Trường được mô tả

Content-Type: application/json

Các trường được biên tập từ nguồn
TrườngKiểu dữ liệuĐiều kiệnÝ nghĩa và giới hạn
credentialIDstringBắt buộcMã credential; phân biệt với chứng thư và giao dịch.
numSignaturesintegerBắt buộcSố chữ ký yêu cầu; không suy giới hạn chưa công bố.
documentDigestsobjectBắt buộcDigest cần liên kết với cấp quyền.
documentDigests.hashesarrayBắt buộcCác digest Base64 được liên kết với cấp quyền.
documentDigests.hashAlgorithmOIDstringBắt buộcOID thuật toán digest; phải khớp dịch vụ ký.
descriptionstringTùy chọnMô tả giao dịch cho người dùng.
agreementUUIDstringTùy chọnDữ liệu thỏa thuận phía gọi.
usernamestringTùy chọnTên người dùng trong phiên quản lý.
clientInfoobjectTùy chọn
clientInfo.applicationstringTùy chọnTên ứng dụng.
viewobjectTùy chọn
view.langstring · VI, ENTùy chọnNgôn ngữ giao diện.
view.expiresInintegerTùy chọnĐơn vị chưa rõ trong nguồn; không tự suy thời hạn.
view.callbackUrlstringTùy chọnURL nhận kết quả tại máy chủ.
view.redirectUrlstringTùy chọnURL chuyển hướng trình duyệt; không phải bằng chứng hoàn tất.
view.fontSizestringTùy chọnCỡ chữ trong giao diện.
view.templateUiIdstringTùy chọnMã mẫu giao diện.

HTTP 202

Các trường được biên tập từ nguồn
TrườngKiểu dữ liệuĐiều kiệnÝ nghĩa và giới hạn
tokenstringBắt buộcToken mở giao diện cấp quyền. Đây chưa phải SAD.
Ví dụ tổng hợp — Không gọi API
{
  "credentialID": "DEMO-CREDENTIAL",
  "numSignatures": 1,
  "documentDigests": {
    "hashes": [
      "ypeBEsobvcr6wjGzmiPcTaeG7/gUfE5yuYB3ha/uSLs="
    ],
    "hashAlgorithmOID": "2.16.840.1.101.3.4.2.1"
  }
}

Điểm cần xác nhận: SIC12-VIEW, SIC12-EXPIRES, SIC12-SAD

POST/v2/signatures/signHash

Ký digest đã được cấp quyền

Có nguồn · Đặc tả triển khai chưa xác nhận · Chưa kiểm thử sandbox

Nguồn: Trusted SIC 1.7.261001 (Compact document) · PDF 24 · trường chọn lọc

Điều kiện: Xác nhận phạm vi triển khai, cách xác thực và quyền sử dụng với Mobile-ID. Giữ token và dữ liệu ký phía máy chủ; không chạy từ trang demo.

Xác thực theo nguồn: Bearer

Đầu vào — Trường được mô tả

Content-Type: application/json

Các trường được biên tập từ nguồn
TrườngKiểu dữ liệuĐiều kiệnÝ nghĩa và giới hạn
credentialIDstringBắt buộcMã credential; phân biệt với chứng thư và giao dịch.
SADstringBắt buộcSignature Activation Data sau cấp quyền; lưu phía máy chủ.
hashesarrayBắt buộcDigest Base64 cần ký; phải khớp đầu vào đã cấp quyền.
hashAlgorithmOIDstringBắt buộcOID thuật toán digest.
signAlgostringBắt buộcMã thuật toán ký: Bảng bắt buộc nhưng ví dụ nguồn thiếu.
operationModestring · A, STùy chọnBảng sign: A bất đồng bộ / S đồng bộ; không dùng chung cách diễn giải với issue.
validityUeriodintegerTùy chọnGiữ cách viết trong nguồn; thời hạn tính bằng mili giây. Không tự đổi tên.
responseUristringTùy chọnURI nhận kết quả theo operation ký.

HTTP default

Các trường được biên tập từ nguồn
TrườngKiểu dữ liệuĐiều kiệnÝ nghĩa và giới hạn
signaturesarrayCó điều kiệnDữ liệu chữ ký; hoàn thiện tài liệu là bước riêng.
responseIDstringCó điều kiệnMã kết quả bất đồng bộ; không thay thế requestID.

Điểm cần xác nhận: SIC12-SIGNALGO, SIC12-SPELLING, SIC12-POLLING

POST/v2/owner/management

Mở quản lý chủ thể

Có nguồn · Đặc tả triển khai chưa xác nhận · Chưa kiểm thử sandbox

Nguồn: Trusted SIC 1.7.261001 (Compact document) · PDF 26 · trường chọn lọc

Điều kiện: Xác nhận phạm vi triển khai, cách xác thực và quyền sử dụng với Mobile-ID. Giữ token và dữ liệu ký phía máy chủ; không chạy từ trang demo.

Xác thực theo nguồn: Bearer

Đầu vào — Trường được mô tả

Content-Type: application/json

Các trường được biên tập từ nguồn
TrườngKiểu dữ liệuĐiều kiệnÝ nghĩa và giới hạn
usernamestringTùy chọnTên người dùng cho phiên quản lý.
viewobjectTùy chọn
view.langstring · VI, ENTùy chọnNgôn ngữ giao diện.
view.expiresInintegerTùy chọnĐơn vị chưa rõ trong nguồn; không tự suy thời hạn.
view.callbackUrlstringTùy chọnURL nhận kết quả tại máy chủ.
view.redirectUrlstringTùy chọnURL chuyển hướng trình duyệt; không phải bằng chứng hoàn tất.
view.fontSizestringTùy chọnCỡ chữ trong giao diện.
view.templateUiIdstringTùy chọnMã mẫu giao diện.

HTTP 200

Các trường được biên tập từ nguồn
TrườngKiểu dữ liệuĐiều kiệnÝ nghĩa và giới hạn
tokenstringBắt buộcToken giao diện quản lý.
expires_inintegerBắt buộcGiá trị thời hạn token.

Điểm cần xác nhận: SIC12-VIEW, SIC12-EXPIRES

Danh mục và mức bao phủ

Tám operation REST với cấu trúc trường chọn lọc; ba giao diện, ba redirect và bốn callback được mô tả riêng.

Operation theo Specification
Phương thứcĐường dẫnMức bao phủPDF
POST/v2/auth/loginTrường chọn lọc6
POST/v2/auth/revokeTrường chọn lọc8
POST/v2/credentials/issueTrường chọn lọc9
POST/v2/credentials/listTrường chọn lọc13
POST/v2/credentials/infoTrường chọn lọc18
POST/v2/credentials/authorizeTrường chọn lọc22
POST/v2/signatures/signHashTrường chọn lọc24
POST/v2/owner/managementTrường chọn lọc26

View, redirect và callback

Kênh nhận kết quả
KênhÝ nghĩaNguồn
GET /view/authorize/{token}Giao diện cấp quyềnSIC §2.2.1
GET /view/manage/{token}Giao diện quản lýSIC §2.2.2
GET /view/certificate/{token}Giao diện chứng thưSIC §2.2.3
Redirect result={base64}3 loại: Cấp quyền, quản lý, phát hành. Base64 là encoding, không chứng minh nguồn gửi.SIC §4
Callback → backend4 loại: Cấp quyền, quản lý, phát hành, ký. Trường và trạng thái phải đối chiếu theo từng loại.SIC §5

Callback cần kiểm tra nguồn gửi theo contract, lưu bền vững trước xác nhận, chống xử lý trùng và đối soát khi thiếu/sai thứ tự. Không dùng redirect trên trình duyệt làm bằng chứng ký hoàn tất. Compact chưa đủ căn cứ để đặt header chữ ký, lịch retry hoặc endpoint polling mới.

Điểm cần xác nhận trước tích hợp

SIC12-MODE · SIC §3.1.3 và §3.1.7

Issue diễn giải S/A ngược signHash và bảng kết quả issue.

Chưa hướng dẫn chọn mode cho production.

SIC12-NAMESPACE · SIC §3.1.4

Danh mục /v2 khác ví dụ /csc/v2.

Giữ path danh mục, gắn vấn đề; xác nhận base URL.

SIC12-SIGNALGO · SIC §3.1.7

SignAlgo bắt buộc nhưng ví dụ nguồn thiếu.

Không phát hành fixture signHash đầy đủ giả.

SIC12-SAD · SIC §3.1.7, §4.1, §5.1

SAD được mở rộng bằng hai thuật ngữ.

Giữ identifier SAD, cần xác nhận định nghĩa thống nhất.

SIC12-EXPIRES · Tham số view của SIC, callback

ExpiresIn có mô tả đơn vị mâu thuẫn; expires_in xuất hiện ở ví dụ.

Không tự đổi trường hoặc suy thời hạn.

SIC12-MULTISIGN · SIC §3.1.5

Multisign String trong bảng, số trong ví dụ.

Schema giữ kiểu bảng và ghi rõ vấn đề.

SIC12-SPELLING · SIC §3.1.7

Nguồn dùng validityUeriod.

Giữ identifier nguồn; không âm thầm sửa chính tả API.

SIC12-VIEW · SIC §3.1.6 và sơ đồ Viewer

202 authorize mô tả token; sơ đồ có token và viewURL.

Token chưa phải SAD; URL mở UI phải xác nhận.

SIC12-POLLING · SIC Compact, lịch sử V11

Compact không mô tả polling/history/provider/package.

Giữ phiên bản cũ riêng; không suy API đã bị loại bỏ.

SIC12-CALLBACK · SIC §§4–5

Callback có JSON, tên trường và code/status không nhất quán.

Không dùng payload nguồn lỗi như ví dụ runnable.

SIC12-LOGIN · SIC §3.1.1

RememberMe String trong bảng nhưng ví dụ Boolean; chọn refresh/Basic chưa rõ.

Giới hạn schema và không có fixture xác thực hoàn chỉnh.

Đối chiếu với thao tác trên Viewer

Xem bản ghi đúng tuyến, đọc kết quả và phần lược bỏ, rồi đối chiếu operation. Video không thay contract hoặc báo cáo kiểm chứng.

Xem bảy bản ghi Viewer/VNeID

Xác thực ứng dụng và mã truy vết

§3.1.1, PDF 6–7 mô tả Basic cho lần đăng nhập và access_token cho các request tiếp theo, x-billcode-id ở response, expires_in tính bằng giây. Cách thay Basic bằng refresh_token và kiểu rememberMe vẫn cần đối chiếu do nguồn chưa nhất quán.

Thông tin xác thực ứng dụng được xử lý ở backend; đăng nhập ứng dụng không thay consent ký hoặc SAD.

Tìm kiếm Mobile-ID Sign

Tìm kiếm cục bộ trong gói ngoại tuyến.