SSO (Enterprise)

주의

SSO 설정은 Enterprise 플랜에서만 사용할 수 있습니다. 보이지 않는다면 SSO 구성 아래 설정 → 조직 → 보안로 이동하여 조직이 Enterprise 플랜인지 확인하세요. 확인이 어렵다면 Capgo 담당자에게 문의하시기 바랍니다.

SSO란 무엇인가요?

Single Sign-On (SSO)를 사용하면 팀원들이 회사의 ID 제공업체(IdP)를 통해 Capgo에 로그인할 수 있습니다. Capgo은 Supabase Auth를 통해 SAML 2.0을 지원합니다. 사용자의 이메일 도메인이 활성화된 SSO 제공업체와 일치하면, 해당 IdP를 통해 인증을 거친 후 SSO 콜백 과정에서 조직에 자동으로 프로비저닝됩니다.

SSO는 사용자의 권한을 변경하지 않습니다. 권한은 조직 역할(organization roles)에 의해 제어됩니다. SSO는 인증 방식만 변경합니다.

사전 요구사항

시작하기 전에:

• Capgo 조직에서 Enterprise 구독이 활성화되었습니다.
• 다음 기능을 지원하는 ID 제공업체(IdP): SAML 2.0 및 IdP 메타데이터 URL (HTTPS).
• 다음 항목을 게시할 수 있는 권한: DNS TXT 레코드 이메일 도메인에 대한 (예: company.com 사용자가 다음으로 로그인할 때: user@company.com).
• 조직 설정 업데이트 권한이 있는 Capgo 조직 구성원.
• 한 IdP 관리자 IT/보안 팀에 문의하세요.

SSO 설정 위치

1. 열기 https://console.capgo.app/
2. 클릭 설정 왼쪽 사이드바에서
3. 다음을 선택하세요: 조직 탭
4. 다음을 선택하세요: 보안 탭
5. 이동하려면 스크롤하세요 SSO 설정. 해당 양식은 조직이 Enterprise 플랜을 사용 중일 때만 표시됩니다.

1단계 - IdP 설정

사용 중인 identity provider에서 새로운 SAML 2.0 애플리케이션을 생성하세요. 다음 정보가 필요합니다. 서비스 제공자 Capgo SSO 설정 패널에 표시된 값:

필드	사용처
ACS URL	IdP SAML 앱의 Assertion Consumer Service URL
Entity ID	Service Provider 엔티티 식별자
SP 메타데이터 URL	선택 사항: IdP가 URL을 통한 SP metadata 임포트를 지원하는 경우 사용
NameID 형식	SAML Name Identifier에 기대되는 형식

IdP는 반드시 사용자의 이메일 주소를 assertion에 포함해야 합니다. Capgo는 이메일 도메인을 사용하여 활성 SSO 제공업체를 확인하고 기존 계정과 매칭합니다.

2단계 - Capgo에 SSO 제공업체 추가

1. SSO 설정 패널에서 새 제공업체를 추가하려면 클릭하세요
2. 다음 정보를 입력하세요 이메일 도메인 (예: company.com). 사용자 로그인 이메일의 도메인 부분과 일치해야 합니다
3. IdP 메타데이터 URL (HTTPS)
4. 제출

제공업체가 다음 상태로 생성되었습니다 인증 대기 중.

3단계 - DNS 도메인 인증

SSO를 활성화하기 전에 Capgo에서 해당 도메인의 소유권을 확인합니다.

다음 항목을 추가하세요: TXT 레코드를 DNS 제공업체에:

필드	값
유형	TXT
이름 / 호스트	_capgo-sso.<your-domain> (예: _capgo-sso.company.com)
값	대시보드 패널에 표시된 인증 토큰

레코드가 게시되면 (DNS TTL 전파에는 보통 몇 분에서 한 시간 정도 소요됩니다), 대시보드에서 DNS 확인 를 클릭하세요. 성공하면 제공업체 상태가 Verified.

