온프레미스 설치를 위한 싱글 사인온

이 페이지는 온프레미스 MonoChat 설치를 운영하는 관리자를 위한 것입니다. OpenID Connect(OIDC)를 통해 직원이 회사의 ID 공급자(IdP)로 로그인하도록 하는 방법을 설명합니다. 예를 들어 Microsoft Entra ID, Okta, Keycloak, AD FS 또는 Google Workspace입니다.

싱글 사인온은 조직별이 아니라 서버 설정에서 설치 전체에 대해 설정합니다. MonoChat 계정은 여러 조직에 속할 수 있으며, 조직을 선택하기 전에 로그인합니다. 로그인으로 얻는 것은 계정이지 접근 권한이 아닙니다. 조직이 초대하고 역할을 부여해야 그 사람에게 해당 조직이 보입니다.

로그인 페이지에서 SSO 버튼을 클릭하면 MonoChat이 IdP의 로그인 페이지를 팝업으로 엽니다. 그곳에서 로그인하면 IdP가 일회용 코드와 함께 브라우저를 MonoChat으로 돌려보냅니다. MonoChat 서버는 코드를 ID 토큰으로 교환하고, 로그인시키기 전에 토큰을 검증합니다.

IdP의 엔드포인트와 서명 키는 로그인할 때마다 디스커버리 문서 <issuer>/.well-known/openid-configuration에서 읽습니다.
로그인은 PKCE(S256), state, nonce를 사용하는 인가 코드 흐름을 사용합니다. 로그인 요청은 10분 동안 유효하며 한 번만 사용할 수 있습니다.
ID 토큰은 IdP의 키 중 하나로 서명되어 있어야 하며, issuer(iss), 클라이언트 ID(aud), 요청의 nonce, 아직 지나지 않은 만료 시간(exp)을 포함해야 합니다.
ID 토큰에는 사용자의 이메일 주소(email)가 있어야 합니다. IdP가 주소가 확인되지 않았다고(email_verified: false) 알리면 로그인이 거부됩니다.

1. ID 공급자에 MonoChat 등록하기

IdP에서 다음 값으로 MonoChat용 애플리케이션(클라이언트)을 만드세요.

IdP 설정	값
애플리케이션 유형	클라이언트 시크릿이 있는 웹 애플리케이션(기밀 클라이언트)
로그인 리디렉션 URI	`https://<your MonoChat domain>/api/oauth/oidc/redirect`
그랜트 유형	인가 코드(Authorization code)
스코프	`openid email profile`
토큰 엔드포인트의 클라이언트 인증	HTTP Basic 인증으로 보내는 클라이언트 시크릿(`client_secret_basic`)

ID 토큰에 email 클레임이 포함되도록 하세요. 클라이언트 ID, 클라이언트 시크릿, issuer를 기록해 두세요. issuer는 IdP 디스커버리 문서의 issuer 값입니다. 일반적인 형식:

ID 공급자	Issuer
Microsoft Entra ID	`https://login.microsoftonline.com/<tenant id>/v2.0`
Okta	`https://<your Okta domain>/oauth2/default` 또는 `https://<your Okta domain>`
Keycloak	`https://<your Keycloak host>/realms/<realm>`
AD FS(2016 이상)	`https://<your AD FS host>/adfs`
Google Workspace	`https://accounts.google.com`

브라우저에서 <issuer>/.well-known/openid-configuration을 열고 issuer 값을 끝의 /가 있다면 그것까지 정확히 복사하세요. 두 값이 다르면 MonoChat은 누구도 로그인시키지 않습니다.

2. 설정 추가하기

서버 설정에 oidc 블록을 추가하고 MonoChat을 다시 시작하세요. 공개 블록은 public.oauth 아래에, 비밀 블록은 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"
      }
    }
  }
}

설정	역할
`public.oauth.oidc.issuer`	1단계의 issuer
`public.oauth.oidc.clientId`	1단계의 클라이언트 ID
`public.oauth.oidc.redirectPath`	1단계 리디렉션 URI의 경로
`public.oauth.oidc.scope`	MonoChat이 요청하는 스코프
`public.oauth.oidc.buttonLabel`	로그인 버튼의 텍스트. 비워 두면 사용자의 언어로 "SSO로 로그인"이 표시됩니다
`oauth.oidc.clientSecret`	클라이언트 시크릿. 서버에만 보관됩니다
`oauth.oidc.autoCreateAccounts`	`true`이면 가입이 초대 전용(`public.disableSignup`)이어도 첫 SSO 로그인 때 MonoChat 계정을 만듭니다
`oauth.oidc.allowedEmailDomains`	이메일 주소가 이 도메인 중 하나에 있는 사람만 SSO로 로그인할 수 있습니다. 모든 도메인을 허용하려면 생략하세요

