외부 로그인과 복구 설정하기
서버 운영자용 안내입니다. 공개 코어는 비밀번호 로그인과 외부 로그인 확장 인터페이스를 제공합니다. 사내 OIDC 같은 제공자 구현은 별도 플러그인입니다. dtxWiki만 설치해도 Google·회사 SSO 버튼이 생기지는 않습니다.
설치한 제공자 설정
API·worker·CLI와 같은 Python 환경에 신뢰하는 플러그인을 설치하고 패키지 이름이 아닌 dtxwiki.plugins 진입점 이름으로 활성화합니다. 아래 가상 예제는 company_login이 company.oidc를 제공한다고 가정합니다.
DTXWIKI_PLUGINS=company_login
DTXWIKI_AUTH_PROVIDERS_FILE=/etc/dtxwiki/auth-providers.toml
DTXWIKI_PUBLIC_BASE_URL=https://wiki.example.com
DTXWIKI_AUTH_PASSWORD_LOGIN_ENABLED=true
[[providers]]
slug = "company"
method = "company.oidc"
display_name = "Company SSO"
issuer = "https://idp.example.com/tenant"
client_id = "dtxwiki"
client_secret_ref = "file:/etc/dtxwiki/oidc-client-secret"
jit_provisioning = true
link_policy = "confirm"
trust_email_verified = false
플러그인·IdP에서 확인한 실제 값으로 바꾸세요. 비밀값은 서비스 계정이 읽는 보호된 파일에 두며 env: 참조도 지원합니다. 예제 redirect URI는 https://wiki.example.com/api/v1/auth/sso/company/callback입니다. 대표 URL은 HTTPS가 필요하고 solo_local의 loopback HTTP 개발 설정만 예외입니다.
jit_provisioning 기본값은 false입니다. 예제는 첫 로그인 때 새 계정 생성을 허용하려고 명시적으로 켰습니다. 꺼져 있으면 미등록 사용자는 계정 생성을 허용하지 않는 제공자라는 안내를 받으니 의도한 가입·연결 절차를 사용하세요. 계정 생성만으로 기존 공간에 접근하지는 않습니다. 플러그인의 로그인 훅은 운영자의 provisioning_workspace_roles 허용 목록 안에서만 멤버십을 요청할 수 있습니다. 정규 UUID의 공간마다 허용할 viewer·editor 역할을 지정하며 임의의 소유자 권한을 주지 않고 기존 역할은 유지합니다. 허용된 프로비저닝 요청이 없으면 멤버를 별도 추가하세요.
API와 worker에 같은 플러그인·제공자·비밀 설정을 전달해 재시작하고 가상 계정으로 새 로그인·기존 계정 연결·로그아웃·재로그인을 확인합니다.
신원·이메일·네트워크 정책
계정은 UUID와 검증된 (issuer, subject)로 식별하며 이메일·SMTP·비밀번호 없이 존재할 수 있습니다. trust_email_verified=true이고 IdP가 검증한 주소만 중복 없는 계정 이메일이 됩니다. 나머지 프로필 주소는 계정 이메일을 선점하지 않습니다.
신뢰된 이메일이 다른 계정에 등록돼 있으면 그 계정으로 로그인해 명시적으로 연결하며 자동 병합하지 않습니다. 미확인 주소 충돌의 기본 email_collision_policy="admin_approval"은 설정 → 사용자 계정에서 주소 해제 또는 기존 계정 유지로 처리합니다. 해제는 기존 데이터를 보존하고 계정 비활성화·자격 증명 폐기를 수행합니다. "auto_release"는 신뢰·검증 이메일이 필요하며 서버 관리자 계정을 자동 해제하지 않습니다. 로그인 화면의 내 계정이 아닙니다 — 서버 관리자에게 요청은 10분 확인을 사용하므로 만료 시 제공자로 다시 로그인하세요.
allowed_email_domains를 쓰려면 trust_email_verified=true와 IdP의 검증 이메일이 필요합니다. 선택적인 회사 디렉터리는 directory_enabled=true, 검증된 directory_tenant, 같은 제공자·tenant 신원의 요청 소유자가 필요합니다. UUID와 신뢰된 조직 정보를 확인하세요. 검증되지 않은 프로필 이메일은 계정 이메일 멤버 조회 키가 아닙니다.
공개 OIDC helper에서 사설망 IdP를 쓰려면 allow_private_network=true를 명시하며 IdP 주소는 계속 HTTPS여야 합니다. 플러그인 전용 환경 변수는 DTXWIKI_PLUGIN_<ENTRY_POINT_NAME>_<FIELD> 형식으로, 활성 플러그인의 설정 모델에 선언한 필드만 사용합니다. 알 수 없는 필드·없는 진입점은 시작을 거부합니다. 필드를 추측하지 말고 설치한 플러그인의 명세를 확인하세요.
관리·복구 경로 유지
비밀번호 로그인을 끄기 전에 필요한 관리자에게 제공자를 연결하고 확인하세요. 비밀번호 로그인과 활성 제공자가 모두 없으면 시작하지 않습니다. 이메일 없는 활성 계정의 서버 관리 권한은 해당 설치의 유지보수 환경에서 dtxwiki admin grant --user-id USER_UUID로 부여합니다. 멤버십과 별개입니다. UUID는 계정 → 사용자 ID → 사용자 ID 복사로 얻습니다.
최근 본인 인증은 기본 60분이며 DTXWIKI_AUTH_REAUTHENTICATION_MAX_AGE_SECONDS로 조정합니다. 세션 갱신으로 늘어나지 않습니다. 이메일 일회용 확인은 5분 후 만료되고 같은 브라우저·계정/관리 목적에 묶입니다. SSO 확인이 IdP의 새 MFA 인증을 증명하지는 않습니다.
이메일 없는 신원은 우선 IdP에서 복구하세요. 독립적으로 소유권을 확인한 뒤 서버 관리자가 설정 → 사용자 계정 → SSO identity 다시 연결로 기존 사용자 UUID를 다시 연결합니다. CLI 대안은 dtxwiki users rebind-identity --help를 확인하세요. UUID·데이터·역할은 유지하고 세션·대기 확인·API/OAuth 자격 증명은 폐기합니다. 필요한 경우 이전 신원을 IdP에서도 차단하세요. 매핑 삭제만으로 이후 JIT 가입이 차단되지는 않습니다.
계정 도구는 보존 삭제·복구·보류된 공간의 관리자 지정과 서버 감사 기록도 설명합니다. 계정 이메일 추가와 이메일 확인에는 해당 메일 설정이 필요하며 SMTP로 유일한 IdP의 장애를 복구하지는 않습니다.
근거: SSO 운영 설정, 제공자 기본값·허용 목록, 제한된 프로비저닝, 신원 복구, 관리 화면 문구.