Microsoft Entra ID로 직원 ID 제휴 구성

Microsoft Entra ID라는 ID 공급업체(IdP)를 사용하여 직원 ID 제휴를 구성하고 Microsoft Graph를 사용하여 Microsoft Entra ID에서 Google Cloud 로 최대 400개까지 그룹을 매핑할 수 있습니다. 그런 후 이러한 그룹에 IAM 역할을 부여하고 그룹 구성원인 Microsoft Entra ID 사용자가 Google Cloud에 로그인하도록 허용할 수 있습니다. 이후에는 사용자가 자신에게 IAM 액세스 권한이 부여되었고 직원 ID 제휴를 지원하는 Google Cloud 제품에 액세스할 수 있습니다.

Microsoft Entra ID에서 Google Cloud로 150개 미만의 그룹을 매핑하려면 Microsoft Entra ID로 직원 ID 제휴 구성 및 사용자 로그인을 참조하세요.

주요 개념

이 섹션에서는 이 문서의 뒷부분에서 직원 ID 제휴를 구성할 때 사용되는 개념을 설명합니다.

추가 속성

최대 400개의 그룹을 매핑하려면 직원 ID 풀 공급업체를 만들 때 extra-attributes 플래그를 지정하여 추가 속성을 사용합니다. 추가 속성은 다음 프로토콜과 함께 사용할 수 있습니다.

암시적 흐름을 사용하는 OIDC
코드 흐름을 사용하는 OIDC
SAML 2.0 프로토콜

Microsoft Entra ID 애플리케이션이 토큰에 포함할 수 있는 그룹 이메일 주소 수는 SAML의 경우 150개, JWT의 경우 200개로 제한되어 있습니다. 이러한 제한에 대해 자세히 알아보려면 Microsoft Entra ID를 사용하여 애플리케이션의 그룹 클레임 구성을 참조하세요. 더 많은 그룹을 검색하기 위해 직원 ID 제휴는 Microsoft Identity의 OAuth 2.0 클라이언트 사용자 인증 정보 흐름을 사용하여 직원 ID 제휴가 Microsoft Graph API를 쿼리하고 사용자 그룹을 가져오도록 허용하는 사용자 인증 정보를 얻습니다.

추가 속성을 사용하려면 개략적으로 다음을 수행합니다.

새 Microsoft Entra ID 애플리케이션을 만들거나 Microsoft Graph API에서 사용자 그룹 멤버십을 가져오도록 기존 애플리케이션을 업데이트합니다. Microsoft Graph가 Microsoft Entra ID에서 많은 수의 그룹을 검색하는 방법은 그룹 초과분을 참조하세요.
직원 ID 풀 공급업체를 만들 때는 extra-attributes 플래그를 사용하여 Microsoft Graph API에서 사용자의 그룹 이메일 주소를 검색하도록 직원 ID 제휴를 구성합니다.

직원 ID 제휴는 Microsoft Graph API에서 최대 999개의 그룹을 검색할 수 있습니다. Microsoft Graph API가 999개를 초과하여 그룹을 반환하면 로그인이 실패합니다.

Microsoft Graph API가 반환하는 그룹 수를 줄이려면 직원 ID 풀 공급업체를 만들 때 --extra-attributes-filter 플래그를 사용하여 직원 ID 제휴 쿼리를 미세 조정할 수 있습니다.

직원 ID 제휴는 Microsoft Graph API에서 그룹을 검색한 후 액세스 토큰을 생성합니다. 직원 ID 제휴는 최대 400개까지 그룹을 액세스 토큰에 추가할 수 있으므로, 그룹 수를 400개 이하까지 필터링하려면 직원 ID 풀 공급업체를 만들 때 Common Expression Language(CEL) 표현식이 포함된 속성 매핑을 지정할 수 있습니다.

확장 속성

Gemini Enterprise만 해당

Gemini Enterprise 사용자는 확장 속성을 사용하여 Microsoft Entra ID에서 그룹을 최대 1,000개까지 매핑할 수 있습니다. 이 한도는 추가 속성의 한도보다 높습니다. 확장 속성을 사용하려면 직원 ID 풀 공급업체를 만들 때 extended-attributes 플래그를 지정합니다. 확장 속성을 사용하면 직원 ID 제휴가 Microsoft Entra ID에서 그룹 ID(UUID)를 가져옵니다.

Gemini Enterprise 사용자가 Gemini Enterprise 노트북 공유 UI에서 UUID 대신 인간이 읽을 수 있는 그룹 이름을 입력할 수 있도록 하려면 SCIM도 구성해야 합니다.

이 문서의 뒷부분에 설명된 대로 직원 ID 제휴와 IdP에서 SCIM을 구성합니다.

확장 속성은 다음 플래그를 사용하여 구성합니다.

--extended-attributes-issuer-uri
--extended-attributes-client-id
--extended-attributes-client-secret-value

확장 속성을 사용할 때는 다음과 같은 제한사항이 적용됩니다.

그룹 속성은 사용되지 않으므로 속성 매핑에서 google.groups를 구성할 필요가 없습니다. 하지만 다른 속성 매핑은 사용됩니다.
문서에 설명된 대로 다른 직원 ID 풀 공급업체 플래그를 구성할 수 있지만 이러한 설정은 직원 ID 제휴를 지원하는 Gemini Enterprise 외의 제품에 적용됩니다.
확장 속성은 로그인 후에도 세션 기간 동안 백그라운드에서 주기적으로 업데이트되고 새로고침됩니다.
Microsoft Entra ID에서는 애플리케이션에 User.Read, User.ReadBasic.All 또는 GroupMember.Read.All 대신 User.Read.All 권한을 부여해야 합니다.
확장 속성 유형 플래그 --extended-attributes-type은 azure-ad-groups-id 유형만 지원합니다.
확장 속성은 그룹을 최대 1,000개까지만 지원합니다. 반면 --extra-attributes 플래그는 최대 400개의 그룹을 지원합니다.
확장된 속성은 vertexaisearch.cloud.google을 통한 웹 로그인에만 사용할 수 있으며 콘솔 로그인이나 gcloud CLI 로그인에는 사용할 수 없습니다.

시작하기 전에

Google Cloud 조직이 설정되었는지 확인합니다.
Google Cloud CLI를 설치합니다. 설치 후 다음 명령어를 실행하여 Google Cloud CLI를 초기화합니다.
```
gcloud init
```
외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

참고: 이전에 gcloud CLI를 설치했으면 gcloud components update를 실행하여 최신 버전이 설치되어 있는지 확인하세요.
Microsoft Entra ID에서 ID 토큰이 암시적 흐름에 따라 사용 설정되었는지 확인합니다. 자세한 내용은 ID 토큰 암시적 권한 부여 사용 설정을 참조하세요.
로그인 시 IdP에서 서명된 인증 정보를 제공해야 합니다. OIDC IdP는 JWT를 제공해야 하고 SAML IdP 응답에 서명이 되어야 합니다.
조직 또는Google Cloud 제품의 변경사항에 대한 중요 정보를 검색하려면 필수 연락처를 제공해야 합니다. 자세한 내용은 직원 ID 제휴 개요를 참조하세요.
매핑하려는 모든 그룹이 Microsoft Entra ID에서 보안 그룹으로 표시되어야 합니다.
중요: 최대 999개까지 그룹을 가져올 수 있습니다.

비용

직원 ID 제휴는 무료 기능으로 제공됩니다. 하지만 직원 ID 제휴 상세 감사 로깅은 Cloud Logging을 사용합니다. Logging 가격 책정에 대한 자세한 내용은 Google Cloud Observability 가격 책정을 참조하세요.

필요한 역할

직원 ID 제휴를 구성하는 데 필요한 권한을 얻으려면 관리자에게 조직에 대한 IAM 직원 풀 관리자(roles/iam.workforcePoolAdmin) IAM 역할을 부여해 달라고 요청하세요. 역할 부여 방법에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할 또는 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

