Chuyển tới nội dung chính

Đăng nhập một lần cho bản cài đặt on-premise

Trang này dành cho người vận hành bản cài đặt MonoChat on-premise. Trang giải thích cách cho phép nhân viên đăng nhập bằng nhà cung cấp danh tính (IdP) của công ty qua OpenID Connect (OIDC), ví dụ Microsoft Entra ID, Okta, Keycloak, AD FS hoặc Google Workspace.

Đăng nhập một lần được thiết lập cho toàn bộ bản cài đặt trong cài đặt máy chủ, không theo từng tổ chức. Một tài khoản MonoChat có thể thuộc nhiều tổ chức, và mọi người đăng nhập trước khi chọn một tổ chức. Đăng nhập cho bạn một tài khoản, không phải quyền truy cập: một người chỉ thấy một tổ chức sau khi tổ chức đó mời họ và cấp cho họ một vai trò.

Cách đăng nhập hoạt động​

Khi ai đó nhấp vào nút SSO trên trang đăng nhập, MonoChat mở trang đăng nhập của IdP trong một cửa sổ bật lên. Sau khi người đó đăng nhập ở đó, IdP đưa trình duyệt trở lại MonoChat kèm một mã dùng một lần. Máy chủ MonoChat đổi mã lấy ID token và kiểm tra token trước khi cho người đó đăng nhập:

  • Các endpoint và khóa ký của IdP được đọc từ tài liệu discovery của nó, <issuer>/.well-known/openid-configuration, ở mỗi lần đăng nhập.
  • Đăng nhập dùng luồng authorization code với PKCE (S256), một state và một nonce. Một yêu cầu đăng nhập có hiệu lực 10 phút và chỉ dùng được một lần.
  • ID token phải được ký bằng một trong các khóa của IdP và chứa issuer của bạn (iss), client ID của bạn (aud), nonce của yêu cầu và thời điểm hết hạn (exp) chưa qua.
  • ID token phải chứa địa chỉ email của người đó (email). Đăng nhập bị từ chối khi IdP cho biết địa chỉ chưa được xác minh (email_verified: false).

1. Đăng ký MonoChat tại nhà cung cấp danh tính​

Tạo một ứng dụng (client) cho MonoChat tại IdP của bạn với các giá trị sau:

Cài đặt tại IdPGiá trị
Loại ứng dụngỨng dụng web có client secret (client bảo mật)
URI chuyển hướng đăng nhậphttps://<your MonoChat domain>/api/oauth/oidc/redirect
Loại grantAuthorization code
Scopeopenid email profile
Xác thực client tại endpoint tokenClient secret gửi bằng xác thực HTTP Basic (client_secret_basic)

Đảm bảo ID token chứa claim email. Ghi lại client ID, client secret và issuer. Issuer là giá trị issuer trong tài liệu discovery của IdP. Các dạng thường gặp:

Nhà cung cấp danh tínhIssuer
Microsoft Entra IDhttps://login.microsoftonline.com/<tenant id>/v2.0
Oktahttps://<your Okta domain>/oauth2/default, hoặc https://<your Okta domain>
Keycloakhttps://<your Keycloak host>/realms/<realm>
AD FS (2016 trở lên)https://<your AD FS host>/adfs
Google Workspacehttps://accounts.google.com

Mở <issuer>/.well-known/openid-configuration trong trình duyệt và sao chép chính xác giá trị issuer, kể cả dấu / ở cuối nếu có. MonoChat từ chối cho bất kỳ ai đăng nhập khi hai giá trị khác nhau.

2. Thêm cài đặt​

Thêm các khối oidc vào cài đặt máy chủ và khởi động lại MonoChat. Khối công khai nằm dưới public.oauth, khối bí mật nằm dưới oauth:

{
  "oauth": {
    "oidc": {
      "clientSecret": "<client secret>",
      "autoCreateAccounts": true,
      "allowedEmailDomains": ["company.com"]
    }
  },
  "public": {
    "oauth": {
      "oidc": {
        "issuer": "https://login.microsoftonline.com/<tenant id>/v2.0",
        "clientId": "<client id>",
        "redirectPath": "/api/oauth/oidc/redirect",
        "scope": "openid email profile",
        "buttonLabel": "Sign in with Company SSO"
      }
    }
  }
}
Cài đặtTác dụng
public.oauth.oidc.issuerIssuer từ bước 1
public.oauth.oidc.clientIdClient ID từ bước 1
public.oauth.oidc.redirectPathĐường dẫn của URI chuyển hướng từ bước 1
public.oauth.oidc.scopeCác scope MonoChat yêu cầu
public.oauth.oidc.buttonLabelVăn bản của nút đăng nhập. Để trống sẽ hiển thị "Đăng nhập bằng SSO" theo ngôn ngữ của người dùng
oauth.oidc.clientSecretClient secret. Chỉ nằm trên máy chủ
oauth.oidc.autoCreateAccountstrue tạo tài khoản MonoChat ở lần đăng nhập SSO đầu tiên của một người, kể cả khi chỉ đăng ký được bằng lời mời (public.disableSignup)
oauth.oidc.allowedEmailDomainsChỉ những người có địa chỉ email thuộc một trong các tên miền này mới đăng nhập được bằng SSO. Bỏ trống để cho phép mọi tên miền

