Cơ sở tri thức
DANH MỤC
Thiết lập đăng nhập
Giữ nguyên cài đặt mặc định không xác thực để sử dụng cục bộ, hoặc bật OIDC để nhóm của bạn đăng nhập bằng nhà cung cấp danh tính của bạn.
Đăng nhập vào TrueForge là tùy chọn. Bạn có thể chạy nó mà không cần xác thực để sử dụng cá nhân, cục bộ, hoặc kết nối với nhà cung cấp danh tính OIDC (Okta, Microsoft Entra ID, hoặc bất kỳ nhà cung cấp danh tính OIDC tiêu chuẩn nào) để nhóm của bạn đăng nhập và cài đặt vẫn chỉ dành cho quản trị viên.
Chọn chế độ của bạn
| Cách thức | Khi nào nên sử dụng | Những gì người dùng nhìn thấy |
|---|---|---|
| Không cần đăng nhập (mặc định) | Mạng cục bộ npxhoặc mạng mà bạn hoàn toàn tin tưởng. |
Không có màn hình đăng nhập; mọi người đều là quản trị viên cục bộ dùng chung duy nhất. |
| Đăng nhập OIDC | Triển khai nhóm được lưu trữ hoặc chia sẻ | Đăng nhập bằng tài khoản IdP của bạn; mỗi người là một adminhoặc mộtuser |
Phương án A — tắt chức năng đăng nhập
Mặc định. Không cần thiết lập bất kỳ OIDC_*biến nào, chạy TrueForge như bình thường ( Khởi động nhanh ), và mở giao diện người dùng — không có màn hình đăng nhập, và Cài đặt cũng như trò chuyện sẽ có sẵn ngay lập tức.
1. Đăng ký ứng dụng với nhà cung cấp danh tính của bạn:
Tạo một ứng dụng OIDC (trên web) bảo mật . Bất kể nhà cung cấp nào, bạn cần:
- Mã ủy quyền loại cấp phép (PKCE cũng được sử dụng)
- URI chuyển hướng:
https://<trueforge-url>/api/v1/auth/callback, trong đó<trueforge-url>là địa chỉ công khai của phiên bản TrueForge của bạn (cùng giá trị bạn đã đặt làPUBLIC_BASE_URL) - Người dùng hoặc nhóm được phép đăng nhập
- Mã định danh (ID token) chứa thông tin về tư cách thành viên nhóm/vai trò, giúp TrueForge phân biệt quản trị viên với người dùng thông thường.
TrueForge sử dụng chuẩn OIDC, vì vậy bất kỳ nhà cung cấp danh tính nào phát hành mã thông báo định danh đều có thể sử dụng được. Chọn nhà cung cấp của bạn để biết các bước cụ thể:
2. Thiết lập môi trường máy chủ
Hãy thiết lập cả ba biến OIDC bắt buộc cùng lúc – cấu hình không đầy đủ sẽ khiến quá trình khởi động thất bại – cộng thêm nguồn gốc công cộng.
| Biến | Yêu cầu | Mục đích |
|---|---|---|
| Đúng | Người dùng nguồn gốc công cộng và IdP thấy (không có đường dẫn theo sau) | |
OIDC_ISSUER_URL |
Đúng | Nhà phát hành IdP (khám phá tại /.well-known/openid-configuration) |
OIDC_CLIENT_ID |
Đúng | ID máy khách OIDC |
OIDC_CLIENT_SECRET |
Đúng | mã bí mật của máy khách OIDC |
OIDC_USER_REFERENCE_CLAIM |
Không (mặc định sub) |
Thông tin xác nhận được sử dụng làm ID người dùng để xác định quyền sở hữu phiên. |
OIDC_USER_DISPLAY_NAME_CLAIM |
Không (mặc định name) |
Yêu cầu được sử dụng làm tên hiển thị của người dùng |
OIDC_USER_ROLE_CLAIM |
Không (mặc định groups) |
Yêu cầu tư cách thành viên quản trị đã được kiểm tra. |
OIDC_ADMIN_ROLE_VALUE |
Không (mặc định admin) |
Chuỗi ký tự chính xác cấp quyền admin(phân biệt chữ hoa chữ thường) |
OIDC_SCOPES |
Không (mặc định openid,profile,email) |
Phạm vi của yêu cầu ủy quyền |
OIDC_ALLOWED_EMAILS |
KHÔNG | Danh sách cho phép các email chính xác và/hoặc *các mẫu ký tự đại diện (ví dụ: alice@acme.com,*@partner.com) được phân tách bằng dấu phẩy. Khi được thiết lập, chỉ các mã định danh có emailthông tin xác thực khớp với một mục nhập mới được phép đăng nhập. Để trống / không được thiết lập = không bị hạn chế. Việc so khớp không phân biệt chữ hoa chữ thường. |
Cách bạn truyền các tham số này phụ thuộc vào cách bạn chạy TrueForge:
3. Đăng nhập và xác minh vai trò
- Mở giao diện người dùng – bạn sẽ được chuyển hướng đến trang đăng nhập IdP của mình.
- Sau khi đăng nhập, hãy xác nhận rằng quản trị viên mới thấy phần Cài đặt, còn người dùng không phải quản trị viên thì không.
- Nếu ai đó mong đợi quyền quản trị nhưng lại nhận được quyền khác
user, hãy giải mã mã định danh của họ và kiểm tra giá trị yêu cầu vai trò (phải khớp chính xác, phân biệt chữ hoa chữ thường). Hãy đăng xuất và đăng nhập lại sau bất kỳ thay đổi nào về yêu cầu của nhà cung cấp danh tính.
Vai trò: quản trị viên so với người dùng
Mỗi người dùng đã đăng nhập tương ứng với chính xác một vai trò, được xác định bởi thông tin vai trò trong mã định danh của họ.
| Vai trò | Ai | Có thể trò chuyện và sử dụng trợ lý ảo. | Có thể thay đổi cài đặt |
|---|---|---|---|
| quản trị viên | Yêu cầu vai trò chứaOIDC_ADMIN_ROLE_VALUE |
Đúng | Đúng vậy — mô hình, trình kết nối, kỹ năng, hộp cát |
| người dùng | Tất cả những người khác có thể đăng nhập | Đúng | Không — Cài đặt bị ẩn |
Để gọi API HTTP hoặc SDK đối với máy chủ có bật tính năng đăng nhập, hãy truyền mã định danh – xem phần Lấy mã và kết nối.
Khắc phục sự cố
| Triệu chứng | Nguyên nhân có thể xảy ra |
|---|---|
no_matching_policy/ Đánh giá chính sách thất bại |
Chính sách truy cập máy chủ ủy quyền không bao gồm máy khách, quyền cấp phép, phạm vi hoặc người dùng này (Okta). |
You are not allowed to access this app |
Người dùng chưa được chỉ định cho ứng dụng hoặc chính sách đăng nhập của ứng dụng từ chối cho phép họ đăng nhập. |
invalid client secret |
Ứng dụng này là ứng dụng SPA/công khai — hãy tạo lại nó thành một ứng dụng web (bí mật) với mã bí mật của khách hàng. |
Màn hình xác thực trống khi yêu cầugroups |
Máy chủ ủy quyền tùy chỉnh thiếu groupsthông tin về phạm vi và/hoặc nhóm mã định danh (Okta) |
Đăng nhập thành công nhưng mọi người đều…role: "user" |
Thông tin nhóm/vai trò bị thiếu trong mã định danh, tên yêu cầu không chính xác hoặc giá trị quản trị không khớp (phân biệt chữ hoa chữ thường) |
SDK trả về401 |
OIDC đang hoạt động và yêu cầu không có mã định danh hoặc cookie phiên. |
Đăng nhập thất bại với lỗi login_failed/ API trả về 401sau khi triển khai danh sách cho phép. |
Yêu cầu của người gọi emailnằm ngoài phạm vi cho phép OIDC_ALLOWED_EMAILS, hoặc mã định danh không có emailyêu cầu nào trong khi danh sách cho phép được thiết lập. Các lỗi vẫn giữ nguyên tính chất chung chung để danh sách cho phép không được tiết lộ. |
Danh sách kiểm tra an ninh
- Lưu trữ
OIDC_CLIENT_SECRETtrong trình quản lý bí mật; đừng bao giờ tiết lộ nó. - Không nên để lộ triển khai không có OIDC trên mạng internet công cộng.
- Hãy ghi lại URL gọi lại chính xác mà người dùng của bạn truy cập (scheme + host).
MỤC LỤC
