직원 ID 제휴를 위한 단기 토큰 가져오기

이 가이드에서는 직원 ID 풀 및 직원 ID 풀 공급업체를 사용하여 보안 토큰 서비스에서 단기 토큰을 가져오는 방법을 설명합니다. 토큰을 사용하여 직원 ID 제휴를 지원하고 액세스 권한이 부여된 Google Cloud 리소스에 액세스할 수 있습니다.

참고: 이 가이드에 설명된 절차는 헤드리스 머신에서 사용할 수 있습니다.

다음 절차에 따라 단기 토큰을 가져옵니다.

1. 신뢰할 수 있는 ID 공급업체에서 사용자 인증 정보를 가져옵니다.
2. 보안 토큰 서비스의 토큰에 대해 사용자 인증 정보를 교환합니다.

시작하기 전에

1. 직원 ID 제휴를 구성하거나 IdP 관련 안내는 다음 가이드를 참조하세요.

   • Azure AD 기반 직원 ID 제휴 구성
   • Okta 기반 직원 ID 제휴 구성

2. 직원 풀 ID 또는 공급업체 ID를 알아야 합니다.

3. Identity and Access Management(IAM) 권한 serviceusage.services.use가 있는지 확인합니다. 이 권한이 포함된 최소 권한 역할은 서비스 사용량 소비자(roles/serviceusage.serviceUsageConsumer)입니다.

4. API IAM and Security Token Service 사용 설정

   API 사용 설정

5. Google Cloud CLI를 설치한 후 다음 명령어를 실행하여 초기화합니다.

   gcloud init

   참고: gcloud CLI를 이전에 설치했으면 gcloud components update를 실행하여 최신 버전을 사용할 수 있는지 확인합니다.

외부 사용자 인증 정보를 Google Cloud 액세스 토큰으로 교환

이 섹션에서는 보안 토큰 서비스를 사용하여 Google Cloud에 액세스 권한을 부여하는 액세스 토큰으로 외부 사용자 인증 정보를 교환하는 방법을 보여줍니다. 이 가이드의 뒷부분에 설명된 대로 gcloud CLI, REST API, Cloud 클라이언트 라이브러리를 사용하여 이 작업을 수행합니다.

장기 액세스 권한이 필요하면 해당 머신에서 사용자 인증 정보를 계속 새로고침하도록 장기 실행 프로세스를 구성할 수 있습니다. 또는 사용자 인증 정보를 반환하는 엔드포인트를 사용해서 백그라운드에서 로컬 서버를 실행할 수 있습니다.

gcloud CLI를 사용한 브라우저 기반 로그인

이 섹션에서는 브라우저 기반 로그인 과정을 사용하도록 gcloud CLI를 구성하는 방법을 설명합니다. 이 작업을 수행하려면 로그인 구성 파일을 만든 다음 gcloud auth login 호출에서 해당 파일을 참조하거나 기본적으로 사용되도록 활성화합니다.

로그인 구성 파일 만들기

로그인 구성 파일을 만들려면 다음 명령어를 실행합니다. 선택적으로 --activate 플래그를 사용해서 gcloud CLI에 대한 기본값으로 파일을 활성화할 수 있습니다.

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

다음을 바꿉니다.

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

파일은 gcloud CLI에서 브라우저 기반 인증 흐름을 사용 설정하고 이 가이드의 앞부분에서 만든 공급업체를 잠재고객으로 설정하는 데 사용한 엔드포인트를 포함합니다. 파일에 포함된 기밀 정보가 없습니다.

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

{
  "type": "external_account_authorized_user_login_config",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/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",
}

주의: 먼저 이 파일의 콘텐츠가 올바른지 확인한 다음 파일을 보호하는 것이 좋습니다. 예를 들어 파일을 읽기 전용으로 설정하고 ACL을 사용하여 액세스를 제한합니다. 파일이 검증되지 않으면 이 파일에 대해 쓰기 액세스 권한이 있는 악의적인 행위자가 엔드포인트를 변경하고 사용자 인증 정보를 가로챌 수 있습니다.

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

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

• 구성 파일을 만들 때 --activate 플래그를 사용하거나 gcloud config set auth/LOGIN_CONFIG_FILE로 구성 파일을 활성화한 경우 gcloud CLI에서 자동으로 구성 파일을 사용합니다.

  gcloud auth login
  

