직원 ID 제휴 문제해결

이 페이지에서는 직원 ID 제휴의 일반적인 문제를 해결하는 방법을 보여줍니다.

IdP 응답 검사

이 섹션에서는 ID 공급업체(IdP)의 응답을 검사하여 이 문서에 나열된 문제를 해결하는 방법을 보여줍니다.

브라우저 기반 로그인

IdP에서 반환된 응답을 검사하려면 원하는 도구를 사용하여 HAR 파일을 생성합니다. 예를 들어 HAR 파일 생성 및 분석 도구에 대한 안내를 제공하는 Google 관리 콘솔 도구 상자 HAR Analysis를 사용할 수 있습니다.

중요: 사용자에게 HAR 파일을 요청하는 경우, 파일을 보내기 전에 HAR 파일에서 개인 식별 정보(PII)와 쿠키를 삭제하도록 요청하세요.

SAML

SAML IdP 응답을 검사하려면 다음 단계를 수행하세요.

1. 경로 /signin-callback가 있는 URL에 대해 로깅되는 HAR 파일에서 SAMLResponse 요청 매개변수의 값을 찾습니다.
2. 원하는 도구를 사용하여 디코딩합니다. 예를 들어 Google Admin Toolbox 인코딩/디코딩을 사용할 수 있습니다.

OIDC

OIDC IdP 응답을 검사하려면 다음 단계를 수행하세요.

1. 경로가 /signin-callback인 URL에 대해 로깅되는 HAR 파일에서 id_token 요청 매개변수를 찾습니다.
2. 선택한 JWT 디버깅 도구를 사용하여 디코딩합니다.

gcloud CLI

gcloud CLI를 사용할 때 IdP의 응답을 검사하려면 gcloud iam workforce-pools create-cred-config 명령어를 실행할 때 --credential-source-file 플래그에 전달한 파일의 콘텐츠를 복사한 후 다음 단계를 따르세요.

SAML

원하는 도구를 사용하여 SAML IdP 응답을 디코딩합니다. 예를 들어 Google Admin Toolbox Encode/Decode를 사용할 수 있습니다.

OIDC

선택한 JWT 디버깅 도구를 사용하여 OIDC IdP 응답을 디코딩합니다.

로그 검토

Google Cloud가 IdP와 통신하고 있는지 확인하고 트랜잭션 정보를 검토하려면 Cloud 감사 로그를 조사하면 됩니다. 로그 예시를 보려면 감사 로그 예시를 참조하세요.

인력 풀 및 공급업체 관리 오류

이 섹션에서는 인력 풀 및 공급업체를 관리할 때 발생할 수 있는 일반적인 오류를 해결하기 위한 제안사항을 설명합니다.

권한이 거부됨

이 오류는 직원 ID 제휴를 구성하려는 사용자에게 IAM 직원 풀 관리자 역할(roles/iam.workforcePoolAdmin)이 없을 때 발생합니다.

INVALID_ARGUMENT: OIDC 웹 싱글 사인온(SSO) 구성 누락

OIDC 직원 ID 풀 공급업체를 만들 때 web-sso-response-type 및 web-sso-assertion-claims-behavior 필드가 설정되지 않으면 다음 오류가 발생합니다.

ERROR: (gcloud.iam.workforce-pools.providers.create-oidc) INVALID_ARGUMENT: Missing OIDC web single sign-on config.

이 오류를 해결하려면 공급업체 만들기 섹션의 단계에 따라 OIDC 직원 ID 풀 공급업체를 만들 때 필드를 적절하게 설정하세요.

비율 제한을 초과했습니다. 나중에 다시 시도해 주세요.

이 오류는 직원 풀 리소스의 할당량 한도에 도달하면 발생합니다. 할당량 상향을 요청하려면 Google Cloud 계정 담당자에게 문의하세요.

로그인 오류

이 섹션에서는 직원 ID 제휴 사용자가 로그인할 때 발생할 수 있는 일반적인 오류를 해결하기 위한 제안사항을 설명합니다.

일반적인 로그인 오류

지정된 사용자 인증 정보가 속성 조건에 의해 거부됨

이 오류는 직원 ID 풀 공급업체에 설정된 속성 조건이 충족되지 않으면 발생합니다.

