OIDC¶
본 문서에서는 Guance 워크스페이스에서 OIDC/OAuth 2.0 프로토콜 기반의 단일 로그온(SSO)을 구성하는 방법을 설명합니다.
Guance는 다음 두 가지 OIDC 구성 방식을 지원합니다.
표준 OIDC 구성: OpenID Connect 표준을 준수하는 아이덴티티 제공자에 적합합니다
비표준 OIDC 구성: OAuth 2.0 기반이지만 인터페이스 규격에 차이가 있는 아이덴티티 제공자에 적합합니다
사전 준비¶
구성을 시작하기 전에 다음 준비 사항을 확인하세요.
| 준비 항목 | 설명 |
|---|---|
| IdP 관리자 권한 | 기업 아이덴티티 제공자(예: Keycloak, Authing, Auth0, 자체 구축 OIDC 서비스 등)에서 애플리케이션을 생성해야 합니다 |
| 클라이언트 자격 증명 | IdP에서 발급받은 Client ID와 Client Secret |
| 서비스 검색 주소 | IdP의 Issuer URL(예: https://****.example.com) |
| 회사 이메일 도메인 | SSO 사용자 식별에 사용되는 이메일 접미사(예: example.com) |
표준 OIDC 구성¶
1단계: 구성 페이지 진입¶
- 관리 > 멤버 관리 > SSO 관리 > 사용자 SSO로 이동합니다.
- OIDC 액세스 유형을 선택합니다.
- 아이덴티티 제공자 추가를 클릭합니다.
2단계: 연결 구성¶
- 아이덴티티 제공자 이름: 아이덴티티 관리 서비스를 제공하는 플랫폼 이름입니다. (❗️이 이름은 IdP 별칭으로 사용되며 SSO IdP 선택 화면에 표시됩니다. 원하는 IdP를 빠르게 찾을 수 있도록 적절한 이름을 입력하세요.)
- 메모: 아이덴티티 제공자에 대한 설명을 기록하기 위해 사용자가 직접 추가하는 설명 정보입니다.
- 아이덴티티 제공자 URL: 아이덴티티 제공자의 전체 URL이자 서비스 검색 주소입니다. 예: https://guance.example.com
- 클라이언트 ID: 인증 서비스에서 제공하는 고유 식별자로, 클라이언트 애플리케이션을 식별하는 데 사용됩니다.
- 클라이언트 시크릿: 클라이언트 ID와 함께 사용되어 클라이언트 애플리케이션을 인증합니다.
- 권한 부여 요청 범위(Scope): 권한 부여 요청의 범위입니다. 기본적으로
openid,profile,email이 포함되며, 필요에 따라address및phone클레임을 추가할 수 있습니다.
3단계: 매핑 구성¶
SSO 로그인을 구현하려면 아이덴티티 제공자(IdP)의 계정 정보를 Guance 계정 정보와 필드 매핑해야 합니다. 주요 필드는 다음과 같습니다.
- 사용자 이름: 필수 항목입니다. 아이덴티티 제공자의 “사용자 이름” 필드(예:
referred_username)입니다. - 이메일: 필수 항목입니다. 아이덴티티 제공자의 “이메일” 필드(예:
email)입니다. - 휴대폰 번호: 선택 항목입니다. 아이덴티티 제공자의 “휴대폰 번호” 필드(예:
phone)입니다.
4단계: 로그인 제어¶
- 액세스 제한: 로그인 이메일의 도메인 접미사가 구성된 도메인과 일치하는지 검증합니다. 일치하는 이메일만 SSO 로그인 링크에 액세스할 수 있습니다. 사용자가 처음 로그인할 때 Guance 멤버 계정을 동적으로 생성할 수 있으며, 워크스페이스에 미리 생성해 둘 필요가 없습니다.
- 역할 부여: 처음 로그인하는 SSO 계정에 역할을 할당합니다. 이미 로그인한 적이 있는 계정은 영향을 받지 않습니다.
- 워크스페이스에서 SAML 매핑이 활성화된 경우 매핑 규칙에 따라 역할을 우선 할당합니다.
- 세션 유지: SSO 로그인 세션의 비활성 유지 시간과 최대 유지 시간을 설정합니다.
세션 유지 구성¶
| 구성 항목 | 범위 | 기본값 | 설명 |
|---|---|---|---|
| 비활성 로그인 세션 유지 | 180~1440분 | 180분 | 사용자가 조작하지 않으면 자동으로 로그아웃되는 시간 |
| 로그인 세션 최대 유지 | 0~7일 | 7일 | 조작 여부와 관계없이 해당 시간이 지나면 강제 로그아웃됩니다. 0은 만료 없음을 의미합니다. |
세션 유지 시간을 변경하면 이미 로그인한 멤버는 기존 설정을 유지하며, 새로 로그인하는 멤버는 최신 설정이 적용됩니다.
역할 부여와 역할 매핑의 관계¶
- 워크스페이스에서 OIDC 역할 매핑이 비활성화된 경우: 처음 로그인하는 모든 SSO 사용자에게 여기서 구성한 기본 역할이 할당됩니다.
- 워크스페이스에서 OIDC 역할 매핑이 활성화된 경우: 매핑 규칙에 따라 역할을 우선 할당하며, 규칙과 일치하지 않는 사용자는 여기서 구성한 기본 역할을 받습니다.
사용자 측 OIDC 구성 시 주의사항¶
-
권한 부여 방식:
authorization_code권한 부여 방식만 지원합니다. 반환 유형은code여야 합니다. -
id_token서명 알고리즘: 현재HS256만 지원합니다. -
code로token을 교환하는 인증 방식:-
기본 지원:
client_secret_basic -
사용자 지정 지원 방식:
client_secret_post,client_secret_basic,none
-
-
scope범위:-
기본 범위:
openid,profile,email,phone -
사용자 지정 요구 사항:
openid가 반드시 포함되어야 하며, 나머지는 사용자 지정할 수 있습니다. 반환 결과에는email이 반드시 포함되어야 하고,phone_number는 선택적으로 반환할 수 있습니다.
-
5단계: 콜백 URL 확인¶
아이덴티티 제공자 생성이 완료되면 편집 버튼을 클릭하여 다음 URL을 확인하고 IdP에 제공합니다.
- 콜백 URL: IdP 인증 성공 후 Guance로 다시 이동하는 주소입니다.
- 로그인 시작 URL: Guance SSO 로그인 진입 주소입니다.
6단계: IdP에서 콜백 주소 구성¶
5단계에서 확인한 콜백 URL을 사용하여 IdP에서 다음 구성을 완료합니다.
- 콜백 주소(Redirect URI): Guance에서 제공한 콜백 URL을 입력합니다.
- 권한 부여 방식:
authorization_code를 지원하는지 확인합니다. - 반환 유형:
code를 지원하는지 확인합니다.
비표준 OIDC 구성¶
OAuth 2.0 기반이지만 표준 OIDC 규격을 준수하지 않는 아이덴티티 제공자에 적용되며, 주로 다음과 같은 경우에 해당합니다.
- IdP에서 표준 OIDC 탐색 엔드포인트(
.well-known/openid-configuration)를 제공하지 않는 경우 - 사용자 정보를 가져오는 API 경로 또는 반환 형식이 표준 OIDC와 다른 경우
- API 매개변수의 대소문자 스타일이 표준과 다른 경우
구성 단계¶
- 관리 > 멤버 관리 > SSO 관리 > OIDC > 아이덴티티 제공자 생성으로 이동합니다.
- 오른쪽 상단을 클릭하면 표준 OIDC 구성 페이지로 전환할 수 있습니다.
-
연결 구성:
- 아이덴티티 제공자 이름: 사용자 지정 표시 이름(최대 64자)
- 구성 파일 업로드: 템플릿을 다운로드하여 권한 부여 엔드포인트, Token 엔드포인트, 사용자 정보 엔드포인트, 필드 매핑 등의 정보를 입력한 후 업로드합니다.
- 메모: 아이덴티티 제공자에 대한 설명을 기록하기 위해 직접 추가하는 설명 정보입니다.
-
로그인 구성: 표준 OIDC와 동일하게 구성합니다(액세스 제한, 역할 부여, 세션 유지).
- 저장 후 활성화합니다.
로그인 검증¶
- SSO 로그인 페이지를 열고 전체 회사 이메일 주소를 입력합니다.
- 계정에 해당하는 아이덴티티 제공자를 선택하고 기업 인증 페이지의 요구 사항에 따라 로그인을 완료합니다.
- 인증에 성공하면 워크스페이스 선택 페이지에서 액세스 권한이 있는 워크스페이스로 이동합니다.
기존 SSO 계정은 전체 이메일 주소에 해당하는 SSO ID로 아이덴티티 제공자를 조회합니다. SSO ID가 아직 생성되지 않은 경우 액세스 제한에 따라 이메일 또는 도메인을 매칭합니다. 자세한 규칙은 사용자 로그인을 참조하세요.
주의사항¶
- 역할 매핑이 활성화된 경우: 사용자가 역할 매핑 규칙과 일치하지 않거나 역할 매핑이 비활성화된 경우 로그인 후 “액세스 권한 없음” 메시지가 표시됩니다.
- 아이덴티티 제공자를 삭제한 경우: 사용자가 SSO로 로그인할 때 삭제된 IdP에 해당하는 워크스페이스를 볼 수 없습니다.
- 다중 IdP 구성: 워크스페이스 하나에서 최대 10개의 IdP를 지원합니다. 사용자는 계정에 따라 사용 가능한 아이덴티티 제공자를 매칭하며, 기업 인증 완료 후 워크스페이스 권한에 따라 액세스할 수 있습니다.
- 계정 연결: SSO 첫 로그인 시 이메일이 기존 Guance 계정과 일치하면 자동으로 연결되며 기존 데이터가 유지됩니다.
- 매핑 필드 오류: 구성된 매핑 필드가 IdP에서 실제로 반환하는 필드와 일치하지 않으면 사용자 정보를 가져올 수 없어 로그인이 실패합니다.
더 보기¶
다음 내용에 관심이 있을 수 있습니다.