• 구성 파일의 위치를 지정하여 로그인하려면 다음 명령어를 실행합니다.

  gcloud auth login --login-config=LOGIN_CONFIG_FILE
  

• 환경 변수를 사용하여 구성 파일의 위치를 지정하려면 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 환경 변수가 설정되어 있으면 지웁니다.

로그인에 구성 파일 사용

이 섹션에서는 브라우저 기반 로그인을 대신하여 인증된 Google Cloud 작업에 대한 액세스를 제공하기 위해 사용자 인증 정보 구성 파일을 사용하는 다양한 방법을 보여 줍니다. 구성 파일을 설정해도 gcloud CLI에 로그인할 필요가 없습니다.

구성 파일 설정 방법은 IdP에서 OIDC를 사용하는지 또는 SAML을 사용하는지에 따라 다릅니다.

OIDC

다음 소스에서 구성 파일을 설정하는 데 사용하는 사용자 인증 정보를 가져올 수 있습니다.

• 파일 소스 사용자 인증 정보
• URL 소스 사용자 인증 정보
• 비대화형 실행 소스 사용자 인증 정보
• 대화형 실행 소스 사용자 인증 정보

파일 소스 사용자 인증 정보

토큰은 파일에서 로드됩니다. 다른 프로세스가 이전 토큰이 만료되기 전에 새 OIDC 토큰을 사용하여 이 파일을 새로 고쳐야 합니다. 예를 들어 토큰 수명이 1시간이면 파일을 1시간 전에 새로 고쳐야 합니다.

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

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/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
• PROVIDER_ID: 공급업체 ID
• PATH_TO_OIDC_TOKEN: OIDC IdP 사용자 인증 정보 파일의 경로
• WORKFORCE_POOL_USER_PROJECT: 작업자 풀 사용자 프로젝트와 연결된 프로젝트 번호 또는 ID

주 구성원에게 이 프로젝트에 대한 serviceusage.services.use 권한이 있어야 합니다.

명령어를 실행하면 다음과 비슷한 OIDC IdP 구성 파일이 생성됩니다.

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/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_FILE"
  }
}

URL 소스 사용자 인증 정보

토큰은 HTTP GET 요청에 응답하는 엔드포인트를 통해 로컬 서버에서 로드됩니다. 응답은 일반 텍스트 또는 JSON 형식의 OIDC ID 토큰이어야 합니다.

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

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

다음을 바꿉니다.

• WORKFORCE_POOL_ID: 직원 풀 ID
• PROVIDER_ID: 공급업체 ID
• URL_TO_RETURN_OIDC_ID_TOKEN: OIDC ID 토큰과 같은 OIDC 사용자 인증 정보를 검색하기 위해 호출할 URL(예: http://localhost:5000/token)
• WORKFORCE_POOL_USER_PROJECT: 할당량 및 결제에 사용되는 프로젝트 번호. 주 구성원에게는 이 프로젝트에 대한 serviceusage.services.use permission이 있어야 합니다.

명령어를 실행하면 다음과 비슷한 OIDC IdP 구성 파일이 생성됩니다.

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/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": {
    "url": "URL_TO_RETURN_OIDC_ID_TOKEN"
  }
}

비대화형 실행 소스 사용자 인증 정보

토큰은 로컬 실행 파일에서 로드됩니다. 실행 파일은 JSON 형식의 만료되지 않은 유효 OIDC ID 토큰을 stdout에 제공해야 합니다.

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620499962
}

성공적인 응답을 위해 이러한 필드는 필수입니다(expiration_time 제외). expiration_time 필드는 출력 파일이 사용자 인증 정보 구성에 지정된 경우에만 필요합니다.

실행 파일은 stdout에 다음 JSON 형식의 오류를 표시해야 합니다.

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

이 필드는 모두 오류 응답에 필요합니다. 코드 및 메시지 필드는 적절한 오류를 발생시킬 때 클라이언트 라이브러리에서 사용됩니다.

이 명령어는 다음 필드를 반환할 수 있습니다.

• version: JSON 출력의 버전. 버전 1만 지원됩니다.

• success: 응답 상태. 상태가 true이면 실행 파일은 종료 코드 0으로 종료되어야 하며 응답에는 다음 필드가 포함되어야 합니다.

  • token_type: id_token
  • 출력 파일이 사용자 인증 정보 구성에 지정된 경우 expiration_time 필드

  상태가 false이면 실행 파일은 0이 아닌 값으로 종료되어야 하며 응답에는 다음 필드가 포함되어야 합니다.

  • code
  • message

