Microsoft Entra ID에서 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. Microsoft Entra ID에서 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을 자세히 알아보려면 그룹을 참조하세요.

Microsoft Entra ID에서 SCIM 구성

Microsoft Entra ID에서 SCIM을 구성하려면 다음을 수행합니다.

1. Azure 포털을 열고 전역 관리자 권한이 있는 사용자로 로그인합니다.
2. Microsoft Entra ID > 엔터프라이즈 앱를 선택합니다.
3. 새 애플리케이션을 클릭합니다.
4. Microsoft Entra 앱 갤러리 찾아보기에서 자체 애플리케이션 만들기를 클릭합니다.
5. 표시되는 자체 애플리케이션 만들기 패널에서 다음을 수행합니다.
   1. 앱 이름에 앱 이름을 입력합니다.
   2. 갤러리에 없는 다른 모든 애플리케이션 통합(갤러리 아님)을 선택합니다.
   3. 앱을 만들려면 만들기를 클릭합니다.
6. 애플리케이션에서 다음을 수행합니다.
   1. 관리 섹션에서 프로비저닝을 클릭합니다.
   2. 표시되는 오른쪽 창에서 새 구성을 클릭합니다.

   3. 관리자 사용자 인증 정보의 테넌트 URL에 SCIM 테넌트를 만들 때 가져온 SCIM URL에 ?aadOptscim062020을 추가하여 입력합니다. 기본 URI 끝에 ?aadOptscim062020을 추가해야 합니다.

      이 쿼리 매개변수는 SCIM PATCH 요청이 SCIM RFC 표준을 준수하는지 확인하기 위해 Microsoft Entra ID에서 필요합니다. 자세한 내용은 Microsoft 문서를 참조하세요.

      Microsoft Entra ID의 최종 테넌트 URL은 다음 형식이어야 합니다.

      https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID?aadOptscim062020

      SCIM_TENANT_UID를 SCIM 테넌트 UID로 바꿉니다.

   4. 보안 비밀 토큰에 SCIM 토큰을 만들 때 가져온 보안 비밀 토큰을 입력합니다.
   5. 직원 ID 제휴로 SCIM 구성을 테스트하려면 연결 테스트를 클릭합니다.
   6. 구성을 저장하려면 만들기를 클릭합니다.
7. 관리 섹션에서 다음을 수행합니다.
   1. 속성 매핑을 클릭합니다.
   2. Microsoft Entra ID 사용자 프로비저닝을 클릭합니다.
   3. 속성 매핑 페이지에서 다음을 수행합니다.
      1. 속성 매핑 표에서 externalId 행을 찾아 해당 행에서 수정을 클릭합니다. 속성 수정 페이지에서 다음을 수행합니다.
         1. 소스 속성 드롭다운 목록에서 objectId를 선택합니다.
         2. 확인을 클릭합니다.
      2. 속성 매핑을 저장하려면 저장을 클릭합니다.

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) 모두에서 동일해야 합니다. 다음 표에는 Microsoft Entra ID의 참조 예가 나와 있습니다.

Google 속성	직원 ID 풀 공급업체 매핑	SCIM 테넌트 매핑
google.subject	assertion.oid	user.externalId
google.subject	assertion.attributes['http://schemas.microsoft.com/identity/claims/objectidentifier'][0]	user.externalId
google.subject	assertion.email	user.emails[0].value
google.subject	assertion.attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'][0]	user.emails[0].value
google.subject	assertion.email.lowerAscii()	user.emails[0].value.lowerAscii()
google.subject	assertion.attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'][0].lowerAscii()	user.emails[0].value.lowerAscii()
google.subject	assertion.preferred_username	user.userName
google.subject	assertion.attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name'][0]	user.userName
google.subject	assertion.preferred_username.lowerAscii()	user.userName.lowerAscii()
google.subject	assertion.attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name'][0].lowerAscii()	user.userName.lowerAscii()

SCIM 동기화 확인

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

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

SCIM을 구성한 후 curl를 사용하여 사용자와 그룹이 Google Cloud에 올바르게 동기화되는지 확인할 수 있습니다. 이러한 명령어를 사용하려면 유효한 SCIM 토큰과 SCIM 테넌트 ID가 필요합니다.

사용자 동기화 확인

사용자가 올바르게 동기화되었는지 확인하려면 다음 필터를 사용하여 사용자의 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이 설정된 경우 제공자 구성에서 사용 중지합니다.

             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: 직원 풀의 위치입니다.

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 제휴를 지원하는 Google Cloud 제품 알아보기
• 콘솔에 대한 사용자 액세스 설정(제휴)