프로덕션 환경이 아닌 개발 또는 테스트 환경에서 권한을 구성하는 경우에는 직원 ID 제휴에 대한 권한도 포함된 IAM 소유자(roles/owner) 기본 역할을 부여할 수 있습니다.

Microsoft Entra ID 애플리케이션 만들기

이 섹션에서는 Microsoft Entra 관리자 포털을 사용하여 Microsoft Entra ID 애플리케이션을 만드는 방법을 보여줍니다. 또는 기존 애플리케이션을 업데이트할 수 있습니다. 자세한 내용은 Microsoft Entra ID 생태계에서 애플리케이션 설정을 참조하세요.

직원 ID 풀은 OIDC 및 SAML 프로토콜을 모두 사용하여 제휴를 지원합니다.

OIDC

OIDC 프로토콜을 사용하는 Microsoft Entra ID 애플리케이션 등록을 만들려면 다음을 수행합니다.

Microsoft Entra 관리자 포털에 로그인합니다.
ID > 애플리케이션 > 앱 등록으로 이동합니다.
애플리케이션 등록 구성을 시작하려면 다음을 수행합니다.
1. 신규 등록을 클릭합니다.
2. 애플리케이션 이름을 입력합니다.
3. 지원되는 계정 유형에서 옵션을 선택합니다.
4. 리디렉션 URI 섹션의 플랫폼 선택 드롭다운 목록에서 웹을 선택합니다.
5. 텍스트 입력란에 리디렉션 URL을 입력합니다. 사용자가 성공적으로 로그인하면 이 URL로 리디렉션됩니다. 콘솔(제휴)에 대한 액세스를 구성하는 경우 다음 URL 형식을 사용합니다.
```
https://auth.cloud.google/signin-callback/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID
```
  다음을 바꿉니다.
  - WORKFORCE_POOL_ID: 이 문서의 뒷부분에서 직원 ID 풀을 만들 때 사용할 직원 ID 풀 ID입니다(예: entra-id-oidc-pool).
  - WORKFORCE_PROVIDER_ID: 이 문서의 뒷부분에서 직원 ID 풀 공급업체를 만들 때 사용할 직원 ID 풀 공급업체 ID입니다(예: entra-id-oidc-pool-provider).
    
    ID 형식 지정에 대한 자세한 내용은 API 참고 리소스의 쿼리 매개변수 섹션을 참조하세요.
6. 애플리케이션 등록을 만들려면 등록을 클릭합니다.
7. 이 문서 뒷부분에서 제공된 속성 매핑 예시를 사용하려면 커스텀 department 속성을 만들어야 합니다.

SAML

SAML 프로토콜을 사용하는 Microsoft Entra ID 애플리케이션 등록을 만들려면 다음을 수행합니다.

Microsoft Entra 관리자 포털에 로그인합니다.
왼쪽 탐색 메뉴에서 Entra ID > 엔터프라이즈 앱으로 이동합니다.
엔터프라이즈 애플리케이션 구성을 시작하려면 다음을 수행합니다.
1. 새 애플리케이션 > 자체 애플리케이션 만들기를 클릭합니다.
2. 표시되는 자체 애플리케이션 만들기 창에 애플리케이션 이름을 입력합니다.
3. 만들기를 클릭합니다.
4. 싱글 사인온(SSO) > SAML로 이동합니다.
5. 다음과 같이 기본 SAML 구성을 업데이트합니다.
  1. 식별자(항목 ID) 필드에 다음 값을 입력합니다.
```
https://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID
```
    다음을 바꿉니다.
    - WORKFORCE_POOL_ID: 이 문서의 뒷부분에서 직원 ID 풀을 만들 때 사용할 직원 ID 풀 ID입니다(예: entra-id-saml-pool).
    - WORKFORCE_PROVIDER_ID: 이 문서의 뒷부분에서 직원 ID 풀 공급업체를 만들 때 사용할 직원 ID 풀 공급업체 ID입니다(예: entra-id-saml-pool-provider).
      
      ID 형식 지정에 대한 자세한 내용은 API 참고 리소스의 쿼리 매개변수 섹션을 참조하세요.
  2. 회신 URL(어설션 소비자 서비스 URL) 필드에 리디렉션 URL을 입력합니다. 사용자가 성공적으로 로그인하면 이 URL로 리디렉션됩니다. 콘솔(제휴)에 대한 액세스를 구성하는 경우 다음 URL 형식을 사용합니다.
```
https://auth.cloud.google/signin-callback/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID
```
    다음을 바꿉니다.
    - WORKFORCE_POOL_ID: 직원 ID 풀 ID입니다.
    - WORKFORCE_PROVIDER_ID: 직원 ID 공급업체 ID입니다.
  3. IdP에서 시작하는 사인온을 사용 설정하려면 릴레이 상태 필드를 다음 값으로 설정합니다.
```
https://console.cloud.google/
```
  4. SAML 애플리케이션 구성을 저장하려면 저장을 클릭합니다.
6. 이 문서 뒷부분에서 제공된 속성 매핑 예시를 사용하려면 커스텀 department 속성을 만들어야 합니다.

Microsoft Entra ID로 많은 수의 그룹 구성

이 섹션에서는 OIDC 및 SAML 프로토콜을 사용하여 Microsoft Entra ID에서 직원 ID 제휴로 최대 400개까지 그룹을 매핑하는 방법을 보여줍니다.

OIDC 암시적 흐름을 사용하여 Microsoft Entra ID에 많은 수의 그룹 구성

이 섹션에서는 암시적 흐름과 함께 OpenID Connect(OIDC) 프로토콜을 사용하여 Microsoft Entra ID에서 직원 ID 제휴로 최대 400개까지 그룹을 매핑하는 방법을 설명합니다.

Microsoft Entra ID 애플리케이션 구성

기존 Microsoft Entra ID 애플리케이션을 구성하거나 새로 만들 수 있습니다. 애플리케이션을 구성하려면 다음을 수행합니다.

Microsoft Entra ID 포털에서 다음을 수행합니다.
- 새 애플리케이션을 등록하려면 새 애플리케이션 등록의 안내를 따릅니다.
- 기존 애플리케이션을 업데이트하려면 다음을 수행합니다.
  - ID > 애플리케이션 > 엔터프라이즈 애플리케이션으로 이동합니다.
  - 업데이트하려는 애플리케이션을 선택합니다.
인증서 및 보안 비밀의 안내에 따라 애플리케이션에 새 클라이언트 보안 비밀번호를 만듭니다. 클라이언트 보안 비밀번호 값은 한 번만 표시되므로 값을 기록해 두어야 합니다.
만들거나 업데이트한 애플리케이션에서 다음 값을 기록해 둡니다. 이 문서의 뒷부분에서 직원 ID 풀 공급업체를 구성할 때 이러한 값을 제공해야 합니다.
- Client ID
- Issuer URI
- Client Secret
- Tenant ID
Microsoft Entra ID 그룹을 검색하려면 직원 ID 제휴가 Microsoft Graph API를 사용하여 Microsoft Entra ID의 사용자 정보에 액세스하도록 허용하는 API 권한을 추가하고 관리자 동의를 부여합니다. Microsoft Entra ID에서 다음을 수행합니다.
1. API 권한으로 이동합니다.
2. 권한 추가를 클릭합니다.
3. Microsoft API를 선택합니다.
4. 애플리케이션 권한을 선택합니다.
5. 검색창에 User.ReadBasic.All을 입력합니다.
6. 권한 추가를 클릭합니다.
Microsoft Entra ID 그룹은 그룹 객체 식별자(ID)로 검색하거나 이메일이 사용 설정된 그룹의 경우 그룹 이메일 주소로 검색할 수 있습니다.

그룹을 그룹 이메일 주소로 검색하도록 선택한 경우 다음 단계가 필요합니다.
Microsoft Entra ID 그룹을 그룹 이메일 주소로 검색하려면 다음을 수행합니다. 그룹을 그룹 객체 식별자로 검색하는 경우에는 이 단계를 건너뜁니다.
1. 검색창에 GroupMember.Read.All을 입력합니다.
2. 권한 추가를 클릭합니다.
3. 도메인 이름에 대해 관리자 동의 부여를 클릭합니다.
4. 대화상자가 표시되면 예를 클릭합니다.
5. 이전에 만들거나 업데이트한 Microsoft Entra ID 애플리케이션의 개요 페이지로 이동합니다.
6. 엔드포인트를 클릭합니다.
발급기관 URI는 /.well-known/openid-configuration 경로가 생략된 OIDC 메타데이터 문서 URI입니다.