• token_type: 서드 파티 제목 토큰 유형(urn:ietf:params:oauth:token-type:id_token이어야 함)

• id_token: 서드 파티 OIDC 토큰

• expiration_time: 서드 파티 OIDC 토큰 만료 시간(초)(유닉스 시간)

• code: 오류 코드 문자열

• message: 오류 메시지

실행 파일이 실행될 때 클라이언트 라이브러리는 다음 환경 변수를 채웁니다.

• GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: 사용자 인증 정보 구성의 잠재고객 필드. 항상 표시됩니다.
• GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: 예상되는 제목 토큰 유형입니다. 항상 표시됩니다.
• GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: 사용자 인증 정보 구성의 출력 파일 위치. 사용자 인증 정보 구성에 지정된 경우에만 존재합니다.

이러한 환경 변수를 사용하여 실행 파일에서 이러한 값을 하드코딩하지 않도록 할 수 있습니다.

클라이언트 라이브러리에서 이 사용자 인증 정보 소스를 사용 설정하려면 GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES 환경 변수를 1로 설정해야 합니다.

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

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-timeout-millis=EXECUTABLE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

다음을 바꿉니다.

• WORKFORCE_POOL_ID: 직원 풀 ID
• PROVIDER_ID: 공급업체 ID
• EXECUTABLE_COMMAND: OIDC ID 토큰과 같은 제목 토큰을 검색하기 위해 실행할 인수를 포함한 전체 명령어(--executable-command="/path/to/command --foo=bar" 형식)
• EXECUTABLE_TIMEOUT: (선택사항) 실행 파일이 실행될 때까지 대기하는 기간(기본값은 30초)
• EXECUTABLE_OUTPUT_FILE: (선택 사항) 실행 파일이 생성한 타사 사용자 인증 정보에 대한 파일 경로. 사용자 인증 정보를 캐싱하는 데 유용합니다. 인증 라이브러리는 실행 파일을 실행하기 전에 먼저 이 경로를 확인합니다.
• WORKFORCE_POOL_USER_PROJECT: 할당량 및 결제에 사용되는 프로젝트 번호 또는 ID. 주 구성원은 이 프로젝트에 대해 설정된 serviceusage.services.use 권한 세트가 있어야 합니다.

명령어를 실행하면 다음과 비슷한 OIDC IdP 구성 파일이 생성됩니다.

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/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": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE"
    }
  }
}

대화형 실행 소스 사용자 인증 정보

stdin 및 stdout를 통해 사용자와 상호작용하는 실행 파일을 제공할 수 있습니다. 사용자가 성공적으로 로그인하면 실행 파일이 지정된 파일에 [유효하고 만료되지 않은 사용자 인증 정보]를 기록합니다.

이 모드를 사용하려면 다음 플래그가 필요합니다.

• --executable-output-file: 실행 파일에서 사용자 인증 정보를 작성하는 파일
• --exeutable-interactive-timeout-millis: 대화형 모드를 나타내고 제한 시간을 설정하는 0이 아닌 값(예: 제한 시간이 60초인 경우에는 6000)

성공적인 응답을 위해 다음 필드는 필수입니다(expiration_time 제외).

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620499962
}

실행 파일은 --executable-output-file에 지정된 파일에 다음 JSON 형식으로 오류를 작성해야 합니다. 오류 응답을 반환할 때는 다음 필드가 모두 필요합니다.

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

code 및 message 필드는 적절한 오류를 나타내야 합니다. 이러한 필드는 오류를 발생시킬 때 클라이언트 라이브러리에서 사용됩니다.

명령어가 성공적으로 실행되면 대화형 또는 비대화형 실행 소스 사용자 인증 정보 결과 모두에 동일한 필드가 반환됩니다.

또한 환경 변수는 일반 실행 소스 사용자 인증 정보와 동일합니다.

대화형 실행 소스 사용자 인증 정보를 생성하려면 --executable-interactive-timeout-millis 매개변수와 --executable-output-file 매개변수를 추가합니다.

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-interactive-timeout-millis=EXECUTABLE_INTERACTIVE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

다음을 바꿉니다.

