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

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

이 가이드에 설명된 메서드는 헤드리스 머신에서 사용할 수 있습니다.

이 문서의 뒷부분에서 자세히 설명하는 다음의 대략적인 프로세스를 사용하여 단기 토큰을 가져올 수 있습니다.

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

시작하기 전에

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

   • Microsoft Entra ID 기반 직원 ID 제휴 구성
   • Okta 기반 직원 ID 제휴 구성

   직원 ID 풀 ID 및 직원 ID 풀 제공업체 ID를 기록해 둡니다.

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

3. Enable the IAM and Security Token Service APIs.

   Enable the APIs

4. Install the Google Cloud CLI, then initialize it by running the following command:

   gcloud init

   Note: If you installed the gcloud CLI previously, make sure you have the latest version by running 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/WORKFORCE_PROVIDER_ID \
    --output-file=LOGIN_CONFIG_FILE

다음을 바꿉니다.

• WORKFORCE_POOL_ID: 직원 ID 풀 ID입니다.
• WORKFORCE_PROVIDER_ID: 직원 ID 풀 제공업체 ID
• LOGIN_CONFIG_FILE: 지정하는 로그인 구성 파일의 경로(예: login.json)

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

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

{
  "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",
}

주의: 먼저 이 파일의 콘텐츠가 올바른지 확인한 다음 파일을 보호하는 것이 좋습니다. 예를 들어 파일을 읽기 전용으로 설정하고 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/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_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/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_FILE"
  }
}

URL 소스 사용자 인증 정보

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

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

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-url=URL_TO_RETURN_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
• 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/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": {
    "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/WORKFORCE_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 풀 ID
• WORKFORCE_PROVIDER_ID: 직원 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/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": {
    "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/WORKFORCE_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 풀 ID
• WORKFORCE_PROVIDER_ID: 직원 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/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": {
    "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/WORKFORCE_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 풀 ID
• WORKFORCE_PROVIDER_ID: 직원 ID 풀 제공업체 ID
• CREDENTIAL_FILE: IdP에서 생성된 사용자 인증 정보 파일의 경로
• WORKFORCE_POOL_USER_PROJECT: 할당량 및 결제에 사용되는 프로젝트 번호 또는 ID. 주 구성원에게는 이 프로젝트에 대한 serviceusage.services.use permission이 있어야 합니다.

URL 소스 사용자 인증 정보

HTTP `GET` 요청에 응답하는 엔드포인트를 사용하여 로컬 서버에서 어설션이 로드됩니다. 응답은 [base64로 인코딩된](https://toolbox.googleapps.com/apps/encode_decode/) SAML 어설션이거나 base64로 인코딩된 SAML 어설션이 포함된 JSON이어야 합니다. URL 소스 사용자 인증 정보를 사용하려면 `--credential-source-url` 플래그를 사용하세요. ```sh gcloud iam workforce-pools create-cred-config \ locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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 풀 ID입니다. * WORKFORCE_PROVIDER_ID: 직원 ID 풀 공급업체 ID입니다. * CREDENTIAL_URL: 로컬 서버 엔드포인트의 URL입니다. * WORKFORCE_POOL_USER_PROJECT: 할당량 및 결제에 사용되는 프로젝트 번호 또는 ID입니다. 주 구성원에게 이 프로젝트에 대한 `serviceusage.services.use 권한` 이 있어야 합니다.

실행 파일 소스 사용자 인증 정보

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

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

{
  "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",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE"
    }
  }
}

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

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/WORKFORCE_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 풀 ID
• WORKFORCE_PROVIDER_ID: 직원 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>WORKFORCE_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

gcloud CLI와 bq 명령줄 도구는 실행 가능한 소스 사용자 인증 정보 유형을 지원하지 않습니다.

헤드리스 흐름의 경우 gcloud CLI는 자동으로 https://www.googleapis.com/auth/cloud-platform 범위를 사용합니다. 그러면 gcloud CLI가 사용자 인증 정보를 보안 토큰 서비스 엔드포인트에 투명하게 게시하여, 여기에서 임시 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 Cloud 클라이언트 라이브러리는 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 CLI에서 직원 ID 제휴는 Google Cloud CLI 버전 392.0.0 이상에서 지원됩니다.

Go

Go용 Cloud 클라이언트 라이브러리는 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)
}

자바

Java용 Cloud 클라이언트 라이브러리는 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용 Cloud 클라이언트 라이브러리는 google-auth-library 패키지 버전 7.10.0 이상을 사용하는 경우 직원 ID 제휴를 지원합니다.

워크로드 아이덴티티 풀과 달리 직원 ID 풀은 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용 Cloud 클라이언트 라이브러리는 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)

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

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

REST API 사용

다음 명령어를 실행하여 Google Cloud Security 토큰 서비스 API를 호출하여 외부 사용자 인증 정보를 Google Cloud 액세스 토큰으로 교환할 수 있습니다.

curl https://sts.googleapis.com/v1/token \
    --data-urlencode "audience=//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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: 주체 토큰을 발급하는 공급업체의 전체 리소스 이름
• WORKFORCE_POOL_ID: 직원 ID 풀 ID입니다.
• WORKFORCE_PROVIDER_ID: 직원 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 CLI가 보안 토큰 서비스 엔드포인트에서 가져오는 임시 Google Cloud 토큰은 지정된 시간 간격이 지나면 만료됩니다. 토큰이 곧 만료되면 gcloud CLI에서 제공된 사용자 인증 정보 파일을 검사하고 IdP에서 받은 사용자 인증 정보의 유효성을 검사합니다. 사용자 인증 정보가 여전히 유효한 경우 gcloud CLI에서 새 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 제품 알아보기
• 콘솔에 대한 사용자 액세스 설정(제휴)