OIDC¶

이 문서에서는 Guance 워크스페이스에서 OIDC/OAuth 2.0 프로토콜 기반 싱글 사인 온(SSO)을 구성하는 방법을 설명합니다.

Guance는 두 가지 OIDC 구성 방식을 지원합니다.

표준 OIDC 구성: OpenID Connect 표준을 준수하는 ID 공급자(IdP)에 적합

비표준 OIDC 구성: OAuth 2.0 기반이지만 인터페이스 사양에 차이가 있는 ID 공급자에 적합

사전 준비¶

구성을 시작하기 전에 다음 항목이 준비되었는지 확인하십시오.

표준 OIDC 구성¶

1단계: 구성 페이지 이동¶

1. 관리 > 멤버 관리 > SSO 관리 > 사용자 SSO로 이동합니다.
2. OIDC 액세스 유형을 선택합니다.
3. ID 공급자 추가를 클릭합니다.

2단계: 연결 구성¶

1. ID 공급자 이름: ID 관리 서비스를 제공하는 플랫폼의 이름입니다. (❗️이 이름은 IdP 별칭으로 사용되며 SSO 로그인 IdP 선택 화면에 표시됩니다. 원하는 IdP를 빠르게 찾으려면 적절한 이름을 입력하십시오.)
2. 비고: ID 공급자에 대한 설명을 기록하기 위해 사용자가 직접 추가할 수 있는 설명 정보입니다.
3. ID 공급자 URL: ID 공급자의 전체 URL이자 서비스 탐색 주소입니다. (예: https://guance.example.com)
4. 클라이언트 ID: 인증 서비스에서 제공하는 고유 식별자로, 클라이언트 애플리케이션을 식별하는 데 사용됩니다.
5. 클라이언트 시크릿: 클라이언트 ID와 함께 사용되어 클라이언트 애플리케이션을 인증합니다.
6. 권한 부여 요청 Scope: 권한 부여 요청의 범위입니다. 기본적으로 openid, profile, email이 포함되며 필요에 따라 address 및 phone 클레임을 추가할 수 있습니다.

3단계: 매핑 구성¶

SSO 로그인을 구현하려면 ID 공급자의 계정 정보를 Guance 계정 정보에 필드 매핑해야 합니다. 주요 필드는 다음과 같습니다.

1. 사용자 이름: 필수 항목입니다. ID 공급자의 "사용자 이름" 필드(예: referred_username)입니다.
2. 이메일: 필수 항목입니다. ID 공급자의 "이메일" 필드(예: email)입니다.
3. 전화번호: 선택 항목입니다. ID 공급자의 "전화번호" 필드(예: phone)입니다.

4단계: 로그인 제어¶

1. 액세스 제한: 로그인 이메일의 도메인 접미사가 구성된 도메인과 일치하는지 확인합니다. 일치하는 이메일만 SSO 로그인 링크에 액세스할 수 있습니다. 사용자가 처음 로그인할 때 Guance 멤버 계정이 동적으로 생성되며, 워크스페이스 내에서 미리 생성할 필요가 없습니다.
2. 역할 권한 부여: 처음 로그인하는 SSO 계정에 역할을 할당합니다. 처음 로그인이 아닌 계정은 영향을 받지 않습니다.
3. 워크스페이스 내에서 SAML 매핑이 활성화된 경우 매핑 규칙에 따라 역할이 우선 할당됩니다.
4. 세션 유지: SSO 로그인 세션의 비활성 유지 시간과 최대 유지 시간을 설정합니다.

세션 유지 구성¶

세션 유지 시간을 변경하면 이미 로그인한 멤버는 기존 설정을 유지하고, 새로 로그인하는 멤버부터 최신 설정이 적용됩니다.

역할 권한 부여와 역할 매핑의 관계¶

• 워크스페이스에서 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 획득¶

ID 공급자 생성이 완료되면 편집 버튼을 클릭하여 다음 URL을 획득하고 IdP에 제공합니다.

1. 콜백 URL: IdP 인증 성공 후 Guance로 리디렉션되는 주소입니다.
2. 로그인 시작 URL: Guance SSO 로그인 진입 주소입니다.

6단계: IdP에서 콜백 주소 구성¶

5단계에서 획득한 콜백 URL을 사용하여 IdP에서 다음 구성을 완료합니다.

1. 콜백 주소(Redirect URI): Guance에서 제공하는 콜백 URL을 입력합니다.
2. 권한 부여 모드: authorization_code를 지원하는지 확인합니다.
3. 반환 유형: code를 지원하는지 확인합니다.

비표준 OIDC 구성¶

OAuth 2.0 기반이지만 표준 OIDC 사양을 준수하지 않는 ID 공급자에 적합하며, 일반적으로 다음과 같은 시나리오에서 발생합니다.

• IdP가 표준 OIDC 탐색 엔드포인트(.well-known/openid-configuration)를 제공하지 않는 경우
• 사용자 정보를 가져오는 인터페이스 경로 또는 반환 형식이 표준 OIDC와 다른 경우
• 인터페이스 매개변수의 대소문자 스타일이 표준과 일치하지 않는 경우

구성 단계¶

1. 관리 > 멤버 관리 > SSO 관리 > OIDC > ID 공급자 생성으로 이동합니다.
2. 오른쪽 상단에서 전환하여 표준 OIDC 구성 페이지로 이동할 수 있습니다.
3. 연결 구성:
4. ID 공급자 이름: 사용자 정의 표시 이름(64자 제한)
5. 프로필 파일 업로드: 템플릿을 다운로드하고 인증 엔드포인트, 토큰 엔드포인트, 사용자 정보 엔드포인트, 필드 매핑 등의 정보를 입력한 후 업로드합니다.
6. 비고: ID 공급자에 대한 설명을 기록하기 위해 사용자가 직접 추가할 수 있는 설명 정보입니다.
7. 로그인 구성: 표준 OIDC와 동일하게 구성합니다(액세스 제한, 역할 권한 부여, 세션 유지).
8. 저장 및 활성화합니다.

로그인 확인¶

1. 이메일 로그인으로 Guance SSO 페이지(https://auth.guance.com/login/sso)에 접속합니다.
2. SSO 생성 시 구성한 이메일 주소를 입력하고 로그인할 워크스페이스가 속한 IDP를 선택합니다.
3. 인증 성공 후 워크스페이스 선택 화면으로 이동합니다.
4. 해당 주소로 로그인합니다.
5. 사용자 이름, 비밀번호 등을 입력합니다.
6. 로그인에 성공합니다.

주의 사항¶

1. 역할 매핑이 활성화된 경우: 사용자가 어떤 역할 매핑 규칙과도 일치하지 않거나 역할 매핑이 비활성화된 경우 로그인 시 "액세스 권한 없음"이 표시됩니다.
2. ID 공급자 삭제 후: 사용자가 SSO로 로그인할 때 삭제된 IdP에 해당하는 워크스페이스를 볼 수 없습니다.
3. 다중 IdP 구성: 단일 워크스페이스는 최대 10개의 IdP를 지원하며, 사용자 이메일 도메인이 IdP 중 하나와 일치하면 로그인할 수 있습니다.
4. 계정 연결: SSO 첫 로그인 시 이메일이 기존 Guance 계정과 일치하면 자동으로 연결되고 이전 데이터가 유지됩니다.
5. 매핑 필드 오류: 구성된 매핑 필드가 IdP에서 실제로 반환하는 필드와 일치하지 않으면 사용자 정보를 가져올 수 없어 로그인에 실패합니다.

더 읽어보기¶

다음 내용에 관심이 있을 수 있습니다.