콘텐츠로 이동

자주 묻는 질문

설정 전 준비

회사에서 SAML과 OIDC 중 어떤 것을 사용해야 할지 모르겠습니다. 어떻게 선택하나요?

먼저 IdP(Identity Provider) 유형을 확인하세요.

  • Azure AD, Okta, OneAuth, Keycloak 등 표준 기업 ID 관리 제품이라면 대개 둘 다 지원합니다. 설정이 더 간편한 SAML을 우선 권장합니다(메타데이터 XML만 업로드하면 됨).

  • 자체 구축 시스템 또는 개발자 플랫폼(예: Authing, Auth0)이라면 OIDC만 지원할 수 있습니다. 이 경우 OIDC를 선택하세요.

  • 확실하지 않은 경우, IT 관리자에게 문의하여 IdP가 지원하는 프로토콜 유형을 확인하세요.

IdP에서 애플리케이션을 생성하려면 먼저 SP의 Entity ID와 콜백 URL을 제공해야 하는데, Guance에서는 먼저 IdP 메타데이터를 업로드해야 합니다. 어떻게 해야 하나요?

임시 주소를 사용하여 먼저 설정하세요.

  • Entity ID: https://auth.guance.com/saml/metadata.xml

  • ACS URL(Assertion Consumer Service URL): https://auth.guance.com/saml/assertion

IdP에 위 임시 주소를 입력하고 메타데이터 XML을 다운로드한 후, Guance에서 IdP를 생성하세요. 생성이 완료되면 실제 Entity ID와 ACS URL을 확인하여 IdP로 돌아가서 값을 교체하면 됩니다.

설정 과정 중

IdP 메타데이터를 업로드했는데 Guance에서 "구문 분석 실패" 또는 "형식 오류"가 발생합니다.

다음 사항을 확인하세요.

  1. 다운로드한 파일이 SAML 메타데이터 XML인지 확인하세요. 인증서 파일이나 다른 형식이 아닙니다.

  2. XML 파일이 완전한지 확인하세요. IdP에서 다운로드한 파일이 브라우저에 의해 잘리는 경우가 있으므로 "다른 이름으로 저장" 방식을 사용하는 것이 좋습니다.

  3. IdP에서 Entity ID와 ACS URL이 올바르게 설정되었는지 확인하세요. 설정이 비어 있으면 메타데이터에 필수 필드가 누락될 수 있습니다.

  4. 자체 서명 인증서를 사용하는 경우 인증서가 만료되지 않았는지 확인하세요.

OIDC 설정 시 "IdP URL"에는 무엇을 입력해야 하나요?

IdP의 Issuer URL(서비스 검색 주소)을 입력하세요. 일반적인 형식은 다음과 같습니다.

  • Keycloak: https://keycloak.example.com/realms/<realm-name>

  • Authing: https://<app-id>.authing.cn/oidc

  • Auth0: https://<tenant>.auth0.com/

  • 자체 구축 OIDC: https://auth.example.com

입력하면 Guance가 자동으로 .well-known/openid-configuration 엔드포인트를 검색합니다. "설정을 가져올 수 없습니다"라는 오류가 발생하면 URL이 잘못되었거나 IdP에서 검색 서비스가 활성화되지 않은 것입니다. 이 경우 비표준 OIDC 설정으로 전환하여 엔드포인트를 수동으로 입력해야 합니다.

OIDC 매핑 설정에서 "사용자 이름" 필드에는 무엇을 입력해야 하나요?

IdP가 반환하는 사용자 정보 필드 이름에 따라 달라집니다. 일반적인 대응 관계는 다음과 같습니다.

IdP 유형 사용자 이름 필드 이메일 필드 전화번호 필드
Keycloak preferred_username email phone_number
Authing name 또는 username email phone
Auth0 name email phone_number
자체 구축 시스템 실제 반환 값에 따라 입력 email 실제 반환 값에 따라 입력

확실하지 않은 경우 IdP에서 사용자 정보를 가져와서 반환된 JSON 필드 이름을 확인하세요.

역할 매핑을 설정할 때 "속성 필드"와 "속성 값"은 어떻게 입력하나요?

