OIDC 또는 SAML IdP에서 SCIM 구성

중요: SCIM 프로비저닝은 Gemini Enterprise 및 Looker (미리보기)에만 적용됩니다.

이 문서에서는 직원 ID 풀에서 SCIM 테넌트를 구성하는 방법을 설명합니다. SCIM에 대해 자세히 알아보려면 직원 ID 제휴를 위한 SCIM 프로비저닝을 참고하세요.

각 직원 ID 풀은 하나의 SCIM 테넌트만 지원합니다. 이미 SCIM 테넌트가 있는 풀에서 새 SCIM 테넌트를 구성하려면 먼저 기존 테넌트를 하드 삭제해야 합니다.

SCIM 테넌트의 --claim-mapping 플래그에는 특정 Common Expression Language(CEL) 표현식만 포함될 수 있습니다. 지원되는 표현식을 알아보려면 클레임 매핑을 참고하세요.

IdP가 google.subject 및 google.group에 매핑된 속성에 고유하고 비어 있지 않은 값을 제공하는지 확인합니다. 중복 값을 동기화하면 HTTP 409 Conflict 오류가 발생하고, null 또는 빈 값을 동기화하면 HTTP 400 Bad Request 오류가 발생합니다. 자세한 내용은 SCIM 지원을 참고하세요.

도메인 간 ID 관리 시스템 (SCIM)을 구성하려면 다음 단계를 따르세요.

1. Google Cloud에서 SCIM 테넌트 및 토큰 구성
2. OIDC 또는 SAML IdP에서 SCIM 구성
3. SCIM을 사용 설정하도록 공급업체 업데이트
4. SCIM 동기화 확인

Google Cloud에서 SCIM 테넌트 및 토큰 구성

Google Cloud에서 SCIM 테넌트를 구성하려면 다음을 수행합니다.

1. SCIM 테넌트를 만듭니다.

       gcloud iam workforce-pools providers scim-tenants create SCIM_TENANT_ID \
           --workforce-pool="WORKFORCE_POOL_ID" \
           --provider="PROVIDER_ID" \
           --display-name="SCIM_TENANT_DISPLAY_NAME" \
           --description="SCIM_TENANT_DESCRIPTION" \
           --claim-mapping="CLAIM_MAPPING" \
           --location="global"
       

   다음을 바꿉니다.

   • SCIM_TENANT_ID: SCIM 테넌트의 ID입니다.
   • WORKFORCE_POOL_ID: 이 문서 앞부분에서 만든 직원 풀의 ID입니다.
   • PROVIDER_ID: 이 문서 앞부분에서 만든 직원 ID 풀 공급업체의 ID입니다.
   • SCIM_TENANT_DISPLAY_NAME: SCIM 테넌트의 표시 이름입니다.
   • SCIM_TENANT_DESCRIPTION: SCIM 테넌트에 대한 설명입니다.
   • CLAIM_MAPPING: 속성 매핑의 쉼표로 구분된 목록입니다. 매핑 속성의 확장 목록은 클레임 매핑을 참고하세요. Gemini Enterprise에는 다음 매핑이 권장됩니다.

     google.subject=user.emails[0].value.lowerAscii(),google.group=group.externalId

     SCIM 테넌트에서 매핑하는 google.subject 속성은 --attribute-mapping 플래그를 사용하여 직원 ID 풀 공급업체의 google.subject 속성에 매핑된 동일한 ID를 고유하게 참조해야 합니다. SCIM 테넌트가 생성된 후에는 클레임 매핑을 업데이트할 수 없습니다. 이를 대체하려면 SCIM 테넌트를 하드 삭제하고 즉시 새 테넌트를 만들면 됩니다. SCIM 사용 시 고려사항에 대해 자세히 알아보려면 SCIM 지원을 참고하세요.

2. 명령어가 완료되면 다음을 수행합니다.

   1. 출력의 baseUri 필드에 https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID 형식으로 지정된 전체 URI를 저장합니다. 이 URI를 IdP에 제공해야 합니다.
   2. 또한 URI에서 SCIM_TENANT_UID만 저장합니다. 이 UID는 이 문서 뒷부분에서 SCIM 테넌트에 IAM 허용 정책을 설정하는 데 필요합니다.