예를 들어 OIDC 메타데이터 문서가 https://login.microsoftonline.com/d41ad248-019e-49e5-b3de-4bdfe1fapple/v2.0/.well-known/openid-configuration인 경우 발급기관 URI는 https://login.microsoftonline.com/d41ad248-019e-49e5-b3de-4bdfe1fapple/v2.0/입니다.

직원 ID 풀 만들기

gcloud

직원 ID 풀을 만들려면 다음 명령어를 실행합니다.

gcloud iam workforce-pools create WORKFORCE_POOL_ID \
    --organization=ORGANIZATION_ID \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --session-duration=SESSION_DURATION \
    --location=global

다음을 바꿉니다.

WORKFORCE_POOL_ID: Google Cloud 직원 풀을 나타내도록 선택한 ID입니다. ID 형식 지정에 대한 자세한 내용은 API 참고 리소스의 쿼리 매개변수 섹션을 참조하세요.
ORGANIZATION_ID: 직원 ID 풀에 대한 Google Cloud 조직의 숫자 조직 ID입니다. 직원 ID 풀은 조직 내 모든 프로젝트 및 폴더에서 사용할 수 있습니다.
DISPLAY_NAME: 선택사항. 직원 ID 풀 표시 이름입니다.
DESCRIPTION: 선택사항. 직원 ID 풀 설명입니다.
SESSION_DURATION: 선택사항. 세션 시간으로, s가 추가된 숫자로 표현됩니다(예: 3600s). 세션 시간은 이 직원 풀의 Google Cloud 액세스 토큰, 콘솔(제휴) 로그인 세션, gcloud CLI 로그인 세션이 유효하게 지속되는 시간을 결정합니다. 세션 시간은 기본적으로 1시간(3,600초)입니다. 세션 시간 값은 15분(900초)~12시간(43,200초) 사이여야 합니다.

콘솔

직원 ID 풀을 만들려면 다음을 수행합니다.

Google Cloud 콘솔에서 직원 ID 풀 페이지로 이동합니다.

직원 ID 풀로 이동
직원 ID 풀의 조직을 선택합니다. 직원 ID 풀은 조직 내 모든 프로젝트 및 폴더에서 사용할 수 있습니다.
풀 만들기를 클릭하고 다음을 수행합니다.
1. 이름 필드에 풀의 표시 이름을 입력합니다. 풀 ID는 자동으로 입력한 이름에서 파생되며 이름 필드 아래에 표시됩니다. 풀 ID 옆에 있는 수정을 클릭하여 풀 ID를 업데이트할 수 있습니다.
2. (선택사항) 설명에 풀 설명을 입력합니다.
3. 직원 ID 풀을 만들려면 다음을 클릭합니다.

직원 ID 풀 세션 시간 기본값은 1시간(3,600초)입니다. 세션 시간은 이 직원 풀의 Google Cloud 액세스 토큰, 콘솔(제휴) 및 gcloud CLI 로그인 세션이 유효한 기간을 결정합니다. 풀을 만들면 풀을 업데이트하여 커스텀 세션 시간을 설정할 수 있습니다. 세션 시간은 15분(900초)~12시간(43,200초) 사이여야 합니다.

OIDC 암시적 흐름 직원 ID 풀 공급업체 구성

OIDC 직원 ID 풀 공급업체를 만들려면 다음 명령어를 실행합니다.

gcloud iam workforce-pools providers create-oidc PROVIDER_ID \
    --workforce-pool=WORKFORCE_POOL_ID \
    --location=global \
    --display-name=DISPLAY_NAME \
    --issuer-uri=ISSUER_URI \
    --client-id=CLIENT_ID \
    --attribute-mapping=ATTRIBUTE_MAPPING \
    --web-sso-response-type=id-token \
    --web-sso-assertion-claims-behavior=only-id-token-claims \
    --extra-attributes-issuer-uri=EXTRA_ATTRIBUTES_ISSUER_URI \
    --extra-attributes-client-id=EXTRA_ATTRIBUTES_CLIENT_ID \
    --extra-attributes-client-secret-value=EXTRA_ATTRIBUTES_CLIENT_SECRET \
    --extra-attributes-type=EXTRA_ATTRIBUTES_TYPE  \
    --extra-attributes-filter=EXTRA_ATTRIBUTES_FILTER \
    --detailed-audit-logging

다음을 바꿉니다.

PROVIDER_ID: 고유한 공급업체 ID입니다. gcp- 프리픽스는 예약되어 있으며 풀 또는 공급업체 ID에 사용될 수 없습니다.
WORKFORCE_POOL_ID: 직원 풀 ID입니다.
DISPLAY_NAME: 공급업체의 표시 이름입니다.
ISSUER_URI: 이 문서의 앞부분에서 만든 Microsoft Entra ID 애플리케이션의 발급기관 URI입니다.
CLIENT_ID: Microsoft Entra ID 애플리케이션의 클라이언트 ID입니다.
ATTRIBUTE_MAPPING: Microsoft Entra ID에서 Google Cloud로 가져온 속성 매핑입니다. 예를 들어 Microsoft Entra ID에서 groups 및 subject 속성을 매핑하려면 다음과 같이 속성 매핑을 사용합니다.
```
--attribute-mapping=”google.groups=assertion.groups, google.subject=assertion.sub"
```
자세한 내용은 속성 매핑을 참조하세요.
EXTRA_ATTRIBUTES_ISSUER_URI: Microsoft Entra ID 애플리케이션의 발급기관 URI입니다.
EXTRA_ATTRIBUTES_CLIENT_ID: Microsoft Entra ID 애플리케이션의 클라이언트 ID입니다.
EXTRA_ATTRIBUTES_CLIENT_SECRET: Microsoft Entra ID 애플리케이션의 추가 클라이언트 보안 비밀번호입니다.
EXTRA_ATTRIBUTES_TYPE: azure-ad-groups-mail을 사용하여 그룹의 이메일 주소를 검색합니다. azure-ad-groups-id를 사용하여 그룹의 ID를 검색합니다.
EXTRA_ATTRIBUTES_FILTER: 선택사항. Microsoft Graph API에 그룹을 쿼리할 때 사용되는 필터 표현식입니다. 이 파라미터를 사용하여 IdP에서 가져온 그룹 수가 그룹 한도인 400개 미만으로 유지되도록 할 수 있습니다.
다음 예시에서는 해당 이메일 ID에 sales 프리픽스가 있는 그룹을 가져옵니다.
```
--extra-attributes-filter='"mail:sales"'
```
다음 표현식은 sales 문자열이 포함된 표시 이름을 사용하여 그룹을 가져옵니다.
```
--extra-attributes-filter='"displayName:sales"'
```
직원 ID 제휴 상세 감사 로깅은 IdP에서 수신된 정보를 Logging에 로깅합니다. 상세 감사 로깅은 직원 ID 풀 공급업체 구성 문제를 해결하는 데 도움이 될 수 있습니다. 상세 감사 로깅을 사용하여 속성 매핑 오류를 해결하는 방법은 일반 속성 매핑 오류를 참조하세요. Logging 가격 책정에 대한 자세한 내용은 Google Cloud Observability 가격 책정을 참조하세요.

직원 ID 풀 공급업체의 상세 감사 로깅을 사용 중지하려면 gcloud iam workforce-pools providers create를 실행할 때 --detailed-audit-logging 플래그를 생략합니다. 상세 감사 로깅을 사용 중지하려면 공급업체를 업데이트해도 됩니다.

OIDC 코드 흐름을 사용하여 Microsoft Entra ID에 많은 수의 그룹 구성