예를 들어 다음과 같은 속성 조건을 가정해 보겠습니다.

SAML

'gcp-users' in assertion.attributes.groups

OIDC

'gcp-users' in assertion.groups

이 경우 ID 공급업체(IdP)가 groups 속성으로 보낸 그룹 목록에 gcp-users가 없으면 오류가 표시됩니다.

이 오류를 해결하려면 다음 단계를 수행합니다.

1. 로그인에 사용된 제공업체를 설명하고 attributeCondition가 올바른지 확인합니다. 조건에서 지원되는 작업에 대한 자세한 내용은 언어 정의를 참조하세요.

2. IdP 응답 검사의 단계에 따라 IdP에서 반환한 속성을 확인하고 속성 조건이 올바른 형식이며 정확한지 확인합니다.

3. IdP의 관리 콘솔에 로그인하고 속성 조건에서 참조되는 IdP 속성이 올바르게 설정되었는지 확인합니다. 필요한 경우 IdP 문서를 참조하세요.

매핑된 속성은 STRING 유형이어야 함

이 오류는 오류 메시지에 지정된 속성이 속성 매핑에서 단일 값 STRING이 될 것으로 예상되지만 하나의 목록에 매핑되었을 때 SAML 직원 ID 풀 공급업자에게 발생합니다.

예를 들어 속성 매핑이 attribute.role=assertion.attributes.userRole인 SAML 직원 ID 풀 공급업체가 있다고 가정해 보겠습니다. SAML 어설션에서 Attribute는 다음 예시와 같이 여러 AttributeValue 태그를 가질 수 있습니다. 따라서 모든 SAML 속성은 목록으로 간주되므로 assertion.attributes.userRole가 목록입니다.

<saml:Attribute Name="userRole">
    <saml:AttributeValue>
      security-admin
    </saml:AttributeValue>
    <saml:AttributeValue>
      user
    </saml:AttributeValue>
</saml:Attribute>

이 예시에서는 다음 오류가 표시될 수 있습니다.

The mapped attribute 'attribute.role' must be of type STRING

이 문제를 해결하려면 다음 단계를 수행하시기 바랍니다.

1. 로그인에 사용된 공급업체를 설명하고 attributeMapping에 설정된 IdP 속성을 확인합니다. 오류 메시지에 표시된 속성과 속성을 확인합니다. 앞의 예시에서 userRole이라는 IdP 속성은 role 속성에 매핑되고 role 속성은 위의 오류 샘플에 표시됩니다.

2. 아래 안내에 따라 속성 매핑을 업데이트합니다.

   참고: google.groups만 목록을 허용합니다.

   • 오류의 원인이 목록 값인 경우 대체 가능한 안정적인 문자열 값 속성을 식별합니다. 그런 다음 첫 번째 항목을 참조하여 속성 매핑을 업데이트합니다. 앞의 예시에서 myRole이 대체 단일 값 IdP 속성으로 식별된 경우 속성 매핑은 다음과 같습니다.

     attribute.role=assertion.attributes.myRole[0]
     

   • 또는 속성이 단일 값인 것으로 알려진 경우, 목록의 첫 번째 항목을 사용하도록 속성 매핑을 업데이트하세요. 앞의 예시에서 userRole에 역할이 하나만 있으면 다음 매핑을 사용할 수 있습니다.

     attribute.role=assertion.attributes.userRole[0]
     

   • 목록에서 단일 값의 안정적인 식별자를 파생하려면 언어 정의를 참조하고 그에 따라 속성 매핑을 업데이트하세요.

IdP 응답 검사 섹션을 참조하여 IdP에서 반환한 응답을 확인합니다.

지정된 사용자 인증 정보에서 google.subject 값을 가져올 수 없음

이 오류는 필요한 클레임 google.subject가 직원 ID 풀 공급업체 구성에서 설정한 속성 매핑을 사용하여 매핑될 수 없는 경우에 발생합니다.

이 오류를 해결하려면 다음 단계를 수행합니다.

1. 공급업체를 설명하고 attributeMapping을 검사합니다. google.subject에 구성된 매핑을 식별합니다. 매핑이 올바르지 않으면 직원 ID 풀 공급업체를 업데이트하세요.