IdP가 사용자 인증 시 반환하는 속성에 따라 달라집니다. 예를 들어,

시나리오: 부서별 역할 할당

  • IdP가 반환하는 사용자 속성: {"department": "기술부", "role": "admin"}

  • Guance 설정:

    • 속성 필드: department

    • 속성 값: 기술부

    • 할당 역할: 표준 멤버

시나리오: 사용자 그룹별 역할 할당

  • IdP가 반환하는 사용자 속성: {"groups": ["admin", "developer"]}

  • Guance 설정:

    • 속성 필드: groups
    • 속성 값: admin(여러 값은 쉼표로 구분, 예: admin,developer)
    • 할당 역할: 관리자

속성 필드 이름은 IdP가 반환하는 값과 완전히 일치해야 합니다(대소문자 구분).

로그인 문제

IdP 로그인 페이지로는 성공적으로 리디렉션되지만, 로그인 후 Guance로 돌아오면 "사용자 정보를 가져올 수 없습니다"(OIDC)라는 오류가 발생합니다.

다음 사항을 확인하세요.

  1. 매핑 필드 오류: "이메일" 매핑 필드가 IdP가 실제로 반환하는 필드 이름과 일치하는지 확인하세요(일반적인 오류는 mail을 입력했지만 IdP가 email을 반환하는 경우).

  2. Scope 누락: 권한 부여 요청 Scope에 email이 포함되어 있고 IdP가 이메일 정보 반환에 동의했는지 확인하세요.

  3. 사용자 정보 엔드포인트 오류: 비표준 OIDC의 경우 설정 파일의 userinfo_endpoint가 올바른지 확인하세요.

  4. Token 구문 분석 실패: IdP가 사용하는 서명 알고리즘이 HS256인지 확인하세요. Guance는 현재 RS256을 지원하지 않습니다.

SAML 로그인은 성공했지만 사용자 역할이 올바르지 않습니다.

역할 매핑 설정을 확인하세요.

  1. 역할 매핑 기능이 활성화되어 있는지 확인하세요(스위치 상태).

  2. IdP에서 사용자의 속성이 올바르게 반환되는지 확인하세요(브라우저 개발자 도구로 SAML 어설션을 확인하거나 SAML 디버깅 도구 사용).

  3. "속성 필드"와 "속성 값"이 어설션의 값과 완전히 일치하는지 확인하세요.

  4. 사용자가 여러 규칙과 일치해야 하는 경우, 예상대로 최고 권한 역할이 할당되었는지 확인하세요.

SSO 로그인 후 사용자가 여러 워크스페이스를 볼 수 있지만, 전환 시 "권한 없음" 오류가 발생합니다.

이유는 다음과 같습니다.

  1. 사용자가 IdP A를 통해 워크스페이스 1에 로그인했습니다.

  2. 워크스페이스 2에도 동일한 IdP A가 설정되어 있지만 역할 매핑 규칙이 다릅니다.

  3. 사용자가 워크스페이스 2로 전환하면 Guance가 역할 매핑을 다시 확인하고, 사용자가 워크스페이스 2의 규칙과 일치하지 않음을 발견합니다.

이 경우 동일한 IdP의 역할 매핑 규칙이 모든 워크스페이스에서 일관되도록 하거나, 크로스 스페이스 사용자를 위한 일반적인 매핑 규칙(예: 통합 사용자 그룹 식별자)을 구성해야 합니다.

사용자 관리

직원이 퇴사한 경우, SSO를 통해 Guance에 로그인하는 것을 완전히 차단하려면 어떻게 해야 하나요?

두 곳에서 모두 삭제해야 합니다.

  1. IdP 측: 해당 직원의 계정을 삭제하거나 비활성화하여 기업 인증을 통한 로그인을 차단합니다.

  2. Guance 측: 관리 > 멤버 관리 > SSO 관리로 이동하여 SSO 멤버 수를 클릭하고 해당 사용자를 찾아 삭제합니다.

Guance 측에서만 삭제하면 직원이 여전히 SSO를 통해 로그인할 수 있습니다(계정이 자동으로 다시 생성됨). IdP 측에서만 삭제하면 직원이 세션이 만료될 때까지 Guance의 로그인 상태를 유지할 수 있습니다.