이 섹션에서는 코드 흐름과 함께 OIDC 프로토콜을 사용하여 Microsoft Entra ID에서 직원 ID 제휴로 최대 400개까지 그룹을 매핑하는 방법을 설명합니다.

Microsoft Entra ID 애플리케이션 구성

기존 Microsoft Entra ID 애플리케이션을 구성하거나 새로 만들 수 있습니다. 애플리케이션을 구성하려면 다음을 수행합니다.

Microsoft Entra ID 포털에서 다음을 수행합니다.
- 새 애플리케이션을 등록하려면 새 애플리케이션 등록의 안내를 따릅니다.
- 기존 애플리케이션을 업데이트하려면 다음을 수행합니다.
  - ID > 애플리케이션 > 엔터프라이즈 애플리케이션으로 이동합니다.
  - 업데이트하려는 애플리케이션을 선택합니다.
인증서 및 보안 비밀의 안내에 따라 애플리케이션에 새 클라이언트 보안 비밀번호를 만듭니다. 클라이언트 보안 비밀번호 값은 한 번만 표시되므로 값을 기록해 두어야 합니다.
만들거나 업데이트한 애플리케이션에서 다음 값을 기록해 둡니다. 이 문서의 뒷부분에서 직원 ID 풀 공급업체를 구성할 때 이러한 값을 제공해야 합니다.
- Client ID
- Issuer URI
- Client Secret
- Tenant ID
Microsoft Entra ID 그룹을 검색하려면 직원 ID 제휴가 Microsoft Graph API를 사용하여 Microsoft Entra ID의 사용자 정보에 액세스하도록 허용하는 API 권한을 추가하고 관리자 동의를 부여합니다. Microsoft Entra ID에서 다음을 수행합니다.
1. API 권한으로 이동합니다.
2. 권한 추가를 클릭합니다.
3. Microsoft API를 선택합니다.
4. 위임된 권한을 선택합니다.
5. 검색창에 User.Read를 입력합니다.
6. 권한 추가를 클릭합니다.
Microsoft Entra ID 그룹은 그룹 객체 식별자(ID)로 검색하거나 이메일이 사용 설정된 그룹의 경우 그룹 이메일 주소로 검색할 수 있습니다.

그룹을 그룹 이메일 주소로 검색하도록 선택한 경우 다음 단계가 필요합니다.
Microsoft Entra ID 그룹을 그룹 이메일 주소로 검색하려면 다음을 수행합니다. 그룹을 그룹 객체 식별자로 검색하는 경우에는 이 단계를 건너뜁니다.
1. 검색창에 GroupMember.Read.All을 입력합니다.
2. 권한 추가를 클릭합니다.
3. 도메인 이름에 대해 관리자 동의 부여를 클릭합니다.
4. 대화상자가 표시되면 예를 클릭합니다.
5. 이전에 만들거나 업데이트한 Microsoft Entra ID 애플리케이션의 개요 페이지로 이동합니다.
6. 엔드포인트를 클릭합니다.
발급기관 URI는 /.well-known/openid-configuration 경로가 생략된 OIDC 메타데이터 문서 URI입니다.

예를 들어 OIDC 메타데이터 문서가 https://login.microsoftonline.com/d41ad248-019e-49e5-b3de-4bdfe1fapple/v2.0/.well-known/openid-configuration인 경우 발급기관 URI는 https://login.microsoftonline.com/d41ad248-019e-49e5-b3de-4bdfe1fapple/v2.0/입니다.

직원 ID 풀 만들기

gcloud

직원 ID 풀을 만들려면 다음 명령어를 실행합니다.

gcloud iam workforce-pools create WORKFORCE_POOL_ID \
    --organization=ORGANIZATION_ID \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --session-duration=SESSION_DURATION \
    --location=global

다음을 바꿉니다.

WORKFORCE_POOL_ID: Google Cloud 직원 풀을 나타내도록 선택한 ID입니다. ID 형식 지정에 대한 자세한 내용은 API 참고 리소스의 쿼리 매개변수 섹션을 참조하세요.
ORGANIZATION_ID: 직원 ID 풀에 대한 Google Cloud 조직의 숫자 조직 ID입니다. 직원 ID 풀은 조직 내 모든 프로젝트 및 폴더에서 사용할 수 있습니다.
DISPLAY_NAME: 선택사항. 직원 ID 풀 표시 이름입니다.
DESCRIPTION: 선택사항. 직원 ID 풀 설명입니다.
SESSION_DURATION: 선택사항. 세션 시간으로, s가 추가된 숫자로 표현됩니다(예: 3600s). 세션 시간은 이 직원 풀의 Google Cloud 액세스 토큰, 콘솔(제휴) 로그인 세션, gcloud CLI 로그인 세션이 유효하게 지속되는 시간을 결정합니다. 세션 시간은 기본적으로 1시간(3,600초)입니다. 세션 시간 값은 15분(900초)~12시간(43,200초) 사이여야 합니다.

콘솔

직원 ID 풀을 만들려면 다음을 수행합니다.

Google Cloud 콘솔에서 직원 ID 풀 페이지로 이동합니다.

직원 ID 풀로 이동
직원 ID 풀의 조직을 선택합니다. 직원 ID 풀은 조직 내 모든 프로젝트 및 폴더에서 사용할 수 있습니다.
풀 만들기를 클릭하고 다음을 수행합니다.
1. 이름 필드에 풀의 표시 이름을 입력합니다. 풀 ID는 자동으로 입력한 이름에서 파생되며 이름 필드 아래에 표시됩니다. 풀 ID 옆에 있는 수정을 클릭하여 풀 ID를 업데이트할 수 있습니다.
2. (선택사항) 설명에 풀 설명을 입력합니다.
3. 직원 ID 풀을 만들려면 다음을 클릭합니다.

OIDC 코드 흐름 직원 ID 풀 공급업체 구성

OIDC 직원 ID 풀 공급업체를 만들려면 다음 명령어를 실행합니다.

gcloud iam workforce-pools providers create-oidc PROVIDER_ID \
    --workforce-pool=WORKFORCE_POOL_ID \
    --location=global \
    --display-name=DISPLAY_NAME \
    --issuer-uri=ISSUER_URI \
    --client-id=CLIENT_ID \
    --client-secret-value="OIDC_CLIENT_SECRET" \
    --attribute-mapping=ATTRIBUTE_MAPPING \
    --web-sso-response-type=code \
    --web-sso-assertion-claims-behavior=merge-user-info-over-id-token-claims \
    --extra-attributes-issuer-uri=EXTRA_ATTRIBUTES_ISSUER_URI \
    --extra-attributes-client-id=EXTRA_ATTRIBUTES_CLIENT_ID \
    --extra-attributes-client-secret-value=EXTRA_ATTRIBUTES_CLIENT_SECRET \
    --extra-attributes-type=EXTRA_ATTRIBUTES_TYPE  \
    --extra-attributes-filter=EXTRA_ATTRIBUTES_FILTER \
    --detailed-audit-logging

다음을 바꿉니다.

