Hướng dẫn cài đặt và cấu hình plugin ký số VSS Declaration trên Cổng dịch vụ công BHXH
Cách cài đặt ứng dụng nền ký số VSS Declaration cho Cổng dịch vụ công BHXH dichvucong.baohiemxahoi.gov.vn: cài SSL, kiểm tra localhost:61505, bật TLS 1.2, tạo mẫu chữ ký, ký số từ xa và sửa lỗi.
Để ký số và nộp hồ sơ trên Cổng dịch vụ công BHXH Việt Nam (dichvucong.baohiemxahoi.gov.vn), máy tính cần cài VSS Declaration (Vietnam Social Security Declaration) – ứng dụng nền (plugin) ký số do BHXH Việt Nam phát hành. Ứng dụng chạy ngầm, cung cấp dịch vụ ký số trên localhost để trang dịch vụ công gọi tới USB Token hoặc chữ ký số từ xa. Bài viết hướng dẫn cài đặt, kiểm tra, cấu hình mẫu chữ ký và ký số từ xa theo tài liệu hướng dẫn của BHXH Việt Nam.
1. Chuẩn bị trước khi cài
- Máy tính Windows, tài khoản có quyền cài phần mềm (Administrator).
- USB Token và phần mềm quản lý Token (driver) đã cài, hoặc tài khoản chữ ký số từ xa nếu ký không cần Token.
- Trình duyệt cho phép trang web gọi ứng dụng trên máy (localhost). Chrome/Edge bản mới có thể hỏi quyền truy cập mạng cục bộ: chọn Cho phép.
- Bộ cài VSS Declaration bản mới nhất: tải bộ cài VSS Declaration tại chukyso.com (link gốc từ máy chủ BHXH, tự cập nhật khi có phiên bản mới).
2. Cài đặt VSS Declaration
- Chạy file bộ cài
vss-declaration-setup_[phiên bản].exe. Tại màn hình chào mừng, bấm Tiếp tục (Next).
Màn hình chào mừng: bấm Tiếp tục - Giữ thư mục cài đặt mặc định
C:\Program Files (x86)\Vietnam Social Security\..., bấm Tiếp tục.
Chọn thư mục cài đặt - Màn hình Sẵn sàng để cài đặt: bấm Cài đặt (Install).
Bấm Cài đặt - Windows hiện hộp thoại User Account Control: chọn Yes để cấp quyền quản trị. Chọn No sẽ hủy cài đặt.
Chọn Yes để cấp quyền Administrator - Chờ bộ cài chép file và cấu hình ứng dụng nền, không tắt cửa sổ khi thanh tiến trình đang chạy.
Chờ thanh tiến độ chạy xong - Khi thấy Hoàn tất quá trình cài đặt, giữ tích Chạy Vietnam Social Security Declaration sau khi kết thúc và bấm Kết thúc. Ứng dụng nền tự khởi động.
Bấm Kết thúc để hoàn tất
3. Cấu hình sau khi cài (quan trọng)
Mọi chức năng nằm trong menu chuột phải của biểu tượng VSS Declaration ở khay hệ thống (góc phải thanh Taskbar, bấm mũi tên ^ nếu không thấy).
3.1. Cài đặt SSL
Nhấp chuột phải vào biểu tượng > Cài đặt SSL. Bước này cài chứng chỉ để trình duyệt kết nối an toàn (https) tới ứng dụng nền; bỏ qua bước này trang dịch vụ công có thể không nhận ứng dụng ký số.
3.2. Kiểm tra ứng dụng nền đã chạy
- Nhấp chuột phải vào biểu tượng > Mở trình duyệt.
Chuột phải biểu tượng > Mở trình duyệt - Trình duyệt mở trang
http://localhost:61505/swaggerhoặchttps://localhost:61505/swagger. Thấy danh sách API là ứng dụng nền đã chạy thành công.
Trang Swagger hiển thị danh sách API là đã chạy
Không mở được trang này: kiểm tra ứng dụng đã chạy chưa, phần mềm diệt virus/tường lửa có chặn cổng 61505 không, thử thoát hẳn ứng dụng rồi mở lại. Máy dùng Windows 7 thì làm thêm mục 3.3.
3.3. Bật TLS 1.2 (chỉ Windows 7)
- Nhấp chuột phải vào biểu tượng > Trợ giúp > Bật TLS 12 trên Win 7.
Trợ giúp > Bật TLS 12 trên Win 7 - Khi báo thành công, bấm OK để khởi động lại máy (bắt buộc để Windows nhận cấu hình mới).
3.4. Tạo mẫu chữ ký
- Nhấp chuột phải vào biểu tượng > Cấu hình.
Chuột phải biểu tượng > Cấu hình - Màn hình Cấu hình chữ ký: bấm Thêm mới.
Bấm Thêm mới để tạo mẫu - Nhập Tên mẫu, chọn kiểu hiển thị (hình ảnh và thông tin, hình ảnh, thông tin), tải ảnh chữ ký/con dấu, tích các thông tin hiển thị (người ký, email, cơ quan, chức danh, thời gian ký) và kích thước, rồi bấm Lưu.
Nhập thông tin mẫu và bấm Lưu
4. Ký số từ xa (không cần USB Token)
4.1. Cấu hình kết nối
Trong Cấu hình chữ ký, mở tab Cấu hình ký từ xa và điều chỉnh nếu mạng chậm: thời gian chờ phản hồi API ký số, số lần thử lại khi lỗi kết nối, thời gian chờ giữa các lần thử. Bấm Lưu.
4.2. Ký số từ xa khi nộp hồ sơ trên Cổng dịch vụ công BHXH
- Ở cửa sổ chọn chứng thư khi ký, bấm Ký số từ xa.
Bấm Ký số từ xa - Chọn đúng tổ chức cung cấp dịch vụ chứng thực chữ ký số (nhà cung cấp chữ ký số từ xa), nhập tài khoản ký số từ xa rồi bấm Đồng ý.
Chọn nhà cung cấp, nhập tài khoản, bấm Đồng ý - Danh sách chứng thư hiện ra: chọn chứng thư cần ký, bấm Đồng ý và xác nhận ký trên ứng dụng điện thoại của nhà cung cấp (nếu được yêu cầu).
Chọn chứng thư và bấm Đồng ý
4.3. Ký số từ xa khi ký PDF trên Cổng tiếp nhận BHYT
- Trên thanh menu, bấm biểu tượng Chọn chứng thư.
Bấm Chọn chứng thư - Tại phần Chữ ký số từ xa, chọn Lấy danh sách chứng thư ký số từ xa, chọn nhà cung cấp và nhập tài khoản như mục 4.2.
Lấy danh sách chứng thư ký số từ xa - Bấm lại Chọn chứng thư, chọn chứng thư trong nhóm Chữ ký số từ xa để ký.
Chọn chứng thư trong nhóm Chữ ký số từ xa
5. Lỗi thường gặp và cách xử lý
| Hiện tượng | Nguyên nhân | Cách xử lý |
|---|---|---|
| Cổng báo không tìm thấy ứng dụng ký số | Ứng dụng nền chưa chạy, chưa cài SSL hoặc trình duyệt chặn localhost | Mở lại VSS Declaration, chạy Cài đặt SSL, cho phép truy cập mạng cục bộ trên trình duyệt, tải lại trang |
| Không mở được trang Swagger (localhost:61505) | Ứng dụng chưa chạy hoặc cổng bị chặn | Khởi động lại ứng dụng, kiểm tra tường lửa/diệt virus; Windows 7 bật TLS 1.2 (mục 3.3) |
| Windows hỏi quyền Administrator | Bộ cài cần quyền ghi file, cấu hình | Chọn Yes; máy công ty không có quyền thì nhờ bộ phận IT cài |
| Chứng thư không hiển thị | USB Token/driver chưa sẵn sàng | Cắm lại Token, kiểm tra phần mềm quản lý Token, chứng thư còn hạn |
| Ký bị hủy (cancelled) | Đóng hộp thoại chọn chứng thư hoặc không xác nhận trên điện thoại (ký từ xa) | Thực hiện lại và chọn chứng thư hợp lệ |
| Lỗi CryptographicException: An internal error occurred khi nộp tờ khai | USB Token/driver chưa sẵn sàng | Rút cắm lại Token, mở phần mềm quản lý Token, thử lại |
Cần hỗ trợ cài đặt, ký số BHXH từ xa miễn phí hoặc mua, gia hạn chữ ký số, liên hệ chukyso.com. Xem thêm bảng giá chữ ký số.
Nội dung tham khảo và ảnh minh họa trích từ tài liệu “Hướng dẫn cài đặt và sử dụng VSS Declaration” của BHXH Việt Nam; thông tin chứng thư trong ảnh đã được làm mờ.