• WORKFORCE_POOL_ID: 직원 풀 ID
• PROVIDER_ID: 공급업체 ID
• EXECUTABLE_COMMAND: 주체 토큰을 검색하기 위해 실행할 인수를 포함한 전체 명령어(--executable-command="/path/to/command --arg1=val1 --arg2=val2" 형식)
• EXECUTABLE_INTERACTIVE_TIMEOUT: 실행 파일이 실행될 때까지 대기하는 기간(밀리초)
• EXECUTABLE_OUTPUT_FILE: 실행 파일이 생성한 타사 사용자 인증 정보에 대한 파일 경로. 이 경로는 사용자 인증 정보를 캐싱하는 데 유용합니다. 인증 라이브러리는 실행 파일을 실행하기 전에 먼저 이 경로를 확인합니다.
• WORKFORCE_POOL_USER_PROJECT: 할당량 및 결제에 사용되는 프로젝트 번호 또는 ID. 주 구성원은 이 프로젝트에 대해 설정된 serviceusage.services.use 권한이 있어야 합니다.

명령어를 실행하면 다음과 비슷한 OIDC IdP 구성 파일이 생성됩니다.

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/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": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "interactive_timeout_millis": "EXECUTABLE_INTERACTIVE_TIMEOUT",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE",
    }
  }
}

참고: timeout_millis 필드는 경우에 따라 대화형 실행 파일을 비대화형 모드로 실행할 수도 있으므로 반환됩니다. 대화형 모드에서 이 명령어는 기본 제한 시간을 반환합니다.

SAML

다음 소스에서 구성 파일을 설정하는 데 사용하는 사용자 인증 정보를 가져올 수 있습니다.

• 파일 소스 사용자 인증 정보
• URL 소스 사용자 인증 정보
• 실행 소스 사용자 인증 정보
• gcloud 대화형 모드에 대한 실행 소스 사용자 인증 정보

파일 소스 사용자 인증 정보

어설션이 파일에서 로드됩니다. 이전 어설션이 만료되기 전에 다른 프로세스에서 새 base64로 인코딩된 SAML 어설션으로 이 파일을 새로 고쳐야 합니다. 예를 들어 어설션 수명이 1시간이면 파일을 1시간 전에 새로 고쳐야 합니다.

참고: 구성 파일을 생성할 때 --subject-token-type=urn:ietf:params:oauth:token-type:saml2 플래그를 전달해야 합니다.

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

다음을 바꿉니다.

• WORKFORCE_POOL_ID: 직원 풀 ID
• PROVIDER_ID: 공급업체 ID
• CREDENTIAL_FILE: IdP에서 생성된 사용자 인증 정보 파일의 경로
• WORKFORCE_POOL_USER_PROJECT: 할당량 및 결제에 사용되는 프로젝트 번호 또는 ID. 주 구성원에게는 이 프로젝트에 대한 serviceusage.services.use permission이 있어야 합니다.

URL 소스 사용자 인증 정보

어설션은 HTTP GET 요청에 응답하는 엔드포인트를 통해 로컬 서버에서 로드됩니다. 응답은 base64로 인코딩된 SAML 어설션이거나 base64로 인코딩된 SAML 어설션이 포함된 JSON이어야 합니다.

--credential-source-url 플래그를 사용하여 URL 소스 사용자 인증 정보 사용

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

다음을 바꿉니다.

• WORKFORCE_POOL_ID: 직원 풀 ID
• PROVIDER_ID: 공급업체 ID
• CREDENTIAL_URL: 로컬 서버 엔드포인트의 URL
• WORKFORCE_POOL_USER_PROJECT: 할당량 및 결제에 사용되는 프로젝트 번호 또는 ID. 주 구성원에게는 이 프로젝트에 대한 serviceusage.services.use permission이 있어야 합니다.

실행 소스 사용자 인증 정보

어설션은 로컬 실행 파일에서 로드됩니다. 실행 파일은 JSON 형식의 만료되지 않은 유효 SAML 어설션을 stdout에 제공해야 합니다.

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:saml2",
  "saml_response": "...",
  "expiration_time": 1620499962
}

성공적인 응답을 위해 이러한 필드는 필수입니다(expiration_time 제외). expiration_time 필드는 출력 파일이 사용자 인증 정보 구성에 지정된 경우에만 필요합니다.