PROVIDER_ID: 고유한 공급업체 ID입니다. gcp- 프리픽스는 예약되어 있으며 풀 또는 공급업체 ID에 사용될 수 없습니다.
WORKFORCE_POOL_ID: 직원 풀 ID입니다.
DISPLAY_NAME: 공급업체의 표시 이름입니다.
ISSUER_URI: 이 문서의 앞부분에서 만든 Microsoft Entra ID 애플리케이션의 발급기관 URI입니다.
CLIENT_ID: Microsoft Entra ID 애플리케이션의 클라이언트 ID입니다.
ATTRIBUTE_MAPPING: Microsoft Entra ID에서 Google Cloud로 가져온 속성 매핑입니다. 예를 들어 Microsoft Entra ID에서 groups 및 subject 속성을 매핑하려면 다음과 같이 속성 매핑을 사용합니다.
```
--attribute-mapping=”google.groups=assertion.groups, google.subject=assertion.sub"
```
자세한 내용은 속성 매핑을 참조하세요.
EXTRA_ATTRIBUTES_ISSUER_URI: Microsoft Entra ID 애플리케이션의 발급기관 URI입니다.
EXTRA_ATTRIBUTES_CLIENT_ID: Microsoft Entra ID 애플리케이션의 클라이언트 ID입니다.
EXTRA_ATTRIBUTES_CLIENT_SECRET: Microsoft Entra ID 애플리케이션의 추가 클라이언트 보안 비밀번호입니다.
EXTRA_ATTRIBUTES_TYPE: azure-ad-groups-mail을 사용하여 그룹의 이메일 주소를 검색합니다. azure-ad-groups-id를 사용하여 그룹의 ID를 검색합니다.
EXTRA_ATTRIBUTES_FILTER: 선택사항. Microsoft Graph API에 그룹을 쿼리할 때 사용되는 필터 표현식입니다. 이 파라미터를 사용하여 IdP에서 가져온 그룹 수가 그룹 한도인 400개 미만으로 유지되도록 할 수 있습니다.
다음 예시에서는 해당 이메일 ID에 sales 프리픽스가 있는 그룹을 가져옵니다.
```
--extra-attributes-filter='"mail:sales"'
```
다음 표현식은 sales 문자열이 포함된 표시 이름을 사용하여 그룹을 가져옵니다.
```
--extra-attributes-filter='"displayName:sales"'
```
직원 ID 제휴 상세 감사 로깅은 IdP에서 수신된 정보를 Logging에 로깅합니다. 상세 감사 로깅은 직원 ID 풀 공급업체 구성 문제를 해결하는 데 도움이 될 수 있습니다. 상세 감사 로깅을 사용하여 속성 매핑 오류를 해결하는 방법은 일반 속성 매핑 오류를 참조하세요. Logging 가격 책정에 대한 자세한 내용은 Google Cloud Observability 가격 책정을 참조하세요.

직원 ID 풀 공급업체의 상세 감사 로깅을 사용 중지하려면 gcloud iam workforce-pools providers create를 실행할 때 --detailed-audit-logging 플래그를 생략합니다. 상세 감사 로깅을 사용 중지하려면 공급업체를 업데이트해도 됩니다.

SAML 2,0을 사용하여 Microsoft Entra ID에 많은 수의 그룹 구성

이 섹션에서는 SAML 2.0 프로토콜을 사용하여 Microsoft Entra ID에서 직원 ID 제휴로 최대 400개까지 그룹을 매핑하는 방법을 설명합니다.

Microsoft Entra ID 애플리케이션 구성

애플리케이션을 구성하려면 다음을 수행합니다.

Microsoft Entra ID 포털에서 다음을 수행합니다.
- 새 애플리케이션을 등록하려면 새 애플리케이션 등록의 안내를 따릅니다.
- 기존 애플리케이션을 업데이트하려면 다음을 수행합니다.
  - ID > 애플리케이션 > 엔터프라이즈 애플리케이션으로 이동합니다.
  - 업데이트하려는 애플리케이션을 선택합니다.
인증서 및 보안 비밀의 안내에 따라 애플리케이션에 새 클라이언트 보안 비밀번호를 만듭니다. 클라이언트 보안 비밀번호 값은 한 번만 표시되므로 값을 기록해 두어야 합니다.
만들거나 업데이트한 애플리케이션에서 다음 값을 기록해 둡니다. 이 문서의 뒷부분에서 직원 ID 풀 공급업체를 구성할 때 이러한 값을 제공해야 합니다.
- Client ID
- Issuer URI
- Client Secret
- Tenant ID
Microsoft Entra ID 그룹을 검색하려면 직원 ID 제휴가 Microsoft Graph API를 사용하여 Microsoft Entra ID의 사용자 정보에 액세스하도록 허용하는 API 권한을 추가하고 관리자 동의를 부여합니다. Microsoft Entra ID에서 다음을 수행합니다.
1. API 권한으로 이동합니다.
2. 권한 추가를 클릭합니다.
3. Microsoft API를 선택합니다.
4. 애플리케이션 권한을 선택합니다.
5. 검색창에 User.ReadBasic.All을 입력합니다.
6. 권한 추가를 클릭합니다.
Microsoft Entra ID 그룹은 그룹 객체 식별자(ID)로 검색하거나 이메일이 사용 설정된 그룹의 경우 그룹 이메일 주소로 검색할 수 있습니다.

그룹을 그룹 이메일 주소로 검색하도록 선택한 경우 다음 단계가 필요합니다.
Microsoft Entra ID 그룹을 그룹 이메일 주소로 검색하려면 다음을 수행합니다. 그룹을 그룹 객체 식별자로 검색하는 경우에는 이 단계를 건너뜁니다.
1. 검색창에 GroupMember.Read.All을 입력합니다.
2. 권한 추가를 클릭합니다.
3. 도메인 이름에 대해 관리자 동의 부여를 클릭합니다.
4. 대화상자가 표시되면 예를 클릭합니다.
5. 이전에 만들거나 업데이트한 Microsoft Entra ID 애플리케이션의 개요 페이지로 이동합니다.
6. 엔드포인트를 클릭합니다.
발급기관 URI는 /.well-known/openid-configuration 경로가 생략된 OIDC 메타데이터 문서 URI입니다.

예를 들어 OIDC 메타데이터 문서가 https://login.microsoftonline.com/d41ad248-019e-49e5-b3de-4bdfe1fapple/v2.0/.well-known/openid-configuration인 경우 발급기관 URI는 https://login.microsoftonline.com/d41ad248-019e-49e5-b3de-4bdfe1fapple/v2.0/입니다.

직원 ID 풀 만들기

gcloud

직원 ID 풀을 만들려면 다음 명령어를 실행합니다.

gcloud iam workforce-pools create WORKFORCE_POOL_ID \
    --organization=ORGANIZATION_ID \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --session-duration=SESSION_DURATION \
    --location=global

다음을 바꿉니다.

WORKFORCE_POOL_ID: Google Cloud 직원 풀을 나타내도록 선택한 ID입니다. ID 형식 지정에 대한 자세한 내용은 API 참고 리소스의 쿼리 매개변수 섹션을 참조하세요.
ORGANIZATION_ID: 직원 ID 풀에 대한 Google Cloud 조직의 숫자 조직 ID입니다. 직원 ID 풀은 조직 내 모든 프로젝트 및 폴더에서 사용할 수 있습니다.
DISPLAY_NAME: 선택사항. 직원 ID 풀 표시 이름입니다.
DESCRIPTION: 선택사항. 직원 ID 풀 설명입니다.
SESSION_DURATION: 선택사항. 세션 시간으로, s가 추가된 숫자로 표현됩니다(예: 3600s). 세션 시간은 이 직원 풀의 Google Cloud 액세스 토큰, 콘솔(제휴) 로그인 세션, gcloud CLI 로그인 세션이 유효하게 지속되는 시간을 결정합니다. 세션 시간은 기본적으로 1시간(3,600초)입니다. 세션 시간 값은 15분(900초)~12시간(43,200초) 사이여야 합니다.

콘솔

직원 ID 풀을 만들려면 다음을 수행합니다.

Google Cloud 콘솔에서 직원 ID 풀 페이지로 이동합니다.

직원 ID 풀로 이동
직원 ID 풀의 조직을 선택합니다. 직원 ID 풀은 조직 내 모든 프로젝트 및 폴더에서 사용할 수 있습니다.
풀 만들기를 클릭하고 다음을 수행합니다.
1. 이름 필드에 풀의 표시 이름을 입력합니다. 풀 ID는 자동으로 입력한 이름에서 파생되며 이름 필드 아래에 표시됩니다. 풀 ID 옆에 있는 수정을 클릭하여 풀 ID를 업데이트할 수 있습니다.
2. (선택사항) 설명에 풀 설명을 입력합니다.
3. 직원 ID 풀을 만들려면 다음을 클릭합니다.

SAML 2.0 직원 ID 풀 공급업체 구성

SAML 직원 ID 풀 공급업체를 만들려면 다음 명령어를 실행합니다.

