싱글 사인온(SSO)

SSO 설정 및 사용

---

위험

이 가이드는 시스템 관리자를 대상으로 합니다. 필요한 기술 전문 지식이 없는 경우, IT 부서에 도움을 요청하세요.

Prevu3D Cloud Platform은 업계 표준 프로토콜을 통해 안전한 싱글 사인온(SSO)을 지원합니다:

• SAML 2.0 – 인증 및 사용자 로그인용.

• SCIM 2.0 – 자동 사용자 및 그룹 프로비저닝용.

지원되는 ID 공급자

SAML 2.0 및/또는 SCIM 2.0 프로토콜을 완전히 지원하는 모든 ID 공급자는 Okta, Google Workspace, OneLogin, Ping Identity 등을 포함하여 Prevu3D와 호환되어야 합니다. Prevu3D의 구현은 공식 SAML 2.0 및 SCIM 2.0 사양을 따르므로, 최신 ID 시스템과의 광범위한 호환성을 보장합니다.

당사는 다음과의 연동을 철저히 테스트했습니다:

• Microsoft Entra ID(이전 Azure Active Directory)

• JumpCloud (English)

참고

• 각 Prevu3D 조직은 한 번에 하나의 ID 공급자에 대한 연결만 지원합니다.

• SSO 기능은 Enterprise 구독에 포함되어 있습니다. 조직에 대해 활성화하려면 sales@prevu3d.com에 문의하세요.

SAML 2.0 – 인증 설정

사전 요구 사항

Prevu3D로 SAML 기반 SSO를 구성하려면, 다음이 필요합니다:

• Prevu3D 조직에 대한 관리자 접근.

• 애플리케이션을 구성할 권한이 있는 IdP에 대한 접근.

단계

1. Prevu3D 계정에 로그인합니다(이메일 주소와 비밀번호 사용)

2. Settings 탭으로 이동합니다

3. 왼쪽 메뉴에서 SSO 탭을 선택합니다

“SSO” 탭에 접근할 수 없나요?

1. 탭이 없으면, 조직 관리자가 아닙니다.

2. 탭이 회색으로 표시되면, 조직이 SSO 기능을 구독하지 않았습니다.

4. SSO 탭에서 다음 값을 복사하여 IdP 구성에 붙여넣습니다:

   • Service Provider Endpoint – IdP가 SAML 어설션을 전송하는 URL입니다. IdP에 따라 ACS URL, Reply URL 또는 Assertion Consumer Service URL이라고 부를 수 있습니다.

   • Service Provider Entity ID – SAML 교환에서 Prevu3D를 식별하는 고유 식별자입니다. IdP에 따라 Audience, Identifier 또는 SP Entity ID라고 부를 수 있습니다.

주의