오류가 발생하면 실행 파일에 의해 다음 JSON 형식으로 stdout에 표시되어야 합니다.

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

이 필드는 모두 오류 응답에 필요합니다. 코드 및 메시지 필드는 적절한 오류를 발생시킬 때 클라이언트 라이브러리에서 사용됩니다.

이 명령어는 다음 필드를 반환할 수 있습니다.

• version: JSON 출력의 버전. 버전 1만 지원됩니다.

• success: 응답 상태. 상태가 true이면 실행 파일은 종료 코드 0으로 종료되어야 하며 응답에는 다음 필드가 포함되어야 합니다.

  • token_type: saml_response
  • 출력 파일이 사용자 인증 정보 구성에 지정된 경우 expiration_time 필드

  상태가 false이면 실행 파일은 0이 아닌 값으로 종료되어야 하며 응답에는 다음 필드가 포함되어야 합니다. + code + message

• token_type: 서드 파티 제목 토큰 유형(urn:ietf:params:oauth:token-type:saml2이어야 함)

• saml_response: 서드 파티 SAML 응답

• expiration_time: 서드 파티 SAML 응답 만료 시간(초)(유닉스 시간)

• code: 오류 코드 문자열

• message: 오류 메시지

실행 파일이 실행될 때 클라이언트 라이브러리는 다음 환경 변수를 채웁니다.

• GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: 사용자 인증 정보 구성의 잠재고객 필드. 항상 표시됩니다.
• GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: 예상되는 제목 토큰 유형입니다. 항상 표시됩니다.
• GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: 사용자 인증 정보 구성의 출력 파일 위치. 사용자 인증 정보 구성에 지정된 경우에만 존재합니다.

참고: 실행 파일은 이러한 값을 하드코딩하지 않도록 이러한 환경 변수를 사용할 수 있습니다.

클라이언트 라이브러리에서 이 사용자 인증 정보 소스를 사용 설정하려면 GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES 환경 변수를 1로 설정합니다.

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

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-timeout-millis=EXECUTABLE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

다음을 바꿉니다.

• WORKFORCE_POOL_ID: 직원 풀 ID
• PROVIDER_ID: 공급업체 ID
• EXECUTABLE_COMMAND: 주체 토큰을 검색하기 위해 실행할 인수를 포함한 전체 명령어(--executable-command="/path/to/command --foo=bar" 형식
• EXECUTABLE_TIMEOUT: (선택사항) 실행 파일이 실행될 때까지 대기하는 기간(기본값은 30초)
• EXECUTABLE_OUTPUT_FILE: (선택 사항) 실행 파일이 생성한 3PI 사용자 인증 정보의 파일 경로. 사용자 인증 정보를 캐싱하는 데 유용합니다. 인증 라이브러리는 실행 파일을 실행하기 전에 파일이 있는지 확인합니다.
• WORKFORCE_POOL_USER_PROJECT: 할당량 및 결제에 사용되는 프로젝트 번호. 주 구성원은 이 프로젝트에 대해 설정된 serviceusage.services.use 권한이 있어야 합니다.

명령어를 실행하면 다음과 비슷한 SAML IdP 구성 파일이 생성됩니다.

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE"
    }
  }
}

gcloud 대화형 모드에 대한 실행 소스 사용자 인증 정보

실행 파일은 명령줄을 통해 사용자와 상호작용합니다.

이전 명령어에서 다음을 바꿉니다.

• EXECUTABLE_OUTPUT_FILE: (필수) 실행 파일이 생성한 사용자 인증 정보를 제공하는 파일의 경로
• EXECUTABLE_TIMEOUT: (필수) 0이 아닌 제한 시간 값은 명령어에 대화형 모드를 사용하도록 신호를 보냅니다.

    {
      "version": 1,
      "success": true,
      "token_type": "urn:ietf:params:oauth:token-type:saml2",
      "saml_response": "...",
      "expiration_time": 1620499962
    }

성공적인 응답을 위해 이러한 필드는 필수입니다(expiration_time 제외). expiration_time이 누락되면 실행 파일을 실행할 것이라는 신호로 간주됩니다.

실행 파일은 executable-output-file에 다음 JSON 형식의 오류를 표시해야 합니다.

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

이 필드는 모두 오류 응답에 필요합니다. 코드 및 메시지 필드는 적절한 오류를 발생시킬 때 클라이언트 라이브러리에서 사용됩니다.