gcloud iam workforce-pools providers create-saml PROVIDER_ID \
    --workforce-pool=WORKFORCE_POOL_ID \
    --location=global \
    --display-name=DISPLAY_NAME \
    --idp-metadata-path=XML_METADATA_PATH \
    --attribute-mapping=ATTRIBUTE_MAPPING \
    --extra-attributes-issuer-uri=EXTRA_ATTRIBUTES_ISSUER_URI \
    --extra-attributes-client-id=EXTRA_ATTRIBUTES_CLIENT_ID \
    --extra-attributes-client-secret-value=EXTRA_ATTRIBUTES_CLIENT_SECRET \
    --extra-attributes-type=EXTRA_ATTRIBUTES_TYPE  \
    --extra-attributes-filter=EXTRA_ATTRIBUTES_FILTER \
    --detailed-audit-logging

다음을 바꿉니다.

PROVIDER_ID: 고유한 공급업체 ID입니다. gcp- 프리픽스는 예약되어 있으며 풀 또는 공급업체 ID에 사용될 수 없습니다.
WORKFORCE_POOL_ID: 직원 풀 ID입니다.
DISPLAY_NAME: 공급업체의 표시 이름입니다.
XML_METADATA_PATH: SAML 2.0 XML 메타데이터 파일의 경로입니다.
ATTRIBUTE_MAPPING: Microsoft Entra ID에서 Google Cloud로 가져온 속성 매핑입니다. 예를 들어 Microsoft Entra ID에서 groups 및 subject 속성을 매핑하려면 다음과 같이 속성 매핑을 사용합니다.
```
--attribute-mapping=”google.groups=assertion.groups, google.subject=assertion.sub"
```
자세한 내용은 속성 매핑을 참조하세요.
EXTRA_ATTRIBUTES_ISSUER_URI: Microsoft Entra ID 애플리케이션의 발급기관 URI입니다.
EXTRA_ATTRIBUTES_CLIENT_ID: Microsoft Entra ID 애플리케이션의 클라이언트 ID입니다.
EXTRA_ATTRIBUTES_CLIENT_SECRET: Microsoft Entra ID 애플리케이션의 추가 클라이언트 보안 비밀번호입니다.
EXTRA_ATTRIBUTES_TYPE: azure-ad-groups-mail을 사용하여 그룹의 이메일 주소를 검색합니다. azure-ad-groups-id를 사용하여 그룹의 ID를 검색합니다.
EXTRA_ATTRIBUTES_FILTER: 선택사항. Microsoft Graph API에 그룹을 쿼리할 때 사용되는 필터 표현식입니다. 이 파라미터를 사용하여 IdP에서 가져온 그룹 수가 그룹 한도인 400개 미만으로 유지되도록 할 수 있습니다.
다음 예시에서는 해당 이메일 ID에 sales 프리픽스가 있는 그룹을 가져옵니다.
```
--extra-attributes-filter='"mail:sales"'
```
다음 표현식은 sales 문자열이 포함된 표시 이름을 사용하여 그룹을 가져옵니다.
```
--extra-attributes-filter='"displayName:sales"'
```
직원 ID 제휴 상세 감사 로깅은 IdP에서 수신된 정보를 Logging에 로깅합니다. 상세 감사 로깅은 직원 ID 풀 공급업체 구성 문제를 해결하는 데 도움이 될 수 있습니다. 상세 감사 로깅을 사용하여 속성 매핑 오류를 해결하는 방법은 일반 속성 매핑 오류를 참조하세요. Logging 가격 책정에 대한 자세한 내용은 Google Cloud Observability 가격 책정을 참조하세요.

직원 ID 풀 공급업체의 상세 감사 로깅을 사용 중지하려면 gcloud iam workforce-pools providers create를 실행할 때 --detailed-audit-logging 플래그를 생략합니다. 상세 감사 로깅을 사용 중지하려면 공급업체를 업데이트해도 됩니다.

그룹에 IAM 역할 부여

이 섹션에서는 Google Cloud 리소스에 대해 그룹에 역할을 부여합니다. 직원 ID 제휴 주 구성원 식별자에 대한 자세한 내용은 IAM 정책에서 직원 풀 사용자 표시를 참조하세요.

다음 예시에서는 Microsoft Entra ID 그룹의 사용자에게 스토리지 관리자 역할(roles/storage.admin)을 부여합니다.

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role="roles/storage.admin" \
    --member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_ID"

다음을 바꿉니다.

PROJECT_ID: 프로젝트 ID
WORKFORCE_POOL_ID: 직원 ID 풀 ID
GROUP_ID: 다음과 같이 직원 ID 풀 공급업체를 만드는 데 사용된 --extra-attributes-type 값에 따라 달라지는 그룹 식별자입니다.
- azure-ad-groups-mail: 그룹 식별자는 이메일 주소입니다(예: admin-group@altostrat.com).
- azure-ad-groups-id: 그룹 식별자는 그룹의 UUID입니다(예: abcdefgh-0123-0123-abcdef).

이 섹션에서는 직원 ID 풀 사용자로 로그인하여 Google Cloud 제품에 대한 액세스 권한이 있는지 테스트합니다.

이 섹션에서는 제휴 사용자로 로그인하고Google Cloud 리소스에 액세스하는 방법을 보여줍니다.

콘솔(제휴)이라고도 알려진 Google Cloud 직원 ID 제휴 콘솔에 로그인하려면 다음을 수행합니다.

콘솔(제휴) 로그인 페이지로 이동합니다.

콘솔(제휴)로 이동

다음과 같은 형식의 공급업체 이름을 입력합니다.

locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID

메시지가 표시되면 Microsoft Entra ID에 사용자 인증 정보를 입력합니다.

IdP에서 시작하는 로그인을 시작할 때는 릴레이 URL에 대해 다음을 사용합니다. https://console.cloud.google/.

브라우저 기반 로그인 과정을 사용하여 gcloud CLI에 로그인하려면 다음을 수행합니다.

구성 파일 만들기

로그인 구성 파일을 만들려면 다음 명령어를 실행합니다. 선택적으로 --activate 플래그를 추가하여 gcloud CLI에 대한 기본값으로 파일을 활성화할 수 있습니다. 그러면 구성 파일 경로를 매번 지정하지 않고도 gcloud auth login을 실행할 수 있습니다.

gcloud iam workforce-pools create-login-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --output-file=LOGIN_CONFIG_FILE_PATH

다음을 바꿉니다.

WORKFORCE_POOL_ID: 직원 풀 ID입니다.
PROVIDER_ID: 공급업체 ID입니다.
LOGIN_CONFIG_FILE_PATH: 지정하는 구성 파일의 경로입니다(예: login.json).

파일에는 브라우저 기반 인증 흐름을 사용 설정하고 잠재고객을 직원 ID 풀 공급업체에 구성된 IdP로 설정하도록 gcloud CLI에서 사용된 엔드포인트가 포함됩니다. 이 파일에는 기밀 정보가 포함되지 않습니다.

결과는 다음과 유사합니다.

{
  "type": "external_account_authorized_user_login_config",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
  "auth_url": "https://auth.cloud.google/authorize",
  "token_url": "https://sts.googleapis.com/v1/oauthtoken",
  "token_info_url": "https://sts.googleapis.com/v1/introspect",
}

gcloud auth login에서 이 구성 파일을 자동으로 사용하지 않게 하려면 gcloud config unset auth/login_config_file을 실행하여 설정 해제하면 됩니다.

브라우저 기반 인증을 사용하여 로그인

브라우저 기반 로그인 인증을 사용하여 인증하려면 다음 방법 중 하나를 사용할 수 있습니다.

구성 파일을 만들 때 --activate 플래그를 사용하거나 gcloud config set auth/login_config_file로 구성 파일을 활성화한 경우 gcloud CLI에서 자동으로 구성 파일을 사용합니다.
```
gcloud auth login
```
구성 파일의 위치를 지정하여 로그인하려면 다음 명령어를 실행합니다.
```
gcloud auth login --login-config=LOGIN_CONFIG_FILE_PATH
```
환경 변수를 사용하여 구성 파일의 위치를 지정하려면 CLOUDSDK_AUTH_LOGIN_CONFIG_FILE을 구성 경로로 설정합니다.

