Okta에서 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. Okta에서 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.displayName

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

Okta에서 SCIM 구성

기존 Okta 애플리케이션에서 Okta의 SCIM을 구성하려면 다음을 수행합니다.

1. Okta 관리 콘솔에 로그인합니다.
2. 애플리케이션 > 애플리케이션으로 이동합니다.

3. 애플리케이션을 선택하거나 만듭니다.

   • 기존 애플리케이션을 선택하려면 다음을 수행합니다.

     1. Google Cloud 직원 ID 제휴 템플릿을 사용하여 만든 애플리케이션의 이름을 클릭합니다.

     2. 일반 탭에서 다음을 수행합니다.

        1. 앱 설정 창에서 수정을 클릭합니다.
        2. 테넌트 필드에 gcloud CLI에서 가져온 테넌트 ID를 입력합니다.
        3. 완료를 클릭합니다.

   • 새 애플리케이션을 만들려면 다음 단계를 따르세요.

     1. 앱 카탈로그 둘러보기를 클릭합니다.
     2. 검색 필드에 Google Cloud 직원 ID 제휴를 입력한 다음 결과에서 Google Cloud 직원 ID 제휴 통합을 선택합니다.

     3. 통합 추가를 클릭합니다.

        1. 애플리케이션 필드에 앱 이름을 입력합니다.
        2. 테넌트 필드에 gcloud CLI에서 가져온 테넌트 ID를 입력합니다.
        3. 완료를 클릭합니다.

4. 프로비저닝 탭에서 다음을 수행합니다.

   1. 통합 창에서 수정을 클릭합니다.

      1. API 토큰 필드에 Google Cloud에서 가져온 SCIM 토큰을 입력합니다.
      2. API 토큰의 유효성을 확인하려면 사용자 인증 정보 테스트를 클릭합니다.
      3. 그룹 가져오기를 선택합니다.
      4. 저장을 클릭합니다.

   2. 앱 창에서 수정을 클릭합니다.

      1. 사용자 생성, 사용자 속성 업데이트, 사용자 비활성화를 선택합니다.
      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) 모두에서 동일해야 합니다. 다음 테이블에는 Okta의 참조 예가 나와 있습니다.

Google 속성	직원 ID 풀 공급업체 매핑	SCIM 테넌트 매핑
google.subject	assertion.sub	user.externalId
google.subject	assertion.subject	user.userName
google.subject	assertion.subject.lowerAscii()	user.userName.lowerAscii()
google.subject	assertion.preferred_username	user.userName
google.subject	assertion.preferred_username.lowerAscii()	user.userName.lowerAscii()
google.subject	assertion.email	user.emails[0].value
google.subject	assertion.email.lowerAscii()	user.emails[0].value.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 제품 알아보기
• 콘솔에 대한 사용자 액세스 설정(제휴)