성공 실행을 위한 명령어 반환 필드는 위의 일반 실행 소스 사용자 인증 정보 결과와 동일합니다.

또한 환경 변수는 일반 실행 소스 사용자 인증 정보와 동일합니다.

대화형 실행 소스 사용자 인증 정보를 생성하려면 --executable-interactive-timeout-millis 매개변수를 추가합니다.

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-interactive-timeout-millis=EXECUTABLE_INTERACTIVE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

다음을 바꿉니다.

• WORKFORCE_POOL_ID: 직원 풀 ID
• PROVIDER_ID: 공급업체 ID
• EXECUTABLE_COMMAND: 주체 토큰을 검색하기 위해 실행할 인수를 포함한 전체 명령어(--executable-command="/path/to/command --foo=bar") 형식)
• EXECUTABLE_INTERACTIVE_TIMEOUT: 실행 파일이 실행될 때까지 대기하는 기간(밀리초)
• EXECUTABLE_OUTPUT_FILE: 실행 파일이 생성한 타사 사용자 인증 정보에 대한 파일 경로. 사용자 인증 정보를 캐싱하는 데 유용합니다. 인증 라이브러리는 실행 파일을 실행하기 전에 먼저 이 경로를 확인합니다.
• WORKFORCE_POOL_USER_PROJECT: 할당량 및 결제에 사용되는 프로젝트 번호 또는 ID. 주 구성원은 이 프로젝트에 대해 serviceusage.services.use 권한을 설정합니다.

명령어를 실행하면 다음과 비슷한 SAML IdP 구성 파일이 생성됩니다.

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/<var>WORKFORCE_POOL_ID<var>/providers/<var>PROVIDER_ID</var>",
  "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "<var>WORKFORCE_POOL_USER_PROJECT</var>",
  "credential_source": {
    "executable": {
      "command": "<var>EXECUTABLE_COMMAND</var>",
      "interactive_timeout_millis": "<var>EXECUTABLE_INTERACTIVE_TIMEOUT</var>",
      "timeout_millis": "<var>EXECUTABLE_TIMEOUT</var>",
      "output_file": "<var>EXECUTABLE_OUTPUT_FILE</var>",
    }
  }
}

참고: 대화형 실행 소스 사용자 인증 정보는 경우에 따라 비대화형 모드로 실행할 수도 있으므로 구성에 timeout_millis가 포함됩니다. gcloud CLI 구성 생성기가 제한 시간 설정 기본값인 30초로 해당 필드를 자동 완성합니다.

로그인하려면 다음 명령어를 실행합니다.

gcloud auth login --cred-file=/path/to/config.json

CLI(gcloud, bq, gsutil)는 현재 실행 가능한 소스 사용자 인증 정보 유형을 지원하지 않습니다.

헤드리스 흐름의 경우 gcloud는 자동으로 https://www.googleapis.com/auth/cloud-platform 범위를 사용합니다. 그러면 gcloud가 사용자 인증 정보를 보안 토큰 서비스 엔드포인트에 투명하게 게시하여, 여기에서 임시 Google Cloud 액세스 토큰으로 교환됩니다.

이제 gcloud CLI를 사용하여 gcloud 명령어를 실행할 수 있습니다.

Google Cloud 클라이언트 라이브러리 사용

지원되는 클라이언트 라이브러리를 사용하는 경우 자동으로 Google 사용자 인증 정보가 생성되도록 클라이언트 라이브러리를 구성할 수 있습니다. 가능하면 토큰 교환 프로세스를 직접 구현할 필요가 없도록 사용자 인증 정보를 자동으로 생성하는 것이 좋습니다.

직원 풀을 위한 Google Cloud 클라이언트 라이브러리는 Node.js, Java, Python, Go, C++(gRPC) 언어로 지원됩니다.

이러한 서비스 또는 언어로 클라이언트 라이브러리를 사용하려면 다음 안내를 따르세요.

bq

직원 ID 제휴를 사용하여 인증하려면 gcloud auth login 명령어를 사용합니다.

gcloud auth login --cred-file=FILEPATH.json

여기서 FILEPATH는 사용자 인증 정보 구성 파일의 파일 경로입니다.

bq의 직원 ID 제휴는 Google Cloud CLI 버전 390.0.0 이상에서 지원됩니다.

C++