전체 접미사를 포함하여(예: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx-production-############-Prevu3DCloudPlatform) SSO 탭에 표시된 그대로 Entity ID를 IdP에 입력하세요. 직접 다시 입력하지 말고 복사하여 붙여넣으세요.

IdP가 축약된 값이나 친숙한 이름의 audience 값(예: Prevu3D)을 전송하면, 나머지 구성이 올바르더라도 audience 불일치로 인증이 거부됩니다. 이는 가장 흔한 설정 오류입니다 — 문제 해결을 참조하세요.

5. IdP에서 다음을 가져와 SSO 탭에 입력합니다:

   • SAML Certificate(PEM 형식)

   • SAML Endpoint URL

6. SCIM이 활성화되어 있지 않은 경우, SAML 속성 매핑을 정의합니다 – 아래 SAML 속성 매핑을 참조하세요.

   

주의

이러한 속성은 SCIM 프로비저닝이 활성화되고 구성된 경우 선택 사항입니다. SCIM은 사용자 세부 정보를 자동으로 관리합니다.

7. 페이지 하단의 Save를 클릭합니다.

8. 배포하기 전에 구성을 확인합니다 – 아래 구성 검증을 참조하세요.

SAML 속성 매핑

각 필드는 ID 공급자가 전송한 SAML 어설션에서 Prevu3D가 읽어야 할 속성(클레임)을 지정합니다. 입력하는 값은 대소문자를 포함하여 IdP에 구성된 속성 이름과 정확히 일치해야 합니다.

필드	입력할 내용	예시 값
First Name SAML Attribute Key	사용자의 이름(given name)이 포함된 IdP 속성의 이름	givenName, firstName, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
Last Name SAML Attribute Key	사용자의 성(surname)이 포함된 IdP 속성의 이름	familyName, surname, lastName

IdP가 어떤 속성 이름을 전송하는지 잘 모르겠나요? SAML-tracer와 같은 브라우저 확장 프로그램으로 SAML 트레이스를 캡처하여 AttributeStatement에 나열된 이름을 확인하거나, IdP의 애플리케이션 구성을 참조하세요.

SSO를 통한 역할 할당

이 섹션에는 이전에 Role SAML Attribute Key 필드와 Default Organization Role 선택 항목이 있어 SAML 속성을 기준으로 조직 전체에 단일 역할을 할당했습니다. 두 항목 모두 제거되었습니다. 조직 전체에 단일 역할을 적용하는 방식은 세분화가 부족하고, 제공되던 역할이 조직의 사용자 지정 역할과 더 이상 일치하지 않기 때문입니다.

대신 그룹 매핑으로 역할을 할당하세요. IdP의 그룹을 Prevu3D 그룹에 매핑하고 각 그룹에 필요한 접근 권한을 부여하면 됩니다. SCIM을 사용하는 경우에는 SCIM으로 역할을 할당하세요.

사용자에게 SSO 배포하기

구성을 저장하고 검증한 후에는, 사용자가 실제로 로그인할 수 있는지를 두 가지 요소가 결정합니다.

도메인 구성 및 신규 사용자

이메일 도메인이 Prevu3D 조직과 연결되어 있어야 합니다. 도메인 구성은 다음을 가능하게 합니다:

• 로그인 페이지 리디렉션 – Sign in with SSO를 클릭하고 해당 도메인의 이메일을 입력한 사용자는 IdP로 리디렉션됩니다.

• JIT(Just-in-time) 계정 생성 – Prevu3D를 한 번도 사용한 적이 없는 해당 도메인의 사용자가 IdP를 통해 성공적으로 인증하면, SAML 속성 매핑에서 가져온 이름으로 Prevu3D 계정이 자동으로 생성됩니다. 초대나 수동 계정 생성이 필요하지 않습니다. 새 계정은 프로젝트 접근 권한이 없으며, 그룹 매핑으로 부여하거나 사용자를 프로젝트에 직접 추가하여 부여할 수 있습니다.

참고

도메인 구성은 Enterprise SSO 온보딩의 일부로 Prevu3D가 완료합니다. 이메일 도메인을 등록하려면 support@prevu3d.com에 문의하세요.

도메인이 구성되기 전까지는 해당 도메인의 사용자가 IdP로 리디렉션되지 않으며, 인증 시 invalid_user_email_domain 오류를 받을 수 있습니다.

주의

SSO를 통해 생성된 사용자는 처음에 프로젝트 접근 권한이 없습니다. 그룹(그룹 매핑 사용)을 통해 또는 사용자를 프로젝트에 직접 추가하여 프로젝트 접근 권한을 부여하세요.

SSO가 구성된 도메인의 사용자는 이메일 초대 링크에서 비밀번호 기반 계정을 만드는 대신 SSO로 로그인해야 합니다.

기존 사용자 및 계정 연결

SSO가 활성화되기 전에 생성된 계정은 SSO와 함께 사용하기 전에 ID 공급자에 한 번 연결해야 합니다. 사용자는 SSO로 처음 로그인할 때 이 과정을 안내받으며, 프로젝트와 데이터는 그대로 유지됩니다. 사용자에게 표시되는 단계는 가입 및 로그인에 설명되어 있습니다.

주의

연결하려면 각 사용자의 기존 Prevu3D 비밀번호가 필요하므로, 비밀번호가 기억나지 않는 사용자는 연결하기 전에 재설정해야 합니다.

이를 완전히 생략하려면, support@prevu3d.com에 문의하여 해당 이메일 도메인의 모든 계정을 한 번의 작업으로 연결하세요. 그러면 사용자는 연결 흐름을 전혀 보지 않게 됩니다.

구성 검증

SSO를 광범위하게 배포하기 전에, 소규모 사용자 그룹으로 테스트하고 다음을 확인하세요:

• Prevu3D 로그인 페이지(Sign in with SSO)와 IdP 대시보드 양쪽에서 로그인이 성공합니다.

• 신규 계정에 이름과 성이 올바르게 입력됩니다.

• 예상보다 넓은 권한을 받는 사용자가 없습니다.

• 그룹 매핑을 사용하는 경우, 그룹 멤버십이 의도한 대로 적용됩니다.

참고

SAML-tracer와 같은 브라우저 확장 프로그램으로 캡처한 SAML 트레이스는 IdP가 정확히 어떤 속성과 audience 값을 전송하는지 확인하는 가장 빠른 방법입니다.

그룹 매핑(선택 사항)

조직 내 사람들의 접근 관리를 간소화하기 위해 IdP 시스템의 그룹을 Prevu3D 그룹에 매핑할 수도 있습니다. 다음 단계는 그룹 매핑을 안내합니다.

• SAML 속성을 통해 그룹 멤버십을 전달하도록 IdP를 구성합니다.

• 이 속성을 SSO 탭에 입력합니다.

• Prevu3D의 “Groups” 섹션에서, **“Edit group”**을 클릭하고 IdP가 예상하는 SAML 그룹 값을 지정합니다.

• 이 매핑은 사용자가 Prevu3D Cloud에 로그인할 때 적용됩니다. 사용자가 이미 로그인한 경우, 접근 변경 사항이 적용되도록 로그아웃한 후 다시 로그인해야 합니다.

참고

• 그룹 매핑은 로그인 시 적용됩니다. 사용자는 업데이트된 접근을 적용하려면 로그아웃한 후 다시 로그인해야 합니다.

• 그룹에 일부 접근이 부여되었는지 확인하세요. 자세한 내용은 그룹 섹션을 참조하세요.

주의

• SCIM이 활성화된 경우, 그룹 생성과 멤버십 할당은 대신 SCIM을 통해 처리되어야 합니다.

SCIM 2.0 – 프로비저닝 설정

Prevu3D는 **SCIM 2.0 프로토콜(System for Cross-Domain Identity Management)**을 통해 사용자 및 그룹 프로비저닝을 지원합니다.

사전 요구 사항

• 조직이 Enterprise 요금제를 사용해야 합니다.

• IdP가 SCIM을 지원해야 합니다(예: Azure AD/Entra, Okta, JumpCloud).

SCIM이 가능하게 하는 것

• 사용자 프로비저닝 – 새 사용자가 Prevu3D에 자동으로 생성됩니다

• 사용자 프로비저닝 해제 – IdP에서 비활성화되면 사용자가 비활성화되거나 제거됩니다

• 그룹 할당 – 그룹과 역할을 IdP에서 중앙 집중식으로 관리할 수 있습니다

설정 가이드

1. 조직 관리자로 Prevu3D 계정에 로그인합니다.

2. Settings 탭으로 이동합니다

3. 왼쪽 메뉴에서 SSO 탭을 선택합니다

4. SCIM Provisioning 섹션으로 스크롤하여 활성화합니다.

   

5. 다음을 찾을 수 있습니다:

   • SCIM Base URL(Entra ID 사용자는 아래 경고를 참조하세요)

   • Bearer Token

참고

보안 또는 자격 증명 교체를 위해 필요할 때 bearer token을 교체할 수도 있습니다.

주의

**Entra ID(Azure AD)**로 SCIM을 구성할 때, Prevu3D가 제공하는 SCIM Base URL 끝에 ?aadOptscim062020을 반드시 추가해야 합니다.

6. ID 공급자(예: Microsoft Entra ID)에서:

   • Prevu3D 엔터프라이즈 애플리케이션을 엽니다.

   • SCIM provisioning을 활성화합니다.

   • SSO 탭에서 얻은 SCIM Base URL과 Bearer Token을 입력합니다.

7. 다음에 대한 속성 매핑을 구성합니다:

   • userName, givenName, familyName, email

   • 선택 사항: groups, roles, active

8. 구성을 저장합니다

   이제 IdP가 프로비저닝 일정에 따라 사용자와 그룹을 Prevu3D와 자동으로 동기화합니다.

문제 해결

증상	유력한 원인	조치
IdP가 Prevu3D로 다시 리디렉션한 후 로그인이 완료되지 않음	SAML 어설션의 audience 값이 Service Provider Entity ID와 정확히 일치하지 않습니다. IdP가 축약된 값이나 친숙한 이름의 값을 전송하고 있을 수 있습니다.	IdP에서 Audience / Identifier / Entity ID 필드를 전체 접미사를 포함하여 SSO 탭에 표시된 정확한 값으로 설정하세요.
사용자가 로그인 페이지에서 이메일과 비밀번호를 입력했지만 IdP로 이동하지 않음	기본 로그인 양식은 비밀번호 기반 계정 전용입니다.	사용자에게 Login 버튼 아래의 Sign in with SSO를 클릭한 다음 회사 이메일을 입력하도록 안내하세요.
Sign in with SSO 화면에서 회사 이메일을 입력한 후 리디렉션되지 않음	이메일 도메인이 Prevu3D 조직과 연결되어 있지 않습니다.	이메일 도메인을 구성하려면 support@prevu3d.com에 문의하세요.
IdP에서 인증한 후 {"statusCode":401,"message":"invalid_user_email_domain"} 표시	동일한 원인: 사용자의 이메일 도메인이 조직과 연결되어 있지 않습니다.	이메일 도메인을 구성하려면 support@prevu3d.com에 문의하세요.
사용자에게 “session timed out”이 표시되고 이메일을 다시 입력하라는 요청을 받음	SSO가 활성화되기 전에 생성된 계정의 일회성 계정 연결 흐름에서 나타나는 정상적인 과정입니다.	사용자에게 계속 진행하도록 안내하세요. 이는 오류가 아닙니다. 기존 사용자 및 계정 연결을 참조하세요.
기존 사용자가 계정 연결을 완료하지 못함	연결하려면 사용자의 기존 Prevu3D 비밀번호가 필요하지만, 기억하지 못할 수 있습니다.	Forgot password로 재설정하도록 안내하거나, support@prevu3d.com에 해당 도메인의 일괄 연결을 요청하세요.
신규 계정의 이름이 비어 있거나 잘못됨	SSO 탭에 입력한 SAML Attribute Key가 IdP가 전송하는 속성 이름과 일치하지 않습니다. 이 값은 대소문자를 구분합니다.	SAML 트레이스를 캡처하고, AttributeStatement의 속성 이름을 확인한 다음, 매핑을 정확히 일치하도록 업데이트하세요.
그룹 접근 변경 사항이 적용되지 않음	그룹 매핑은 로그인 시에만 적용됩니다.	사용자에게 로그아웃한 후 다시 로그인하도록 안내하세요.
브라우저에서 Service Provider Endpoint URL을 직접 열면 {"statusCode":500,"message":"Internal server error"} 반환	예상된 동작입니다. 이 엔드포인트는 SAML POST 요청만 허용하며 브라우저에서 직접 열 수 없습니다.	이는 구성 문제를 나타내지 않습니다. 대신 로그인 페이지나 IdP에서 로그인하여 테스트하세요.

참고

여전히 해결되지 않으면, 성공하지 못한 로그인 시도의 SAML 트레이스를 캡처하고, 민감한 값을 가린 다음 support@prevu3d.com으로 보내주세요. 어설션에 표시된 audience 값과 속성 이름을 포함해 주시면, 당사 팀이 대부분의 문제를 한 번에 진단할 수 있습니다.

로그인 오류 문제 해결

구성 문제로 인해 SSO를 통해 로그인할 수 없는 경우, Prevu3D는 짧은 오류 코드가 포함된 오류 페이지를 표시합니다. 관리자는 아래에서 해당 코드를 찾아 그에 따른 해결 방법을 따르세요. 각 오류는 IdP의 SAML 애플리케이션 또는 Prevu3D의 SSO 탭에서 해결됩니다.

참고

일부 오류는 구성 문제가 아니라 자격 문제로 인해 사용자에게 표시됩니다 — 예를 들어 조직에 연결되지 않은 이메일 도메인, 구성원이 아닌 계정, 아직 연결이 필요한 계정 등입니다(기존 사용자 및 계정 연결 참조). 이러한 경우에는 IdP나 SSO 탭을 변경할 필요가 없습니다.

구성을 찾을 수 없음

코드: ConfigNotFound

조직에 대한 SAML 구성이 존재하지 않습니다 — SSO가 한 번도 구성되지 않았거나 구성이 삭제되었습니다.

해결 방법: IdP의 메타데이터를 사용하여 SSO 탭(Settings → SSO)에서 SSO를 구성하세요 — 위의 단계를 참조하세요 — 그리고 IdP의 애플리케이션이 올바른 Prevu3D 조직을 대상으로 하는지 확인하세요.

이메일 어설션 누락

코드: MissingEmailAssertion

IdP에서 전송한 SAML 응답에 이메일 주소(또는 NameID)가 포함되어 있지 않았습니다.

해결 방법: IdP의 SAML 애플리케이션에서 이메일(또는 NameID) 속성을 매핑하여 어설션에 포함되도록 하세요.

잘못된 응답 서명

코드: InvalidResponseSignature

SAML 응답의 서명 검증에 실패했습니다. 이는 대개 SSO 탭에 저장된 인증서가 IdP의 현재 서명 인증서와 더 이상 일치하지 않거나, 응답이 아예 서명되지 않았음을 의미합니다.

해결 방법: IdP의 현재 x509 서명 인증서를 SSO 탭에 복사하고, IdP가 SAML 응답에 서명하도록 구성되어 있는지 확인하세요.

인증서 오류

코드: CertificateError

SSO 탭에 저장된 인증서의 형식이 잘못되었거나, 만료되었거나, 구문 분석할 수 없습니다.

해결 방법: IdP에서 발급한 유효한 PEM 형식의 x509 인증서를 붙여넣으세요. 현재 인증서가 만료된 경우에는 교체하세요.

Audience 불일치

코드: AudienceMismatch

IdP에 구성된 audience가 Prevu3D가 해당 조직에 대해 기대하는 Service Provider Entity ID와 일치하지 않습니다.

해결 방법: IdP에서 Audience / Identifier / Entity ID 필드를 전체 접미사를 포함하여 SSO 탭에 표시된 정확한 Service Provider Entity ID로 설정하세요.

잘못된 역할 매핑

코드: InvalidRoleMapping

IdP에서 전송한 역할 값이 Prevu3D 조직의 유효한 역할과 일치하지 않습니다.

해결 방법: SAML 속성을 통한 역할 할당은 제거되었으므로, 이 코드는 이전 구성에서 역할 속성이 남아 있는 조직에만 해당합니다. 대신 그룹 매핑으로 역할을 할당하고, 오류가 계속되면 support@prevu3d.com으로 문의하세요.

정의

• IdP, Identity Provider(ID 공급자): 모든 사용자를 등록하고 다양한 다른 서비스에 대한 연결을 가능하게 하는 시스템을 의미합니다. 이는 조직, 사용자, 그룹에 대한 정보의 원천입니다. 예: Azure AD, JumpCloud…

• SP, Service Provider(서비스 공급자): SSO 정보를 소비하는 서비스 애플리케이션을 의미하며, 이 경우 Prevu3D Cloud입니다.

• SSO, Single Sign-On(싱글 사인온): 사용자가 단일 포털에서 자격 증명을 얻고 여러 애플리케이션에 걸쳐 사용자 관리 구성을 배포할 수 있게 하는 메커니즘을 의미합니다.

• SAML, Security Assertion Markup Language: 여러 클라우드 기반 플랫폼에서 SSO 사용을 가능하게 하는 업계 전반의 프로토콜입니다.

• SCIM, System for Cross-Domain Identity Management: 사용자와 그룹을 프로비저닝하기 위한 프로토콜입니다.