3. SCIM 토큰을 만듭니다.

       gcloud iam workforce-pools providers scim-tenants tokens create SCIM_TOKEN_ID \
           --display-name DISPLAY_NAME \
           --scim-tenant SCIM_TENANT_ID \
           --workforce-pool WORKFORCE_POOL_ID \
           --provider PROVIDER_ID \
           --location global
       

   다음을 바꿉니다.

   • SCIM_TOKEN_ID: SCIM 토큰 ID입니다.
   • DISPLAY_NAME: SCIM 토큰의 표시 이름입니다.
   • WORKFORCE_POOL_ID: 직원 풀의 ID입니다.
   • SCIM_TENANT_ID: SCIM 테넌트의 ID입니다.
   • PROVIDER_ID: 직원 ID 풀 공급업체의 ID입니다.

4. gcloud iam workforce-pools providers scim-tenants tokens create 명령어가 완료되면 다음을 수행합니다.

   1. 출력에서 SCIM_TOKEN 값을 securityToken 필드에 저장합니다. 이 보안 토큰을 IdP에 제공해야 합니다. 보안 토큰은 이 출력에만 표시되며 분실한 경우 새 SCIM 토큰을 만들어야 합니다.

   2. 조직 정책에서 SCIM_TOKEN을 거부했는지 확인하려면 다음 명령어를 실행합니다.

      curl -v -H "Authorization: Bearer SCIM_TOKEN"  https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Users

      권한 관련 오류가 표시되면서 명령어가 실패하면 이후 단계에 설명된 gcloud organizations add-iam-policy-binding을 실행합니다. 명령어가 성공하면 이 단계를 건너뛸 수 있습니다.

5. SCIM 테넌트 및 토큰에 IAM 허용 정책을 설정합니다. 권한 관련 오류가 표시되면서 이전 단계의 curl 명령어가 실패하면 다음 명령어를 실행해야 합니다.

       gcloud organizations add-iam-policy-binding ORGANIZATION_ID \
           --member=serviceAccount:SERVICE_AGENT_EMAIL \
           --role roles/iam.scimSyncer
       

   다음을 바꿉니다.

   • ORGANIZATION_ID: 조직의 ID입니다.
   • SERVICE_AGENT_EMAIL: 서비스 에이전트의 이메일 주소입니다. 이메일 주소는 [e-mail] 형식입니다. SCIM 테넌트를 만들면 SCIM_TENANT_UID가 반환됩니다.

IdP에서 그룹을 프로비저닝할 때 displayName 필드에 제공된 각 그룹의 표시 이름이 SCIM 테넌트 내에서 고유해야 합니다. Microsoft Entra ID의 그룹 및 SCIM을 자세히 알아보려면 그룹을 참조하세요.

SCIM을 사용 설정하도록 공급업체 업데이트

공급업체에 SCIM을 사용 설정하려면 제품 타겟에 따라 --scim-usage 플래그를 설정하세요.

• 그룹에 사용 설정됨 (enabled-for-groups): Gemini Enterprise에 사용됩니다. IAM 승인 및 정책 평가에 SCIM 동기화 그룹을 사용합니다. 사용자 속성은 IdP 로그인 토큰에서 계속 가져옵니다.
• 사용자 및 그룹에 사용 설정됨 (enabled-for-users-groups): Looker (미리보기)에 사용됩니다. SCIM 동기화 사용자 및 그룹 데이터를 IAM 승인 및 OAuth 로그인 워크플로의 기본 클레임 소스로 사용합니다.

그룹에 SCIM 사용 설정 (Gemini Enterprise)

OIDC

      gcloud iam workforce-pools providers update-oidc PROVIDER_ID \
          --workforce-pool=WORKFORCE_POOL_ID \
          --location=LOCATION \
          --scim-usage=enabled-for-groups
    

다음을 바꿉니다.

