HCP SSO 문제 해결

HCP SSO 문제 해결 (Troubleshooting single sign-on on HCP)

HCP에서 SSO에 선호하는 아이덴티티 제공자를 설정할 때의 문제 해결 과정을 설명해 드릴게요.

출처: 문서

본문

개요 (Overview)

HCP에 SSO를 활성화할 때 발생하는 오류 문제는 두 범주 중 하나에 속해요.

HCP 설정의 오류는 우리 지원 범위 안에 있어요.
IdP 설정의 오류는 지원 범위 밖이에요. 자세한 내용과 추가 문제 해결 리소스는 아이덴티티 제공자 문서를 참고하세요.

일반적인 오류 메시지

인증 중 접근이 거부됨 (Access was denied while authenticating)
대체 인증 필요 (Alternative authentication required)
인증 중 오류 발생 (An error occurred with authentication.)
invalid_request: IdP-Initiated login is not enabled
검증된 TXT 레코드로 인식되지 않음 (Not recognized as a verified TXT record)
문제가 발생했습니다. (OIDC) (Something went wrong.)
문제가 발생했습니다. (SAML) (Something went wrong.)
요청을 진행할 수 없음 (Unable to proceed with request)

인증 중 접근이 거부됨

오류 메시지: 인증 중 접근이 거부되었습니다. (Access was denied while authenticating.)
원인: SAML SSO의 Entity ID가 잘못 구성되어 HCP에 할당된 Entity ID와 일치하지 않을 때 발생할 수 있어요.
해결 방법: 구성된 Entity ID가 HCP의 것과 일치하는지 확인해 주세요.

대체 인증 필요

오류 메시지: 대체 인증이 필요합니다. (Alternative authentication required)
원인: 조직의 SSO를 비활성화하려고 할 때 발생해요. SSO를 사용해 조직에 가입했다면 계정에 다른 로그인 방법이 구성되어 있지 않으므로 SSO를 비활성화할 수 없어요.
해결 방법: 비밀번호 또는 GitHub 인증이 활성화된 owner 또는 admin 권한 사용자에게 문의해 주세요. 그들이 대신 SSO를 비활성화할 수 있어요. SSO가 비활성화되면 그들이 조직에 가입하도록 사용자 초대를 보내줄 수 있고, 그러면 별도의 로그인 자격 증명을 만들 수 있어요.

인증 중 오류 발생

오류 메시지: 인증 중 오류가 발생했습니다. (An error occurred with authentication.)
원인: 이 오류는 사용자 메타데이터에 대한 토큰 또는 클레임 요청을 검증하는 데 문제가 있음을 나타내요.
해결 방법: 오류 페이지의 지침을 따르세요. 이 페이지에 오류에 대한 추가 정보가 제공돼요.

invalid_request: IdP-Initiated login is not enabled

오류 메시지: invalid_request: IdP-Initiated login is not enabled.
원인: 현재 HCP SSO 통합은 HCP UI에서 직접 SSO 자격 증명으로 로그인해야 해요. SSO 플랫폼에서 HCP에 직접 로그인하려고 하면 아래와 유사한 오류가 발생하는 것이 정상이에요.

invalid_request: IdP-Initiated login is not enabled for connection "HCP-SSO-11eb58f9-5983-1701-8c33-0242ac110016-samlp".
TRACKING ID: 1ee9c265894f363dd226

"Oops!, something went wrong" 메시지도 받을 수 있어요.

해결 방법: HCP Portal에서 직접 SSO 자격 증명으로 HCP에 로그인해 주세요.

Okta SAML 해결 방법

대안으로 Okta의 북마크 앱(bookmark app)을 사용해 HCP에서 IdP 시작(IdP-initiated)을 흉내 내는 타일을 만들 수 있어요. 사용할 수 있는 URL은 https://portal.cloud.hashicorp.com/login/signin?conn-id=HCP-SSO-<ORGID>-samlp예요. ORGID는 HCP Portal의 Organization Settings에서 찾을 수 있는 실제 조직 ID로 바꿔 주세요.

Microsoft Entra ID (Azure AD) SAML 해결 방법