브라우저 기반 로그인 사용 중지

로그인 구성 파일 사용을 중단하려면 다음을 수행합니다.

구성 파일을 만들 때 --activate 플래그를 사용했거나 gcloud config set auth/login_config_file로 구성 파일을 활성화한 경우 다음 명령어를 실행하여 설정을 해제해야 합니다.
```
gcloud config unset auth/login_config_file
```
CLOUDSDK_AUTH_LOGIN_CONFIG_FILE 환경 변수가 설정되어 있으면 지웁니다.

gcloud CLI를 사용하여 Microsoft Entra ID에 로그인하려면 다음을 수행합니다.

OIDC

로그인 요청 보내기의 단계를 수행합니다. OIDC를 사용하여 Microsoft Entra ID로 애플리케이션에 사용자를 로그인합니다.
리디렉션 URL의 id_token 파라미터에서 ID 토큰을 복사하여 로컬 머신의 안전한 위치에 있는 파일에 저장합니다. 이후 단계에서 PATH_TO_OIDC_ID_TOKEN을 이 파일의 경로로 설정합니다.

다음 명령어를 실행하여 이 단계의 뒷부분에 있는 예시와 비슷한 구성 파일을 생성합니다.

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token \
    --credential-source-file=PATH_TO_OIDC_ID_TOKEN \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file=config.json

다음을 바꿉니다.

WORKFORCE_POOL_ID: 직원 ID 풀 ID입니다.
WORKFORCE_PROVIDER_ID: 직원 ID 풀 공급업체 ID입니다.
PATH_TO_OIDC_ID_TOKEN: IdP 토큰이 저장된 파일 위치의 경로입니다.
WORKFORCE_POOL_USER_PROJECT: 할당량 및 결제에 사용되는 프로젝트 번호 또는 ID입니다. 주 구성원에게 이 프로젝트에 대한 serviceusage.services.use 권한이 있어야 합니다.

명령어가 완료되면 Microsoft Entra ID에서 다음 구성 파일을 만듭니다.

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "file": "PATH_TO_OIDC_CREDENTIALS"
  }
}

gcloud CLI를 열고 다음 명령어를 실행합니다.
```
gcloud auth login --cred-file=PATH_TO_OIDC_CREDENTIALS
```
PATH_TO_OIDC_CREDENTIALS를 이전 단계의 출력 파일 경로로 바꿉니다.

gcloud CLI는 사용자 인증 정보를 보안 토큰 서비스 엔드포인트에 투명하게 게시합니다. 엔드포인트에서 임시 Google Cloud 액세스 토큰으로 교환됩니다.

이제Google Cloud에 대해 gcloud CLI 명령어를 실행할 수 있습니다.

SAML

Microsoft Entra ID 애플리케이션에 사용자를 로그인하고 SAML 응답을 가져옵니다.
Microsoft Entra ID에서 반환한 SAML 응답을 로컬 머신의 안전한 위치에 저장한 후 다음과 같이 경로를 저장합니다.
```
SAML_ASSERTION_PATH=SAML_ASSERTION_PATH
```

사용자 인증 정보 구성 파일을 생성하려면 다음 명령어를 실행합니다.

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2 \
    --credential-source-file=SAML_ASSERTION_PATH  \
    --workforce-pool-user-project=PROJECT_ID  \
    --output-file=config.json

다음을 바꿉니다.

WORKFORCE_PROVIDER_ID: 이 가이드의 앞부분에서 만든 직원 ID 풀 공급업체의 ID입니다.
WORKFORCE_POOL_ID: 이 가이드의 앞부분에서 만든 직원 ID 풀의 ID입니다.
SAML_ASSERTION_PATH: SAML 어설션 파일의 경로입니다.
PROJECT_ID: 프로젝트 ID

생성되는 구성 파일은 다음과 유사합니다.

{
   "type": "external_account",
   "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
   "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
   "token_url": "https://sts.googleapis.com/v1/token",
   "credential_source": {
     "file": "SAML_ASSERTION_PATH"
   },
   "workforce_pool_user_project": "PROJECT_ID"
}

직원 ID 제휴 토큰 교환을 사용하여 gcloud CLI에 로그인하려면 다음 명령어를 실행합니다.
```
gcloud auth login --cred-file=config.json
```
그러 후에는 gcloud CLI가 임시 Google Cloud 액세스 토큰에 대해 Microsoft Entra ID 사용자 인증 정보를 투명하게 교환합니다. 이 액세스 토큰을 사용하여 Google Cloud에 액세스할 수 있습니다.

다음과 비슷한 출력이 표시됩니다.
```
Authenticated with external account user credentials for:
[principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/USER_ID].
```
사용자 인증 정보 계정과 활성 계정을 나열하려면 다음 명령어를 실행합니다.
```
gcloud auth list
```

액세스 테스트

이제 직원 ID 제휴를 지원하고 액세스 권한이 부여된 Google Cloud 서비스에 액세스할 수 있습니다. 이 문서의 앞부분에서는 TEST_PROJECT_ID 프로젝트의 gcloud projects add-iam-policy-binding에 지정한 그룹 식별자 내에 있는 모든 ID에 스토리지 관리자 역할(roles/storage.admin)을 부여했습니다.

이제 Cloud Storage 버킷을 나열하여 액세스 권한이 있는지 테스트할 수 있습니다.

콘솔(제휴)

콘솔(제휴)을 사용하여 액세스 권한이 있는지 테스트하려면 다음을 수행합니다.

Cloud Storage 페이지로 이동합니다.

Cloud Storage로 이동
TEST_PROJECT_ID의 기존 버킷 목록이 표시되는지 확인합니다.

gcloud CLI

gcloud CLI를 사용하여 액세스 권한이 있는지 테스트하려면 액세스할 수 있는 프로젝트의 Cloud Storage 버킷 및 객체를 나열하면 됩니다. 이렇게 하려면 다음 명령어를 실행합니다. 주 구성원에게 지정된 프로젝트에 대한 serviceusage.services.use 권한이 있어야 합니다.

gcloud storage ls --project="TEST_PROJECT_ID"

사용자 삭제하기

직원 ID 제휴는 제휴 사용자 ID에 대한 사용자 메타데이터와 리소스를 만듭니다. IdP에서 사용자를 삭제하는 경우 Google Cloud에서도 해당 리소스를 명시적으로 삭제해야 합니다. 이렇게 하려면 직원 ID 제휴 사용자 및 데이터 삭제를 참조하세요.

리소스가 삭제된 사용자와 계속 연결된 것으로 표시될 수 있습니다. 이는 사용자 메타데이터 및 리소스 삭제를 위해 장기 실행 작업이 필요하기 때문입니다. 사용자 ID 삭제를 시작한 후에는 프로세스가 완료되거나 취소되기 전까지 삭제 이전에 사용자가 시작한 프로세스가 계속 실행될 수 있습니다.

SCIM 구성

Gemini Enterprise만 해당

이 섹션에서는 직원 ID 풀에서 SCIM 테넌트를 구성하는 방법을 설명합니다.

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

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

중요: IdP가 SCIM을 사용하여 google.subject 및 google.group에 매핑하는 속성에 고유한 값을 제공하는지 확인합니다. 자세한 내용은 SCIM 지원을 참조하세요.

도메인 간 ID 관리 시스템(SCIM)을 구성하려면 다음을 수행해야 합니다.

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

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

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

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: 속성 매핑의 쉼표로 구분된 목록입니다. 다음 속성 매핑을 사용하는 것이 좋습니다.
```
google.subject=user.externalId,google.group=group.externalId
```
  SCIM 테넌트에서 매핑하는 google.subject 속성은 --attribute-mapping 플래그를 사용하여 직원 ID 풀 공급업체의 google.subject 속성에 매핑된 동일한 ID를 고유하게 참조해야 합니다. SCIM 테넌트가 생성된 후에는 클레임 매핑을 업데이트할 수 없습니다. 이를 대체하려면 SCIM 테넌트를 하드 삭제하고 즉시 새 테넌트를 만들면 됩니다. SCIM 사용 시 고려사항에 대해 자세히 알아보려면 SCIM 지원을 참조하세요.