2. IdP에서 반환한 응답을 보려면 IdP 응답 검사 섹션을 참조하세요. 속성 매핑에서 google.subject에 매핑된 IdP 응답에서 속성 값을 검사합니다.

   값이 비어 있거나 잘못된 경우 IdP의 관리 콘솔에 로그인하고 구성된 속성을 검사합니다. 속성의 경우 영향을 받는 사용자의 IdP에 해당 데이터가 있는지 확인합니다. IdP 구성을 업데이트하여 속성 또는 사용자 정보를 적절히 수정합니다.

3. 로그인을 다시 시도합니다.

400. 오류가 발생했습니다.

이 오류는 요청이 예상대로 수신되지 않았거나 형식이 잘못된 경우에 발생합니다.

이 오류를 해결하려면 다음 단계를 수행합니다.

1. 사용자에게 로그인 방법 안내 섹션의 단계에 따라 올바른 로그인 단계를 따르고 있는지 확인합니다.

2. 직원 ID 풀 공급업체 구성을 IdP 구성과 비교합니다.

OIDC 로그인 오류

이 섹션에서는 직원 ID 제휴 사용자가 로그인할 때 발생할 수 있는 OIDC 관련 오류를 해결하기 위한 제안사항을 제공합니다.

제공된 사용자 인증 정보 발급자에 연결하는 중 오류 발생

이 오류는 OIDC 직원 ID 풀 공급업체가 OIDC 검색 문서 또는 JWKS URI에 연결할 수 없는 경우에 발생합니다.

이 오류를 해결하려면 다음 단계를 수행합니다.

1. 공급업체를 설명하고 구성된 issuerUri를 검사합니다. 발급기관 URI에 /.well-known/openid-configuration을 추가하여 검색 문서 URL을 구성합니다. 예를 들어 issuerUri가 https://example.com이면 검색 문서 URL은 https://example.com/.well-known/openid-configuration입니다.

2. 시크릿 탐색 창에서 검색 문서 URL을 엽니다.

   1. URL이 열리지 않거나 브라우저에 404 오류가 표시되면 IdP 문서를 참조하여 올바른 발급기관 URI를 식별합니다. 필요한 경우 직원 ID 제휴 풀 공급업체의 issuerUri를 업데이트합니다.

      IdP가 온프레미스에서 실행 중인 경우 IdP의 문서를 참조하여 인터넷을 통한 액세스를 프로비저닝하세요.

   2. URL이 열리면 다음 조건을 확인합니다.

      1. 검색 문서를 제공하기 전에 URL이 너무 많이 리디렉션되지 않는지 확인합니다. 이러한 경우 IdP 관리자에게 문의하여 문제를 해결하세요.
      2. IdP 응답 시간을 확인합니다. 응답 지연 시간을 줄이려면 IdP 관리자에게 문의하세요.
      3. 열린 검색 문서는 JSON 형식이어야 합니다.

      4. JSON에서 jwks_uri 필드를 찾습니다.

         1. 연결된 URL 값도 열리는지 확인합니다.
         2. 이 가이드의 앞부분에서 설명한 대로 URL이 조건을 충족하는지 확인합니다.

   3. 로그인을 다시 시도합니다.

SAML 로그인 오류

이 섹션에서는 직원 ID 제휴 사용자가 로그인할 때 발생할 수 있는 SAML 관련 오류를 해결하기 위한 제안사항을 제공합니다.

SAMLResponse에서 서명 확인 실패

이 오류는 직원 ID 풀 공급업체에서 구성한 IdP 메타데이터 XML에 제공된 어떤 X.509 인증서로도 IdP 응답의 서명을 확인할 수 없는 경우 SAML 직원 ID 풀 공급업체에 발생합니다. 이 오류의 일반적인 원인은 IdP의 확인 인증서가 순환되었지만 직원 ID 풀 공급업체 구성을 최신 IdP 메타데이터 XML 파일로 업데이트하지 않았기 때문입니다.

이 오류를 해결하려면 다음 단계를 수행합니다.

1. 선택사항: IdP 응답 검사의 단계에 따라 IdP에서 반환한 응답을 확인하고 응답에서 X509Certificate 필드를 찾습니다. 로그인에 사용한 공급업체를 설명하고 직원 ID 풀에 설정된 idpMetadataXml 값에 있는 X509Certificate 필드를 검사합니다. 인증서를 IdP에서 반환된 응답에 표시된 인증서와 비교하세요. 인증서가 일치해야 합니다.