대안으로 Basic SAML Configuration 설정에서 **"Sign-on URL"**을 설정할 수 있어요. 사용할 수 있는 URL은 https://portal.cloud.hashicorp.com/login/signin?conn-id=HCP-SSO-<ORGID>-samlp예요. ORGID는 HCP Portal의 Organization Settings에서 찾을 수 있는 실제 조직 ID로 바꿔 주세요.

검증된 TXT 레코드로 인식되지 않음

오류 메시지: 검증된 TXT 레코드로 인식되지 않습니다. (Not recognized as a verified TXT record.)
원인: 도메인 호스트에 적절한 TXT 레코드가 생성되지 않았거나 잘못 구성됐을 때 발생할 수 있어요.
해결 방법: 도메인 호스트에 TXT 레코드를 추가하거나 기존 TXT 레코드를 기대 형식과 일치하도록 수정하세요.

dig 또는 host 명령을 사용해 HCP에 대한 TXT 항목이 보이는지 확인할 수 있어요.

$ dig -t txt domain.com

$ host -t TXT domain.com

또는 이 웹사이트를 사용해 TXT 레코드를 검증할 수도 있어요.

도메인의 TXT 레코드를 조회하면 hcp-domain-verification=c886c6010596fb39XXXX18bd80c77073b3584와 유사한 형식의 값을 가진 TXT 레코드가 보여야 해요. 도메인이 성공적으로 검증되면 나머지 SSO 설정 단계를 계속할 수 있어요.

문제가 발생했습니다 (OIDC)

오류 메시지: 문제가 발생했습니다. (Something went wrong.)
이 오류는 HCP 포털로 리다이렉트해요.
원인: issuer URL이 다음 패턴 https://<domain>/을 따라야 해요.
해결 방법: URL에 트레일링 슬래시를 추가하거나 패턴과 일치하도록 조정해 주세요.

문제가 발생했습니다 (SAML)

오류 메시지: 문제가 발생했습니다. (Something went wrong.)
원인: 사용자가 SAML Response 서명을 검증할 잘못된 인증서를 제공했거나, 업스트림 IdP에서 속성 assertion 이름으로 이메일을 설정하지 않았을 수 있어요.
해결 방법: 인증서를 확인하려면 일반적으로 아이덴티티 제공자의 metadata.xml에서 필요한 정보를 얻을 수 있어요. 아이덴티티 제공자는 보통 이 파일을 다운로드할 수 있는 엔드포인트를 제공해요. 속성 assertion에 대한 자세한 내용은 지원되는 SAML 속성 목록을 참고하세요.

요청을 진행할 수 없음

오류 메시지: 요청을 진행할 수 없습니다. (Unable to proceed with the request.)
원인: 이 오류는 인증서가 잘못 구성되었거나 ACS URL이 잘못되어 발생해요.
해결 방법:
- 인증서 불일치: 인증서가 일치하는지 확인해 주세요. 인증서를 설정할 때 끝에 여분의 공백이나 추가 문자를 넣지 않았는지 확인하세요.
- 잘못된 ACS URL: "Initiate SAML Integration" 지침에서 "SSO Sign-On URL"을 제공하지만, 일부 IdP는 ?connection=HCP-SSO-<ORGID>-saml 인자를 생략한 경로로 요청을 받아요. IdP 설정에서 ACS URL로 다음 URL을 대신 사용해 보세요.

https://auth.hashicorp.com/login/callback

도메인 재사용 (Reused domains)

도메인 소유권을 증명하려면 DNS 레코드(TXT로 설정할 시크릿 값)가 필요해요. HCP는 도메인을 사용해 SSO 이메일 주소를 매칭해요. 각 HCP 조직마다 서로 다른 SSO 도메인을 사용해야 해요. 도메인 이름을 재사용하려고 하면 DNS 연결 요청이 실패해요.

지원 (Support)

HCP 조직에 SSO를 활성화할 때 다른 문제가 발생한다면 HashiCorp Help Center를 참고하거나 지원팀에 문의해 주세요.

더 알아보기 (Learn more)

SSO 개요 — HCP의 SSO 기능과 지원되는 IdP를 확인해 보세요.
SSO 관리 — SSO 구성을 업데이트·비활성화·삭제하는 방법을 알아보세요.
SAML SSO 설정 — SAML 2.0 기반 SSO를 구성하는 절차를 확인해 보세요.