• PROVIDER_ID: 직원 ID 풀 공급업체의 ID입니다.
• WORKFORCE_POOL_ID: 직원 풀의 ID입니다.
• LOCATION: 직원 풀의 위치입니다.

SAML

      gcloud iam workforce-pools providers update-saml PROVIDER_ID \
          --workforce-pool=WORKFORCE_POOL_ID \
          --location=LOCATION \
          --scim-usage=enabled-for-groups
    

다음을 바꿉니다.

• PROVIDER_ID: 직원 ID 풀 공급업체의 ID입니다.
• WORKFORCE_POOL_ID: 직원 풀의 ID입니다.
• LOCATION: 직원 풀의 위치입니다.

사용자 및 그룹에 SCIM 사용 설정 (Looker) (미리보기)

OIDC

      gcloud iam workforce-pools providers update-oidc PROVIDER_ID \
          --workforce-pool=WORKFORCE_POOL_ID \
          --location=LOCATION \
          --scim-usage=enabled-for-users-groups
    

다음을 바꿉니다.

• PROVIDER_ID: 직원 ID 풀 공급업체의 ID입니다.
• WORKFORCE_POOL_ID: 직원 풀의 ID입니다.
• LOCATION: 직원 풀의 위치입니다.

SAML

      gcloud iam workforce-pools providers update-saml PROVIDER_ID \
          --workforce-pool=WORKFORCE_POOL_ID \
          --location=LOCATION \
          --scim-usage=enabled-for-users-groups
    

다음을 바꿉니다.

• PROVIDER_ID: 직원 ID 풀 공급업체의 ID입니다.
• WORKFORCE_POOL_ID: 직원 풀의 ID입니다.
• LOCATION: 직원 풀의 위치입니다.

SCIM 동기화를 확인하려면 SCIM 동기화 확인을 참고하세요.

소유권 주장 매핑

SCIM을 구성할 때 SCIM 사용자 및 그룹 속성을 Google 속성에 매핑하도록 SCIM 테넌트에서 클레임 매핑 (--claim-mapping)을 정의합니다.

클레임 매핑에 지원되는 Google Cloud 속성

다음 표에는 Common Expression Language (CEL)를 사용하여 SCIM 테넌트 (--claim-mapping)에서 매핑할 수 있는 Google Cloud 속성이 나와 있습니다.

