SSO와 SCIM
회사 계정(IdP) 로그인과 사용자 자동 동기화를 설정하는 순서입니다.
회사의 IdP(Okta, Microsoft Entra ID, Google Workspace 등)를 Keural에 연결하면 직원이 회사 계정으로 로그인하고, 첫 로그인 때 조직에 자동으로 합류합니다.
IdP 담당자·개발자용 명세는 SSO·SCIM 연동 명세 참고.
준비 사항
| 항목 | 이유 |
|---|---|
| Keural 조직의 소유자 계정 | SSO 설정은 소유자만 바꿀 수 있습니다. |
| IdP 관리자 권한 | IdP에 Keural 애플리케이션을 만듭니다. |
| 회사 도메인의 DNS 관리 권한 | 도메인 소유를 TXT 레코드로 인증합니다. |
지원 방식
| 방식 | 용도 |
|---|---|
| OpenID Connect (OIDC) | 회사 계정으로 로그인 |
| SAML 2.0 | 회사 계정으로 로그인. 인증 요청은 Redirect, 응답은 HTTP-POST로 받습니다. |
| SCIM 2.0 | IdP에서 사용자를 추가·비활성화하면 Keural 계정에 자동 반영 |
OIDC와 SAML 중 하나를 고릅니다. IdP가 둘 다 지원하면 설정이 간단한 OIDC를 권장합니다.
설정 순서
모든 설정은 조직 관리 → SSO 설정에서 합니다.
1. 회사 도메인 인증
SSO에 쓸 이메일 도메인의 소유를 먼저 인증합니다. 인증하지 않은 도메인은 3단계에서 저장되지 않습니다.
조직 도메인에 회사 도메인(예: acme.com)을 입력하고 도메인 추가를 누릅니다.
도메인 행의 인증을 누릅니다. 도메인 인증 창에 표시된 TXT 레코드 값(keural-verify=…)을 복사합니다.
DNS 관리 화면에서 그 도메인에 TXT 레코드를 추가하고 복사한 값을 붙여 넣습니다. 호스트(이름)는 도메인 자체(보통 @)입니다.
Keural로 돌아와 인증 확인을 누릅니다. 인증됨이 표시되면 완료입니다. DNS 반영에는 수십 분 걸릴 수 있으므로, 실패하면 잠시 뒤 다시 누릅니다.
회사 도메인이 여러 개면 각각 추가하고 인증합니다. gmail.com 같은 공개 이메일 도메인은 쓸 수 없습니다.
2. IdP에 애플리케이션 만들기
SSO 설정 맨 위 프로토콜에서 OpenID Connect (OIDC) 또는 SAML 2.0을 고르면 IdP에 등록할 Keural 값이 표시됩니다. 이 값을 IdP 애플리케이션에 입력하고, IdP가 발급한 값을 복사해 둡니다.
| 방향 | 항목 | 내용 |
|---|---|---|
| Keural → IdP | 콜백 URI | IdP 애플리케이션의 리디렉션 URI에 입력합니다. |
| IdP → Keural | Issuer URL | IdP의 발급자 주소입니다. |
| IdP → Keural | Client ID · Client Secret | IdP 애플리케이션을 만들면 발급되는 값입니다. |
IdP가 사용자 이메일을 보내도록 설정해야 로그인됩니다.
| IdP | 만드는 곳 | 콜백 URI를 넣는 칸 | Issuer URL |
|---|---|---|---|
| Okta | Applications → Create App Integration → OIDC · Web Application | Sign-in redirect URIs | https://<Okta 도메인> |
| Microsoft Entra ID | App registrations → New registration | Redirect URI(Web) | https://login.microsoftonline.com/<테넌트 ID>/v2.0 |
| Google Workspace | Google Cloud 콘솔 → API 및 서비스 → 사용자 인증 정보 → OAuth 클라이언트 ID(웹 애플리케이션) | 승인된 리디렉션 URI | https://accounts.google.com |
- Microsoft Entra ID: Client Secret은 Certificates & secrets에서 새로 만든 값(Value)입니다. Token configuration에서 ID 토큰에
email선택 클레임을 추가합니다. - Okta: 애플리케이션의 Assignments에서 Keural을 쓸 사용자나 그룹을 지정합니다.
3. Keural에 값 입력하고 저장
- 2단계에서 받은 IdP 값을 입력합니다.
- 이메일 도메인에 1단계에서 인증한 도메인을 쉼표로 구분해 입력합니다. 이 도메인 이메일로 로그인하면 회사 로그인 화면으로 이동합니다.
- 미가입 사용자 자동 생성(JIT)을 설정합니다. 켜면 Keural 계정이 없는 직원도 첫 SSO 로그인 때 계정이 만들어지고, 끄면 계정이 있는 사람만 로그인할 수 있습니다.
- 저장을 누릅니다.
OIDC에서 IdP가 표준 주소(discovery)를 제공하지 않으면 고급 설정 열기에서 엔드포인트를 직접 입력합니다. 대부분의 IdP는 비워 둡니다.
4. SSO 켜고 테스트 로그인
- SSO 활성화를 켜고 저장합니다.
- 테스트 로그인을 누릅니다. 새 창에 회사 로그인 화면이 열립니다.
- 회사 계정으로 로그인해 Keural로 돌아오면 연결이 완료됩니다.
테스트 로그인은 SSO가 켜져 있어야 동작합니다. 문제가 있으면 SSO 활성화를 끄고 저장합니다. 그동안 해당 도메인의 직원은 이메일 링크로 로그인합니다.
직원 로그인
- Keural 로그인 화면에 회사 이메일을 입력하면 회사 로그인 화면으로 이동하고, 로그인하면 Keural로 돌아옵니다.
- 데스크톱 앱에서는 회사 로그인 화면 대신 이메일 링크로 로그인합니다.
- 처음 SSO로 로그인한 직원은 조직에 멤버로 합류합니다. 관리자 역할은 조직 관리에서 지정합니다.
다음 경우에는 로그인은 되지만 조직에 자동으로 합류하지 않습니다.
- 조직이 산 좌석이 모두 찼을 때
- 그 계정이 이미 다른 조직에 속해 있을 때
5. SCIM 연결(선택)
SCIM을 연결하면 IdP에서 사용자를 추가하거나 비활성화할 때 Keural 계정에 바로 반영됩니다. SSO 연결을 마친 뒤 설정합니다.
SCIM 프로비저닝에서 SCIM 프로비저닝 활성화를 켭니다.
토큰 발급을 누르고 토큰을 복사합니다. 토큰은 이때 한 번만 표시됩니다.
IdP의 프로비저닝 설정에 SCIM Base URL (Tenant URL)과 토큰을 입력합니다. 인증 방식은 Bearer 토큰입니다.
| IdP | 입력 위치 |
|---|---|
| Okta | 애플리케이션 → Provisioning → SCIM connector base URL, Authentication Mode는 HTTP Header |
| Microsoft Entra ID | Enterprise application → Provisioning → Automatic → Tenant URL · Secret Token |
IdP 작업은 Keural에 다음과 같이 반영됩니다.
| IdP에서 | Keural에서 |
|---|---|
| 사용자 할당 | 계정을 만들고 조직에 넣습니다. 사용자 이름은 이메일입니다. |
| 사용자 비활성화 또는 할당 해제 | 계정을 정지해 로그인을 막습니다. 데이터는 지우지 않습니다. |
| 다시 활성화 | 정지를 풉니다. |
| Keural Admins 그룹에 추가·제외 | 관리자로 올리거나 멤버로 내립니다. 소유자는 바뀌지 않습니다. |
토큰을 잃어버렸으면 토큰 재발급을 누르고 새 토큰을 IdP에 입력합니다. 기존 토큰은 즉시 무효가 됩니다.
문제 해결
| 증상 | 조치 |
|---|---|
| 이메일 도메인이 저장되지 않습니다 | 1단계 도메인 인증을 마쳤는지, 공개 이메일 도메인이 아닌지 확인합니다. |
| 도메인 인증이 실패합니다 | TXT 값을 keural-verify=부터 끝까지 넣었는지 확인하고, DNS 반영을 기다린 뒤 다시 누릅니다. |
| 테스트 로그인을 눌러도 회사 로그인 화면이 열리지 않습니다 | SSO 활성화를 켜고 저장했는지 확인합니다. |
| 회사 로그인 뒤 Keural 로그인 화면으로 돌아옵니다 | OIDC는 콜백 URI·Issuer URL·Client Secret과 이메일 클레임을, SAML은 SP EntityID·ACS URL·인증서와 이메일 속성을 다시 확인합니다. |
| 계정이 없다며 로그인이 거부됩니다 | 미가입 사용자 자동 생성(JIT)이 꺼져 있습니다. 켜거나 그 직원을 먼저 초대합니다. |
| 로그인은 되지만 조직 워크스페이스가 보이지 않습니다 | 좌석이 남았는지, 그 계정이 다른 조직에 속해 있지 않은지 확인합니다. |
| IdP 포털에서 앱을 눌러 들어오면 실패합니다(SAML) | Keural 로그인 화면에서 회사 이메일로 시작합니다. |
| SCIM 연결 테스트가 실패합니다 | Base URL과 토큰을 다시 넣습니다. 토큰을 재발급했다면 새 토큰으로 바꿉니다. |