Sau đó nút SSO xuất hiện trên trang đăng nhập.

Ai có thể đăng nhập​

  • Người mới. Với autoCreateAccounts: true, lần đăng nhập SSO đầu tiên của một người sẽ tạo tài khoản của họ. Nếu không có, tài khoản chỉ được tạo khi public.disableSignup tắt hoặc người đó đăng nhập từ một lời mời.
  • Người đã có tài khoản với cùng địa chỉ email. Với oauth.autoMerge: true, lần đăng nhập SSO đầu tiên liên kết SSO với tài khoản hiện có, nhưng chỉ khi ID token cho biết địa chỉ đã được xác minh (email_verified: true). Nếu không, và luôn luôn khi không có autoMerge, MonoChat yêu cầu người đó đăng nhập bằng mật khẩu một lần rồi liên kết SSO với tài khoản lúc đó; chấp nhận lời mời vào một tổ chức cũng liên kết SSO. Microsoft Entra ID và AD FS không gửi email_verified, vì vậy với hai IdP này, hãy tiếp tục cho phép đăng nhập bằng mật khẩu cho đến khi mọi người đã liên kết SSO, hoặc mời lại họ.
  • Tên miền được phép. Với allowedEmailDomains, địa chỉ thuộc tên miền khác sẽ bị từ chối. Với Google Workspace (issuer https://accounts.google.com), MonoChat kiểm tra claim hd, tức tên miền Workspace của tài khoản, thay vì địa chỉ email, vì tài khoản Google cá nhân có thể dùng địa chỉ thuộc bất kỳ tên miền nào.

Đặt SSO làm cách đăng nhập duy nhất​

  1. Đặt public.auth.methods thành ["oidc"]. Khi đó trang đăng nhập chỉ hiển thị nút SSO, và máy chủ từ chối đăng nhập bằng mật khẩu và mạng xã hội.
  2. Người dùng root super (người dùng có vai trò root super trong tổ chức gốc) vẫn có thể đăng nhập bằng mật khẩu tại /auth/signin?fallback=1, để bản cài đặt không bao giờ bị khóa khi IdP ngừng hoạt động.
  3. Để ngăn các tài khoản SSO mới tự mở tổ chức riêng, đặt public.disableTenantCreation thành true. Khi đó chỉ những người có vai trò phù hợp trong một tổ chức mới tạo được tổ chức bên dưới nó.

Mạng​

  • Giữ /api/oauth/oidc/authorize và redirectPath của bạn truy cập được với những người đăng nhập. Cả hai đều mở trong trình duyệt của họ.
  • Máy chủ MonoChat phải truy cập được tài liệu discovery, endpoint token và bộ khóa (jwks_uri) của IdP qua HTTPS.

Giới hạn​

  • Ứng dụng di động MonoChat chưa hỗ trợ SSO. Nếu bạn đặt SSO làm cách đăng nhập duy nhất, nhân viên hỗ trợ sẽ không đăng nhập được vào ứng dụng di động.
  • Đăng xuất khỏi MonoChat không đăng xuất người đó khỏi IdP, và đăng xuất khỏi IdP hiện chưa đăng xuất họ khỏi MonoChat.

Kiểm tra thiết lập​

  1. Mở trang đăng nhập và nhấp vào nút SSO. Đăng nhập tại IdP; cửa sổ bật lên đóng lại và bạn đã đăng nhập vào MonoChat.
  2. Đăng nhập bằng một người chưa có tài khoản MonoChat và xác nhận tài khoản được tạo (hoặc bị từ chối, nếu bạn chưa bật autoCreateAccounts).
  3. Nếu bạn đã đặt allowedEmailDomains, hãy thử với một người thuộc tên miền khác và xác nhận đăng nhập bị từ chối.
  4. Nếu bạn đã đặt public.auth.methods, hãy xác nhận đăng nhập bằng mật khẩu bị từ chối, và người dùng root super vẫn đăng nhập được tại /auth/signin?fallback=1.