대부분의 C++용 Google Cloud 클라이언트 라이브러리는 grpc::GoogleDefaultCredentials()를 호출하여 생성된 ChannelCredentials 객체를 사용해 직원 ID 제휴를 지원합니다. 이 사용자 인증 정보를 초기화하려면 클라이언트 라이브러리를 gRPC 버전 1.42.0 이상으로 빌드해야 합니다.

C++용 Cloud Storage 클라이언트 라이브러리는 gRPC가 아닌 REST API를 사용하므로 직원 ID 제휴를 지원하지 않습니다.

auto creds = grpc::GoogleDefaultCredentials();

// Create a channel, stub and make RPC calls (same as in the previous example)
auto channel = grpc::CreateChannel("greeter.googleapis.com", creds);
std::unique_ptr<Greeter::Stub> stub(Greeter::NewStub(channel));
grpc::Status s = stub->sayHello(&context, *request, response);

gcloud

직원 ID 제휴를 사용하여 인증하려면 gcloud auth login 명령어를 사용합니다.

gcloud auth login --cred-file=FILEPATH.json

여기서 FILEPATH는 사용자 인증 정보 구성 파일의 파일 경로입니다.

gcloud에서 직원 ID 제휴는 Google Cloud CLI 버전 392.0.0 이상에서 지원됩니다.

Go

Go용 클라이언트 라이브러리는 golang.org/x/oauth2 모듈의 버전 v0.0.0-20211005180243-6b3c2da341f1 이상을 사용하는 경우 직원 ID 제휴를 지원합니다.

import (
  "context"
  "fmt"
  "log"

  "cloud.google.com/go/storage"
  "google.golang.org/api/iterator"
  "google.golang.org/api/option"
  "io/ioutil"
)
ctx := context.Background()
client, err := storage.NewClient(ctx)
# Explicit initialization can also be used.
# var jsonPath = "/path/to/3p-credentials.json"
# client, err := storage.NewClient(ctx, option.WithCredentialsFile(jsonPath))
if err != nil {
  log.Fatal(err)
}
fmt.Println("Buckets:")
it := client.Buckets(ctx, projectID)
for {
  battrs, err := it.Next()
  if err == iterator.Done {
    break
  }
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(battrs.Name)
}

gsutil

직원 ID 제휴를 사용하여 인증하려면 다음 방법 중 하나를 사용합니다.

gcloud와 함께 gsutil을 사용하는 경우 평소처럼 로그인합니다.

gcloud auth login --cred-file=FILEPATH.json

gsutil을 독립형 명령줄 애플리케이션으로 사용하는 경우 다음 섹션을 포함하도록 .boto 파일을 수정합니다.

[Credentials]
gs_external_account_file = FILEPATH

두 케이스 모두 FILEPATH는 사용자 인증 정보 구성 파일의 파일 경로입니다.

gsutil에서 직원 ID 제휴는 Google Cloud CLI 버전 379.0.0 이상에서 지원됩니다.

Java

Java용 클라이언트 라이브러리는 com.google.auth:google-auth-library-oauth2-http 아티팩트 버전 1.2.0 이상을 사용하는 경우 직원 ID 제휴를 지원합니다.

import com.google.auth.oauth2.GoogleCredentials;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
GoogleCredentials sourceCredentials = credentials
    .createScoped(Arrays.asList("https://www.googleapis.com/auth/devstorage.read_only"));

Storage storageService = StorageOptions.newBuilder().setProjectId("project-id")
    .setCredentials(sourceCredentials).build().getService();

Node.js

Node.js용 클라이언트 라이브러리는 직원 ID 제휴를 지원합니다. google-auth-library 패키지 버전 7.10.0 이상을 사용해야 합니다. 워크로드 아이덴티티 풀과 달리 직원 풀은 Google Cloud 프로젝트가 아닌 조직과 연결됩니다. GoogleAuth 객체를 만들 때 프로젝트 ID를 지정해야 합니다. 자세한 내용은 google-auth-library 패키지의 리드미를 참조하세요.

const auth = new GoogleAuth({
  scopes: 'https://www.googleapis.com/auth/cloud-platform',
  // Specify a project ID.
  projectId: 'CLOUD_RESOURCE_PROJECT_ID',
});

# API request using Auth library.
const client = await auth.getClient();
const url =
    `https://storage.googleapis.com/storage/v1/b?projects=${projectId}`;