Google Cloud 속성	요구사항	설명	지원되는 표현식 및 한도
google.subject	필수	인증하는 사용자의 고유 식별자입니다. google.subject를 채우는 데 사용되는 기본 IdP 속성은 공급업체 매핑 (--attribute-mapping)과 SCIM 테넌트 (--claim-mapping) 모두에서 동일해야 합니다. 이러한 매핑이 일치하지 않으면 사용자가 로그인할 수는 있지만 SCIM에서 프로비저닝된 그룹의 구성원으로 인식되지 않습니다.	다음 기본 표현식으로 제한됩니다 (또는 .lowerAscii() 사용). user.externalId user.userName user.emails[0].value 최대 길이: 127바이트 참고: 이 매핑은 SCIM 테넌트가 생성된 후에는 변경할 수 없습니다. 업데이트하려면 SCIM 테넌트를 하드 삭제하고 다시 만들어야 합니다.
google.group	SCIM 그룹에 필수	SCIM을 사용하여 동기화된 그룹 멤버십의 고유 식별자입니다.	다음 기본 표현식으로 제한됩니다 (또는 .lowerAscii() 사용). group.externalId group.displayName 참고: 이 매핑은 SCIM 테넌트가 생성된 후에는 변경할 수 없습니다. 업데이트하려면 SCIM 테넌트를 하드 삭제하고 다시 만들어야 합니다.
google.display_name	선택사항	Google Cloud 콘솔에서 로그인한 사용자의 이름을 설정하는 속성입니다. IAM 허용 정책에서는 사용할 수 없습니다.	문자열 속성 (예: user.displayName 또는 user.name.formatted)에 매핑됩니다. 최대 길이는 100바이트입니다.
google.profile_photo	선택사항	Google Cloud 콘솔에서 프로필 사진으로 표시되는 사용자의 썸네일 사진 URL입니다. IAM 허용 정책에서는 사용할 수 없습니다.	유효한 URL 문자열 (예: user.photos.filter(p, p.type == 'thumbnail')[0].value 또는 user.photos[0].value)로 평가되어야 합니다.
google.email	선택사항	IdP의 이메일 주소를 직원 ID 제휴 OAuth 클라이언트 통합을 사용하여 통합된 제품에 매핑하는 데 사용되는 속성입니다. IAM 허용 정책에서는 사용할 수 없습니다.	이메일 속성 (예: user.emails.filter(e, e.type == 'work')[0].value 또는 user.emails[0].value)에 매핑됩니다.
google.posix_username	선택사항	SSH-in-browser 및 직원 ID 제휴가 있는 OS 로그인에 사용되는 고유한 POSIX 호환 사용자 이름 문자열입니다. 이 속성은 IAM 허용 정책에서 사용할 수 없습니다.	최대 길이는 32자(영문 기준)입니다.
attribute.KEY	선택사항	IAM 허용 정책에서 승인 전략을 정의하는 데 사용할 수 있는 IdP의 맞춤 속성입니다. KEY을 사용하려는 속성 이름으로 바꿉니다. 예를 들어 costcenter = "1234"와 같은 맞춤 속성을 정의하고 principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workforcePools/WORKFORCE_POOL_ID/attribute.costcenter/1234를 사용하여 이를 참조할 수 있습니다. 이 주 구성원 식별자에 액세스 권한을 부여하면 해당 비용 센터로 IdP에 구성된 모든 ID에 액세스 권한이 부여됩니다.	최대 50개의 맞춤 속성 매핑 규칙 규칙당 최대 크기: 256자(영문 기준)

주제 일관성을 위한 매핑 예시

클레임 매핑에 지원되는 속성에 설명된 대로 google.subject를 채우는 데 사용되는 기본 IdP 속성은 공급자 매핑 (--attribute-mapping)과 SCIM 테넌트 (--claim-mapping) 모두에서 동일해야 합니다. 다음 표에는 OIDC 또는 SAML IdP의 참조 예가 나와 있습니다.

Google 속성	직원 ID 풀 공급업체 매핑	SCIM 테넌트 매핑

SCIM 동기화 확인

중요: SCIM은 IdP에서 푸시하는 방식이므로 Google Cloud 에서 데이터를 적극적으로 가져오거나 연결 상태를 확인하지 않습니다. IdP와 Google Cloud 의 연결이 자동으로 중단되면 ID 데이터가 오래될 수 있습니다.

최대 90일 동안 지속되는 연장된 세션 길이 (ESL) 워크플로에서 비활성화된 사용자는 다음 동기화가 성공하거나 세션이 만료될 때까지 액세스 권한을 유지할 수 있습니다. 무단 액세스를 방지하려면 SCIM 동기화 상태를 지속적으로 모니터링하고 감사하세요.

SCIM을 구성한 후 curl를 사용하여 IAM SCIM 서비스 엔드포인트(iamscim.googleapis.com)를 쿼리하고 사용자 및 그룹이 Google Cloud에 동기화되는지 확인할 수 있습니다. 이러한 명령어에는 유효한 SCIM 토큰과 SCIM 테넌트 UID가 필요합니다. iamscim.googleapis.com 서비스는 SCIM 2.0 프로토콜 (RFC 7644)을 구현합니다. 지원되는 엔드포인트, 쿼리 필터, 제한사항에 관한 자세한 내용은 지원되는 엔드포인트 및 지원되지 않는 엔드포인트와 프로토콜 기능 제한사항을 참고하세요.

사용자 동기화 확인

사용자가 올바르게 동기화되었는지 확인하려면 다음 필터를 사용하여 사용자의 userName을 검색합니다.

curl -H "Authorization: Bearer SCIM_TOKEN" \
  "https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Users?filter=userName%20eq%20%22USER_NAME%22"