명령어가 완료되면 다음을 수행합니다.
1. 출력의 baseUri 필드에 https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID 형식으로 지정된 전체 URI를 저장합니다. 이 URI를 IdP에 제공해야 합니다.
2. 또한 URI에서 SCIM_TENANT_UID만 저장합니다. 이 UID는 이 문서 뒷부분에서 IAM 정책을 SCIM 테넌트에 설정하는 데 필요합니다.

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입니다.

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을 실행합니다. 명령어가 성공하면 이 단계를 건너뛸 수 있습니다.
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 서비스 에이전트의 이메일 주소입니다. 이메일 주소는 o-ORGANIZATION_ID-SCIM_TENANT_UID@gcp-sa-iamscim.iam.gserviceaccount.com 형식입니다. SCIM 테넌트를 만들면 SCIM_TENANT_UID가 반환됩니다.

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

Microsoft Entra ID에서 SCIM 구성

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

Azure 포털을 열고 전역 관리자 권한이 있는 사용자로 로그인합니다.
Microsoft Entra ID > 엔터프라이즈 앱을 선택합니다.
새 애플리케이션을 클릭합니다.
Microsoft Entra 앱 갤러리 찾아보기에서 자체 애플리케이션 만들기를 클릭합니다.
표시되는 자체 애플리케이션 만들기 패널에서 다음을 수행합니다.
1. 앱 이름에 앱 이름을 입력합니다.
2. 갤러리에 없는 다른 모든 애플리케이션 통합(갤러리 아님)을 선택합니다.
3. 앱을 만들려면 만들기를 클릭합니다.
애플리케이션에서 다음을 수행합니다.
1. 관리 섹션에서 프로비저닝을 클릭합니다.
2. 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로 바꿉니다.
3. 보안 비밀 토큰에 SCIM 테넌트를 만들 때 가져온 보안 비밀 토큰을 입력합니다.
4. 직원 ID 제휴로 SCIM 구성을 테스트하려면 연결 테스트를 클릭합니다.
5. 구성을 저장하려면 만들기를 클릭합니다.
관리 섹션에서 다음을 수행합니다.
1. 속성 매핑을 클릭합니다.
2. Microsoft Entra ID 사용자 프로비저닝을 클릭합니다.
3. 속성 매핑 페이지에서 다음을 수행합니다.
  1. 속성 매핑 표에서 externalId 행을 찾아 해당 행에서 수정을 클릭합니다. 속성 수정 페이지에서 다음을 수행합니다.
    1. 이 속성을 사용하여 객체 일치에서 Yes를 선택합니다.
    2. 일치 우선순위에 2를 입력합니다.
    3. 소스 속성 드롭다운 목록에서 objectId를 선택합니다.
    4. 속성 매핑을 저장하려면 확인을 클릭합니다.
  2. 속성 매핑 표에서 userName 행을 찾아 해당 행에서 수정을 클릭합니다. 속성 수정 페이지에서 다음을 수행합니다.
    1. 이 속성을 사용하여 객체 일치에서 No를 선택합니다.
    2. 속성 매핑을 저장하려면 확인을 클릭합니다.
  3. 속성 매핑 표에서 externalId 행을 찾아 해당 행에서 수정을 클릭합니다. 속성 수정 페이지에서 다음을 수행합니다.
    1. 일치 우선순위에 1을 입력합니다.
    2. 속성 매핑을 저장하려면 확인을 클릭합니다.
4. Microsoft Entra ID 그룹 프로비저닝을 클릭합니다.
5. 속성 매핑 페이지에서 다음을 수행합니다.
  1. 속성 매핑 표에서 externalId 행을 찾아 해당 행에서 수정을 클릭합니다. 속성 수정 페이지에서 다음을 수행합니다.
    1. 이 속성을 사용하여 객체 일치에서 Yes를 선택합니다.
    2. 일치 우선순위에 2를 입력합니다.
    3. 소스 속성 드롭다운 목록에서 objectId를 선택합니다.
    4. 속성 매핑을 저장하려면 확인을 클릭합니다.
  2. 속성 매핑 표에서 displayName 행을 찾아 해당 행에서 수정을 클릭합니다. 속성 수정 페이지에서 다음을 수행합니다.
    1. 이 속성을 사용하여 객체 일치에서 No를 선택합니다.
    2. 속성 매핑을 저장하려면 확인을 클릭합니다.
  3. 속성 매핑 표에서 externalId 행을 찾아 해당 행에서 수정을 클릭합니다. 속성 수정 페이지에서 다음을 수행합니다.
    1. 일치 우선순위에 1을 입력합니다.
    2. 속성 매핑을 저장하려면 확인을 클릭합니다.

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

공급업체에 SCIM을 사용 설정하려면 다음 단계를 따르세요.

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 속성 매핑

직원 ID 풀 공급업체와 공급업체에 대해 구성된 SCIM 테넌트 모두에서 속성을 일관되게 매핑해야 합니다. 직원 ID 풀 공급업체의 경우 --attribute-mapping 플래그를 사용하고 SCIM 테넌트의 경우 --claim-mapping 플래그를 사용합니다. 사용자의 google.subject에 매핑된 IdP 속성은 토큰에 정의되었는지 SCIM 매핑에 정의되었는지에 관계없이 동일한 ID를 고유하게 참조해야 합니다. SCIM을 사용할 때 속성을 매핑하는 방법을 자세히 알아보려면 SCIM 지원 섹션을 참조하세요. 다음 표에는 토큰 클레임의 속성과 SCIM 속성을 매핑하는 방법이 나와 있습니다.

Google 속성	직원 ID 풀 공급업체 매핑	SCIM 테넌트 매핑
`google.subject`	`assertion.oid`	`user.externalId`
`google.subject`	`assertion.email`	`user.emails[0].value`
`google.subject`	`assertion.email.lowerAscii()`	`user.emails[0].value.lowerAscii()`
`google.subject`	`assertion.preferred_username`	`user.userName`
`google.group`: 공급업체를 `--scim-usage=enabled-for-groups`로 업데이트하도록 지원	`N/A`	`group.externalId`

SCIM 테넌트 삭제

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 지원을 참조하세요.

Microsoft Entra ID로 직원 ID 제휴 구성

주요 개념

추가 속성

확장 속성

시작하기 전에

비용

필요한 역할

Microsoft Entra ID 애플리케이션 만들기

OIDC

SAML

Microsoft Entra ID로 많은 수의 그룹 구성

OIDC 암시적 흐름을 사용하여 Microsoft Entra ID에 많은 수의 그룹 구성

Microsoft Entra ID 애플리케이션 구성

직원 ID 풀 만들기

gcloud

콘솔

OIDC 암시적 흐름 직원 ID 풀 공급업체 구성

OIDC 코드 흐름을 사용하여 Microsoft Entra ID에 많은 수의 그룹 구성

Microsoft Entra ID 애플리케이션 구성

직원 ID 풀 만들기

gcloud

콘솔

OIDC 코드 흐름 직원 ID 풀 공급업체 구성

SAML 2,0을 사용하여 Microsoft Entra ID에 많은 수의 그룹 구성

Microsoft Entra ID 애플리케이션 구성

직원 ID 풀 만들기

gcloud

콘솔

SAML 2.0 직원 ID 풀 공급업체 구성

그룹에 IAM 역할 부여

로그인 및 액세스 테스트

로그인

콘솔(제휴) 로그인

gcloud CLI 브라우저 기반 로그인

gcloud CLI 헤드리스 로그인

OIDC

SAML

액세스 테스트

콘솔(제휴)

gcloud CLI

사용자 삭제하기

SCIM 구성

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

Microsoft Entra ID에서 SCIM 구성

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

OIDC

SAML

토큰 및 SCIM 속성 매핑

SCIM 테넌트 삭제

다음 단계