const res = await client.request({url});
console.log(res.data);

Python

Python용 클라이언트 라이브러리는 google-auth 패키지 버전 2.3.0 이상을 사용하는 경우 직원 ID 제휴를 지원합니다.

from google.cloud import storage
import google.auth

credentials, project = google.auth.default(
    scopes=['https://www.googleapis.com/auth/devstorage.read_only'])

client = storage.Client(
    project="project-id", credentials=credentials)

위의 예시에서 라이브러리가 이 값을 자동으로 검색할 수 없으면 project 값이 None이 될 수 있습니다. 서비스 인스턴스를 사용할 때(스토리지 클라이언트 예시 참조) 이를 명시적으로 전달하거나 환경 변수 GOOGLE_CLOUD_PROJECT를 통해 설정할 수 있습니다.

자세한 내용은 google-auth 패키지 사용자 가이드를 참조하세요.

REST API 사용

Google Cloud Security Token Service API를 호출하여 외부 사용자 인증 정보를 Google Cloud 액세스 토큰으로 교환할 수 있습니다.

curl https://sts.googleapis.com/v1/token \
    --data-urlencode "audience=//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
    --data-urlencode "scope=https://www.googleapis.com/auth/cloud-platform" \
    --data-urlencode "subject_token_type=SUBJECT_TOKEN_TYPE" \
    --data-urlencode "subject_token=EXTERNAL_SUBJECT_TOKEN"  \
    --data-urlencode "options={\"userProject\":\"BILLING_PROJECT_NUMBER\"}"

다음을 바꿉니다.

• AUDIENCE: 주체 토큰을 발급하는 공급업체의 전체 리소스 이름
• PROVIDER_ID: 공급업체 ID

• SUBJECT_TOKEN_TYPE을 다음 중 하나로 설정합니다.

  • OIDC ID 토큰: urn:ietf:params:oauth:token-type:id_token
  • SAML 어설션: urn:ietf:params:oauth:token-type:saml2

• EXTERNAL_SUBJECT_TOKEN: 액세스 토큰이 요청된 주 구성원의 ID를 나타내는 IdP 발급 토큰 참고: OIDC를 사용하는 경우 토큰이 JWT 형식입니다.

• BILLING_PROJECT_NUMBER: 할당량 및 결제에 사용되는 프로젝트 번호 또는 ID. 주 구성원에게 이 프로젝트에 대한 serviceusage.services.use 권한이 있어야 합니다.

응답은 다음 예시와 유사합니다.

{
  "access_token": "ya29.dr.AaT61Tc6Ntv1ktbGkaQ9U_MQfiQw...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600
}

gcloud CLI를 사용한 세션 관리

gcloud가 보안 토큰 서비스 엔드포인트에서 가져오는 임시 Google Cloud 토큰은 지정된 시간 간격이 지나면 만료됩니다. 토큰이 곧 만료되는 경우 gcloud에서 제공된 사용자 인증 정보 파일을 검사하고 IdP에서 받은 사용자 인증 정보의 유효성을 검사합니다. 사용자 인증 정보가 여전히 유효한 경우에는 gcloud에서 새 Google Cloud 액세스 토큰을 투명하게 가져오고 현재 세션이 중단 없이 실행됩니다.

사용자 인증 정보가 만료된 경우 새 Google Cloud 토큰이 발급되지 않고 해당 사용자 인증 정보로 수행하는 모든 호출이 실패합니다. 이 시점에서 다시 인증해야 합니다.

다음 명령어를 실행하여 세션을 종료할 수 있습니다.

gcloud auth revoke

gcloud는 여러 사용자 세션을 지원합니다. 현재 활성 세션을 포함하여 세션 목록을 가져오려면 다음 명령어를 실행합니다.

gcloud auth list

이 명령어 출력은 다음과 비슷합니다.

Credentialed Accounts
ACTIVE    ACCOUNT
*         [e-mail]
          principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/[e-mail]

다른 세션으로 전환하여 이를 활성 상태로 설정하려면 다음 명령어를 실행합니다.

gcloud config set account principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_ID

다음 단계

• 직원 ID 제휴 사용자 및 데이터 삭제
• 직원 ID 제휴를 지원하는 Google Cloud 제품 알아보기
• 콘솔에 대한 사용자 액세스 설정(제휴)