SSO 사용자가 Guance에 표시되는 사용자 이름을 어떻게 변경할 수 있나요?

SSO 사용자의 사용자 이름은 IdP가 반환하는 매핑 필드에 의해 결정되므로 Guance 측에서 직접 수정할 수 없습니다. 수정이 필요한 경우:

  1. IdP에서 사용자의 해당 속성(예: preferred_username 또는 name)을 수정합니다.

  2. 사용자가 Guance에 다시 로그인하면 자동으로 업데이트됩니다.

Guance에 다른 이름을 표시해야 하는 경우 IdP 관리자에게 문의하여 속성 매핑을 조정하거나, Guance에서 역할 매핑을 활성화할 때 표시 이름에 영향을 주지 않는 필드(예: 사용자 그룹)를 사용하여 권한을 제어하는 것이 좋습니다.

일부 직원은 SSO로 로그인하고, 일부 직원은 일반 계정/비밀번호로 로그인하도록 설정할 수 있나요?

네, 가능합니다. Guance는 혼합 로그인 모드를 지원합니다.

  • SSO 관리에서 IdP 및 도메인 제한을 설정합니다.

  • SSO 도메인과 일치하지 않는 사용자는 여전히 Guance 계정/비밀번호 또는 휴대폰 번호 인증 코드로 로그인할 수 있습니다.

  • SSO 도메인과 일치하는 사용자는 IdP 로그인 페이지로 안내됩니다.

주의할 점은 동일한 이메일 주소로 두 방식을 동시에 사용할 수 없다는 것입니다. 이메일이 이미 SSO에 바인딩된 경우 해당 이메일로 Guance 로컬 계정을 등록할 수 없습니다.

다중 IdP 및 크로스 스페이스

회사가 다른 회사를 인수하여 두 개의 서로 다른 Azure AD가 있습니다. 두 개를 모두 동일한 Guance 워크스페이스에 설정할 수 있나요?

네, 가능합니다. Guance 단일 워크스페이스는 최대 10개의 IdP를 지원합니다. 설정 방법:

  1. 두 개의 Azure AD를 각각 별도의 IdP로 추가합니다.

  2. 각자의 이메일 도메인(예: @company-a.com 및 @company-b.com)을 설정합니다.

  3. 각 IdP에 대해 역할 매핑 규칙을 설정합니다(규칙은 서로 다를 수 있음).

사용자가 로그인하면 Guance가 이메일 도메인을 기반으로 해당 IdP를 자동으로 매칭합니다.

"한 번 로그인으로 여러 워크스페이스에 액세스"하는 진정한 SSO(Single Sign-On)를 구현할 수 있나요?

네, 가능하지만 다음 조건을 충족해야 합니다.

  1. 여러 워크스페이스가 동일한 IdP(또는 신뢰하는 여러 IdP)로 설정되어 있어야 합니다.

  2. IdP에서 사용자의 세션이 유효한 상태(만료되지 않음)여야 합니다.

  3. 사용자가 각 워크스페이스에서 유효한 역할(역할 매핑 또는 기본 역할 할당을 통해)을 가지고 있어야 합니다.

조건이 충족되면 사용자가任一 워크스페이스에 로그인한 후, 세션 유효 기간 내에 상단의 워크스페이스 전환기를 통해 다른 워크스페이스로 직접 이동할 수 있으며 비밀번호를 다시 입력할 필요가 없습니다.

보안 및 규정 준수

SSO 사용자의 로그인 활동을 어떻게 감사(Audit)할 수 있나요?

Guance는 다음과 같은 감사 기능을 제공합니다.

  1. SSO 멤버 목록: 각 IdP를 통해 로그인한 멤버 목록과 마지막 로그인 시간을 확인할 수 있습니다.

  2. 작업 감사: 관리 > 감사 이벤트에서 사용자의 작업 기록(로그인, 로그아웃, 주요 작업 포함)을 확인할 수 있습니다.

  3. 알림 메커니즘: SSO 설정이 변경되면 Owner와 Administrator에게 이메일 알림이 전송됩니다.

문서 평가

이 페이지가 도움이 되었나요?