슈퍼 관리자와 인증 설정

Chorus의 대부분은 워크스페이스 단위로 동작하지만, 워크스페이스보다 위에 있는 역할이 하나 있습니다. 바로 슈퍼 관리자입니다. 슈퍼 관리자로 워크스페이스를 만들고 팀의 싱글 사인온(SSO)을 켭니다. 이 가이드는 Chorus 배포를 운영하는 사람을 위한 것입니다. 로그인만 하면 되는 최종 사용자는 계정과 워크스페이스를 읽으세요.

슈퍼 관리자 활성화하기

슈퍼 관리자는 어떤 워크스페이스와도 분리된 플랫폼 수준의 계정입니다. 서버에 환경 변수 두 개, 즉 관리자 이메일과 관리자 비밀번호의 bcrypt 해시를 설정해 활성화합니다.

SUPER_ADMIN_EMAIL="admin@example.com"
SUPER_ADMIN_PASSWORD_HASH="$2b$10$..."   # 비밀번호의 bcrypt 해시

해시는 다음과 같은 일회성 명령으로 생성합니다.

node -e "console.log(require('bcryptjs').hashSync('your-password', 10))"

bcrypt 해시를 배포의 시크릿 저장소에 보관하세요. 관리자 세션에는 안전한 NEXTAUTH_SECRET도 필요합니다. 단일 인스턴스라면 npm chorus 런처와 Docker 엔트리포인트가 이 값을 생성해 저장해 줍니다. 레플리카가 여러 개라면 모든 레플리카에 같은 값을 명시적으로 설정하세요. Docker 세션 비밀 키를 참고하세요.

슈퍼 관리자로 로그인하기

앱 안에는 관리 패널로 가는 링크가 없으며, 일반 로그인 화면을 통해 들어갑니다. 슈퍼 관리자 이메일을 입력하면 Chorus가 이를 인식하고, 별도의 단계에서 관리자 비밀번호를 요구한 뒤 슈퍼 관리자 패널을 엽니다. 관리자 세션은 어떤 워크스페이스와도 독립적이며 일반 세션보다 수명이 짧으므로, 주기적으로 다시 로그인하게 됩니다.

Dashboard와 Companies 내비게이션, 그리고 워크스페이스·사용자·에이전트 수를 표시하는 슈퍼 관리자 패널의 대시보드 — 슈퍼 관리자 패널의 전용 대시보드와 회사 화면에서 배포의 워크스페이스를 관리합니다.

워크스페이스 만들기

슈퍼 관리자 패널의 회사 목록에서 워크스페이스를 생성·편집·삭제할 수 있습니다. 회사 만들기 양식에서 인증 방식을 선택합니다.

OIDC: 이름, 이메일 도메인, 아래의 SSO 설정을 입력합니다. 도메인은 이메일에 맞는 워크스페이스를 찾는 데 사용됩니다.
로컬 계정: 이름과 초기 워크스페이스 관리자의 사용자 이름·이메일을 입력합니다. 표시 이름은 선택 사항입니다. 이메일 도메인이나 OIDC 제공자는 필요하지 않습니다. 생성 후 일회용 초대를 복사해 안전하게 공유하면 관리자가 직접 비밀번호를 설정하고 별도로 로그인합니다.

한 워크스페이스에서 로컬 계정과 OIDC를 함께 사용할 수 없으며 편집으로 인증 방식을 전환할 수도 없습니다. 로컬 워크스페이스는 이름을 바꿀 수 있지만 OIDC·도메인 필드는 편집할 수 없습니다. 환경 변수로 정의하는 Default Auth 계정은 별도 로그인 옵션이며 초기 로컬 관리자가 아닙니다.

초기 초대 복구하기

초기 관리자가 초대를 수락하기 전에는 회사에서 로컬 워크스페이스를 열어 초대를 재발급·취소·교체할 수 있습니다. 재발급은 이전 링크를 무효화합니다. 교체하면 같은 사용자 이름·이메일을 사용하더라도 새 ID가 생성됩니다. 취소 후에는 같은 패널에서 대체 관리자를 초대할 수 있습니다. 초기 관리자 초대 중 하나라도 수락되면 이 초기 설정 복구 기능은 닫힙니다. 이후의 일상적인 계정 관리는 슈퍼 관리자가 아닌 로컬 워크스페이스 관리자가 사이드바의 설정 아래에 있는 워크스페이스 사용자에서 수행합니다. 로컬 사용자 관리를 참고하세요.

로컬 계정을 선택하고 데모 초기 관리자 정보를 입력한 회사 만들기 양식 — 로컬 계정을 선택하면 OIDC 제공자 없이 워크스페이스를 만들고 첫 워크스페이스 관리자를 초대할 수 있습니다.

SSO(OIDC) 구성하기

아래 설정은 OIDC 방식 워크스페이스에만 적용됩니다. 로컬 워크스페이스에는 OIDC 설정 카드가 표시되지 않습니다.

Chorus는 PKCE를 사용하는 OpenID Connect로 조직의 ID 제공자를 통해 사용자를 로그인시킵니다. 따로 관리할 client secret은 없습니다. 워크스페이스마다 슈퍼 관리자 패널의 워크스페이스 설정에 있는 OIDC 설정에서 구성하며, 필수 값은 두 개입니다.

OIDC 발급자 URL — ID 제공자의 OpenID Connect 디스커버리 URL.
클라이언트 ID — ID 제공자에 등록한 애플리케이션의 client ID.

둘 다 설정하면 SSO가 자동으로 켜지고, 둘 중 하나를 지우면 꺼집니다. Chorus는 표준 openid profile email 스코프를 요청합니다.

OIDC를 선택하고 데모 이메일 도메인, Issuer URL, Client ID를 입력한 회사 만들기 양식 — 워크스페이스 생성 시 OIDC를 선택하고 제공자를 설정합니다. 기존 OIDC 워크스페이스에서도 나중에 편집할 수 있습니다.

ID 제공자 쪽에서 Chorus를 애플리케이션으로 등록하고 리디렉션(콜백) URL을 허용 목록에 추가하세요. 이 URL은 Chorus 사이트 주소 뒤에 /login/callback을 붙인 것이며, 회사 목록에 복사할 정확한 URL이 표시됩니다. 이 값은 Chorus를 열 때 사용한 주소로 만들어지므로, 운영 URL로 회사 페이지를 열고 거기에 표시된 값을 복사하세요.

사용자에게 미치는 영향

워크스페이스에 SSO가 구성되면, 그 워크스페이스의 도메인에 속한 이메일로 로그인하는 사람은 ID 제공자로 이동했다가 돌아옵니다. 계정과 워크스페이스에서 설명하는 흐름입니다. 이메일이 여러 SSO 워크스페이스에 해당하는 사용자에게는 하나를 고르라는 안내가 표시됩니다. 이미 워크스페이스에 추가된 사람은 이메일 도메인이 달라도 그 워크스페이스로 로그인됩니다.

워크스페이스와 SSO가 준비되면 일상적인 설정은 각 워크스페이스의 운영자에게 맡기세요. 에이전트 액세스 준비는 에이전트 인증 정보 만들기를 다루고, 계정과 워크스페이스는 사용자가 로그인할 때 무엇을 보게 되는지를 다룹니다.