응답 예:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "Resources": [
    {
      "id": "USER_ID",
      "userName": "USER_NAME",
      ...
    }
  ]
}

그룹 동기화 확인

그룹이 올바르게 동기화되었는지 확인하려면 다음 필터를 사용하여 그룹의 displayName을 검색합니다.

curl -H "Authorization: Bearer SCIM_TOKEN" \
  "https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Groups?filter=displayName%20eq%20%22GROUP_NAME%22"

응답 예:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "Resources": [
    {
      "id": "GROUP_ID",
      "displayName": "GROUP_NAME",
      ...
    }
  ]
}

그룹 멤버십 확인

특정 사용자가 그룹의 구성원인지 확인하려면 그룹 ID와 사용자 ID를 모두 지정하는 필터를 사용하세요.

curl -H "Authorization: Bearer SCIM_TOKEN" \
  "https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Groups?filter=id%20eq%20%22GROUP_ID%22%20and%20members%20eq%20%22USER_ID%22"

사용자가 회원인 경우의 응답 예시:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "Resources": [
    {
      "id": "GROUP_ID",
      "displayName": "GROUP_NAME",
      ...
    }
  ]
}

사용자가 회원이 아닌 경우의 응답 예시:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 0,
  "Resources": []
}

참고: GROUP_ID 및 USER_ID를 가져오려면 먼저 displayName 및 userName 필터를 사용하여 그룹과 사용자를 찾으세요. ID는 응답의 id 필드에 반환됩니다. SCIM_TOKEN, SCIM_TENANT_UID, USER_NAME, GROUP_NAME, GROUP_ID, USER_ID를 실제 값으로 바꿉니다.

SCIM 테넌트 강제 삭제

SCIM 테넌트를 강제 삭제하려면 다음 단계를 따르세요.

1. 제공자에 대해 --scim-usage=enabled-for-groups 또는 --scim-usage=enabled-for-users-groups이 설정된 경우 제공자 구성에서 사용 중지합니다.

   OIDC

   gcloud iam workforce-pools providers update-oidc PROVIDER_ID \
       --workforce-pool=WORKFORCE_POOL_ID \
       --location=LOCATION \
       --scim-usage=SCIM_USAGE_UNSPECIFIED
   

   다음을 바꿉니다.

   • PROVIDER_ID: 직원 ID 풀 공급업체의 ID입니다.
   • WORKFORCE_POOL_ID: 직원 풀의 ID입니다.
   • LOCATION: 직원 풀의 위치입니다.

   SAML

   gcloud iam workforce-pools providers update-saml PROVIDER_ID \
       --workforce-pool=WORKFORCE_POOL_ID \
       --location=LOCATION \
       --scim-usage=SCIM_USAGE_UNSPECIFIED
   

   다음을 바꿉니다.

   • PROVIDER_ID: 직원 ID 풀 공급업체의 ID입니다.
   • WORKFORCE_POOL_ID: 직원 풀의 ID입니다.
   • LOCATION: 직원 풀의 위치입니다.

2. SCIM 테넌트를 삭제합니다.

   gcloud iam workforce-pools providers scim-tenants delete SCIM_TENANT_ID \
       --workforce-pool=WORKFORCE_POOL_ID \
       --provider=PROVIDER_ID \
       --hard-delete \
       --location=global
   

   다음을 바꿉니다.

   • SCIM_TENANT_ID: 삭제할 SCIM 테넌트의 ID입니다.
   • WORKFORCE_POOL_ID: 직원 풀의 ID입니다.
   • PROVIDER_ID: 직원 ID 풀 공급업체의 ID입니다.
   SCIM 테넌트 삭제를 비롯해 SCIM에 대해 자세히 알아보려면 SCIM 지원을 참조하세요.

다음 단계

• SCIM 프로비저닝 문제 해결
• 직원 ID 제휴 사용자 및 데이터 삭제
• 직원 ID 제휴 사용자 세션 취소
• 직원 ID 제휴를 지원하는 Google Cloud 제품 알아보기
• 콘솔에 대한 사용자 액세스 설정(제휴)