2. IdP의 관리 콘솔에 로그인하고 최신 메타데이터 XML을 다운로드합니다.

3. 다운로드한 IdP 메타데이터 XML을 사용하여 직원 ID 풀 공급업체를 업데이트합니다.

4. 로그인을 다시 시도합니다.

SAML 어설션의 수신자가 올바른 ACS URL로 설정되지 않음

이 오류는 IdP 응답에 SubjectConfirmationData 태그의 Recipient 필드에 잘못된 값이 포함된 경우 SAML 직원 ID 풀 공급업체에 발생합니다.

이 오류를 해결하려면 IdP에서 리디렉션 URL 설정에 설명된 리디렉션 URL을 사용하도록 Recipient URL / Redirect URL 또는 IdP의 구성에 있는 상응하는 필드를 업데이트한 후에 다시 로그인을 시도합니다.

IdP 응답 검사의 단계에 따라 IdP에서 반환한 응답을 확인하고 Recipient 필드가 올바른지 확인합니다.

예를 들어 직원 ID 풀 공급업체 locations/global/workforcePools/example-pool/providers/example-provider의 경우 리디렉션 URL이 포함된 Recipient은 IdP의 SAML 응답에 다음과 같이 표시됩니다.

<SubjectConfirmationData Recipient="https://auth.cloud.google/signin-callback/locations/global/workforcePools/example-pool/providers/example-provider"

SAMLResponse 대상이 RP 콜백 URL과 일치하지 않음

이 오류는 IdP 응답에 Response 태그의 Destination 필드에 잘못된 값이 포함된 경우 SAML 직원 ID 풀 공급업체에 발생합니다.

이 오류를 해결하려면 IdP에서 리디렉션 URL 설정에 설명된 리디렉션 URL을 사용하도록 Destination URL / Redirect URL 또는 IdP 구성의 해당 필드를 업데이트하세요.

IdP 응답 검사의 단계에 따라 IdP에서 반환한 응답을 확인하고 Destination 필드가 올바른지 확인합니다.

예를 들어 직원 ID 풀 공급업체 locations/global/workforcePools/example-pool/providers/example-provider의 경우 리디렉션 URL이 포함된 Destination은 IdP의 SAML 응답에 다음과 같이 표시됩니다.

<Response Destination="https://auth.cloud.google/signin-callback/locations/global/workforcePools/example-pool/providers/example-provider"

잘못된 어설션: NameID가 누락되었거나 비어 있음

이 오류는 IdP에서 수신된 SAML 응답에 NameId 필드가 포함되지 않거나 빈 값이 있을 때 발생합니다.

이 오류를 해결하려면 IdP 문서를 참조하여 SAML 어설션의 제목인 NameID(일반적으로 인증 중인 사용자)을 보내도록 구성합니다.

참고: 속성 매핑에서 다른 속성을 google.subject에 매핑하더라도 NameID는 필수입니다.

IdP 응답 검사의 단계에 따라 IdP에서 반환된 응답과 설정된 NameID를 확인합니다.

모든 <AudienceRestriction>에 SAML RP 항목 ID가 포함되어야 합니다.

이 오류는 IdP의 SAML 응답에 있는 AudienceRestriction 태그가 직원 ID 풀 공급업체의 항목 ID를 나타내는 값으로 Audience 태그를 설정하지 않은 경우에 발생합니다.

이 오류를 해결하려면 다음 단계를 수행합니다.

1. SAML 응답에서 전송하는 AudienceRestriction 태그에서 대상을 구성하는 방법은 IdP 문서를 참조하세요. 일반적으로 대상은 IdP 구성에서 Entity ID 또는 Audience 필드를 설정하여 구성됩니다. 설정해야 하는 SP Entity ID 값을 보려면 직원 ID 풀 공급업체의 SAML 만들기 섹션을 참조하세요.

2. IdP 구성을 업데이트한 후 로그인을 다시 시도합니다.

IdP 응답 검사의 단계에 따라 IdP에서 반환된 응답과 설정된 AudienceRestriction를 확인합니다.