4단계 - 제공업체 활성화

DNS 검증이 완료되면 Activate를 클릭하세요. 제공업체 상태가 활성.만 사용됩니다. 활성 SSO 로그인 흐름 중에 제공자가 사용됩니다.

다음 중 선택할 수 있습니다: 비활성화 대시보드에서 언제든지 설정할 수 있습니다. 설정하면 해당 제공자가 비활성 상태로 이동하며, 구성을 삭제하지 않고 해당 도메인의 SSO를 일시 중지합니다.

5단계 - 테스트 및 역할 할당

사용자가 SSO를 통해 처음 로그인하고 해당 조직에 기존 멤버십이 없는 경우, Capgo에서 다음 권한을 부여합니다: 읽기 역할.

파일럿 사용자가 로그인한 후:

1. 다음으로 이동: 설정 → 조직 → 멤버
2. SSO로 프로비저닝된 각 사용자를 찾습니다.
3. 적절한 권한 수준으로 역할을 조정하세요 (업로드, Write, Admin 등)

참고하세요: 예제 앱의 전체 권한 상세 내역 각 역할의 권한을 확인하세요.

참고

Supabase가 Capgo에 이미 존재하는 이메일에 대해 별도의 SSO 인증 사용자를 생성하는 경우, Capgo은 해당 SSO 계정을 기존 계정과 통합하고 사용자에게 다시 로그인하도록 요청합니다.

선택 사항 - SSO 강제 적용

다음의 활성 provider에서 다음을 설정할 수 있습니다. SSO 강제 적용. 이 기능을 활성화하면 Capgo은 해당 이메일 도메인의 기존 인증 사용자를 SSO 전용으로 표시하며, 로그인 시 해당 도메인에 대한 IdP 인증이 필요합니다. provider를 Disabled (비활성화) 또는 강제 적용을 해제하면 해당 도메인의 SSO 전용 플래그가 제거됩니다.

주의

강제 적용을 활성화하기 전에 IdP 관리자와 협의하고 모든 관련 사용자에게 공지하세요. IdP 인증을 완료할 수 없는 사용자는 해당 도메인에 대해 비밀번호로 로그인할 수 없습니다.

Provider 상태 참조

상태	의미
인증 대기 중	DNS TXT 레코드가 아직 인증되지 않음
인증됨	도메인 소유권 확인됨; 활성화 준비 완료
활성	이 도메인에 SSO가 적용되었습니다
비활성화됨	설정자: 비활성화 대시보드에서; 해당 도메인에 SSO를 사용하지 않음; 재활성화 로 돌아가려면 활성

배포 체크리스트

• Enterprise 플랜 확인됨
• Capgo의 ACS URL 및 Entity ID를 사용하여 IdP에서 SAML 앱 생성
• 안정적인 email claim을 전달하도록 IdP 설정 완료
• DNS TXT 레코드 게시 및 DNS 검증 성공
• Provider 활성화됨
• Pilot 사용자 로그인 성공
• 기본 권한에서 역할 상향 읽기 필요에 따라
• Enforcement 결정 완료 (활성화 시 통지됨)

관련 문서

• 조직: 역할 및 권한
• 조직 보안: 2FA, 비밀번호, API 키

SSO (Enterprise) 이후 단계

사용 중이라면 SSO (Enterprise) 인증 및 계정 흐름을 설계할 때, 이를 다음 항목과 연결하세요: @capgo/capacitor-social-login @capgo/capacitor-social-login의 구현 세부 사항은, @capgo/capacitor-passkey @capgo/capacitor-passkey의 구현 세부 사항은 @capgo/capacitor-native-biometric @capgo/capacitor-native-biometric의 구현 세부 사항은, 2단계 인증 2단계 인증(Two-factor authentication)의 구현 세부 사항은, Capacitor 앱에 OAuth2를 구현하는 5단계 Capacitor 앱에 OAuth2를 구현하는 5단계 가이드에서 실무적인 맥락을 확인해 보세요.