이제 로그인 페이지에 SSO 버튼이 나타납니다.

새로운 사람. autoCreateAccounts: true이면 첫 SSO 로그인에서 계정이 만들어집니다. 설정하지 않으면 public.disableSignup이 꺼져 있거나 초대에서 로그인한 경우에만 계정이 만들어집니다.
같은 이메일 주소로 이미 계정이 있는 사람. oauth.autoMerge: true이면 첫 SSO 로그인에서 SSO가 기존 계정에 연결됩니다. 단, ID 토큰이 주소가 확인되었다고(email_verified: true) 알릴 때만 연결됩니다. 그렇지 않거나 autoMerge를 설정하지 않으면 MonoChat이 한 번 비밀번호로 로그인하도록 요청하고 그때 SSO를 계정에 연결합니다. 조직의 초대를 수락해도 연결됩니다. Microsoft Entra ID와 AD FS는 email_verified를 보내지 않으므로, 이들을 사용할 때는 모든 사람이 SSO를 연결할 때까지 비밀번호 로그인을 허용해 두거나 사람들을 다시 초대하세요.
허용 도메인. allowedEmailDomains를 설정하면 다른 도메인의 주소는 거부됩니다. Google Workspace(issuer https://accounts.google.com)에서는 개인 Google 계정도 어떤 도메인의 주소든 쓸 수 있으므로, MonoChat은 이메일 주소 대신 계정의 Workspace 도메인인 hd 클레임을 확인합니다.

public.auth.methods를 ["oidc"]로 설정하세요. 그러면 로그인 페이지에는 SSO 버튼만 표시되고, 서버는 비밀번호와 소셜 로그인을 거부합니다.
root super 사용자(루트 조직에서 root super 역할을 가진 사용자)는 계속 /auth/signin?fallback=1에서 비밀번호로 로그인할 수 있으므로, IdP가 중단되어도 설치가 잠기지 않습니다.
새 SSO 계정이 자체 조직을 만들지 못하게 하려면 public.disableTenantCreation을 true로 설정하세요. 그러면 조직에서 적절한 역할을 가진 사람만 그 아래에 조직을 만들 수 있습니다.

네트워크

/api/oauth/oidc/authorize와 redirectPath는 로그인하는 사람이 접근할 수 있어야 합니다. 둘 다 그 사람의 브라우저에서 열립니다.
MonoChat 서버는 HTTPS로 IdP의 디스커버리 문서, 토큰 엔드포인트, 키 세트(jwks_uri)에 접근할 수 있어야 합니다.

제한 사항

MonoChat 모바일 앱은 아직 SSO를 지원하지 않습니다. SSO를 유일한 로그인 방법으로 만들면 상담원은 모바일 앱에 로그인할 수 없습니다.
MonoChat에서 로그아웃해도 IdP에서는 로그아웃되지 않으며, IdP에서 로그아웃해도 아직 MonoChat에서는 로그아웃되지 않습니다.

설정 확인하기

로그인 페이지를 열고 SSO 버튼을 클릭하세요. IdP에서 로그인하면 팝업이 닫히고 MonoChat에 로그인됩니다.
아직 MonoChat 계정이 없는 사람으로 로그인하여 계정이 만들어지는지(autoCreateAccounts를 켜지 않았다면 거부되는지) 확인하세요.
allowedEmailDomains를 설정했다면 다른 도메인의 사람으로 시도하여 로그인이 거부되는지 확인하세요.
public.auth.methods를 설정했다면 비밀번호 로그인이 거부되고, root super 사용자가 여전히 /auth/signin?fallback=1에서 로그인할 수 있는지 확인하세요.

로그인 작동 방식​

1. ID 공급자에 MonoChat 등록하기​

2. 설정 추가하기​

로그인할 수 있는 사람​

SSO를 유일한 로그인 방법으로 만들기​

네트워크​

제한 사항​

설정 확인하기​

로그인 작동 방식

1. ID 공급자에 MonoChat 등록하기

2. 설정 추가하기

로그인할 수 있는 사람

SSO를 유일한 로그인 방법으로 만들기

네트워크

제한 사항

설정 확인하기