Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

gcloud CLI 인증

이 문서는Google Cloud 리소스에 액세스하기 위한 Google Cloud CLI 인증에만 관한 내용입니다. Cloud 클라이언트 라이브러리 또는 Google API 클라이언트 라이브러리를 사용하여 워크로드를 인증해야 하는 경우 애플리케이션 기본 사용자 인증 정보 작동 방식을 참고하세요.

시작하기 전에

Google Cloud 를 처음 사용하고 로컬 개발 환경에서 gcloud CLI 명령어를 사용하기 시작하려면 다음 명령어를 사용하여 gcloud CLI를 초기화하면 됩니다.

gcloud init

초기화하면 인증 흐름을 안내하고, gcloud CLI 구성을 설정하고, gcloud CLI가 사용자를 대신하여 작업을 수행하도록 승인합니다. 별도의 인증 단계를 수행할 필요가 없습니다.

이 문서의 나머지 부분에서는 다양한 주 구성원 유형으로 gcloud CLI 사용, 다양한 환경에 적합한 인증 방법, 주 구성원 전환, 저장된 사용자 인증 정보 관리와 같은 더 복잡한 시나리오를 다룹니다.

인증 방식

모든 gcloud CLI 명령어는 Google CloudAPI에 인증해야 합니다. 다음과 같은 방법으로 인증할 수 있습니다.

사용자 인증 정보 승인 및 저장: 사람이 로컬 개발 환경에서 사용하기에 적합합니다. gcloud auth login 명령어를 사용하여 주 구성원을 대신하여 작업하도록 gcloud CLI에 권한을 부여할 수 있습니다. 초기 인증 후 이 명령어는 gcloud CLI 구성 디렉터리에 사용자 인증 정보를 저장합니다. gcloud CLI는 저장된 사용자 인증 정보를 사용하여 세션이 만료되거나 승인을 취소할 때까지 후속 명령어에 대해 자동으로 인증합니다.
사용자 인증 정보 파일로 인증: Google Cloud외부에서 실행되는 워크로드에 적합합니다. 환경 변수 또는 gcloud CLI 구성 속성을 사용하여 자동 인증을 위한 사용자 인증 정보 파일을 지정할 수 있습니다. 이 파일은 다음 중 하나일 수 있습니다.
- 워크로드 아이덴티티 제휴 사용자 인증 정보 구성 파일입니다.
- 서비스 계정 키
액세스 토큰 제공: 공유 머신에서 고도로 격리된 자동 워크플로 또는 상태 비저장 세션에 적합합니다. gcloud CLI에 액세스 토큰을 직접 제공하여 사용자 인증 정보 저장소를 우회할 수 있습니다. 원시 액세스 토큰 문자열에 특정 환경 변수를 설정하거나 액세스 토큰이 포함된 파일을 gcloud CLI에 지정하여 이 작업을 수행할 수 있습니다.

인증 후 서비스 계정의 이메일 주소를 제공하여 gcloud CLI가 서비스 계정을 가장하도록 선택적으로 허용할 수 있습니다.

단일 환경에서 여러 인증 방법을 사용할 수 있습니다. 하지만 지정된 gcloud 명령어에는 하나의 주 구성원만 사용됩니다. 사용할 주 구성원을 확인하기 위해 gcloud CLI는 우선순위를 따릅니다.

인증이 필요하지 않은 경우

다음 상황에서는 gcloud CLI를 인증하지 않아도 됩니다.

gcloud CLI를 초기화한 직후 인증 및 승인은 초기화 프로세스에 포함됩니다. 다른 주 구성원을 사용하여 다른 리소스에 액세스해야 하거나 주 구성원을 재인증해야 하는 경우 다시 인증해야 할 수 있습니다.
Compute Engine 메타데이터 서버를 노출하는 리소스에서 gcloud CLI를 사용하는 경우 여기에는 Compute Engine VM 인스턴스, Cloud Run 서비스, Cloud Build 빌드와 같은 리소스가 포함됩니다. gcloud CLI는 VM에 연결된 서비스 계정을 사용하여 인증하고 적용된 액세스 범위의 한도 내에서 해당 서비스 계정과 동일한 리소스에 액세스할 수 있는 권한이 부여됩니다.
Cloud Shell을 사용하는 경우 gcloud CLI는 Google Cloud 콘솔에 로그인한 주 구성원을 사용하여 자동으로 인증합니다. 새 Cloud Shell 세션에서 gcloud CLI 명령어를 처음 실행하면 해당 주 구성원을 사용하여 Cloud Shell을 승인하라는 메시지가 표시됩니다.

작업에 적합한 주 구성원 선택

인간 사용 및 자동 워크로드에 사용할 수 있는 다양한 유형의 주 구성원이 있습니다. 사용해야 하는 주 구성원 유형은 인증 방식에 영향을 미칩니다.

사용자 계정: 사람이 부수적인 관리 작업, Google Cloud 서비스의 비프로그래매틱 구성, 테스트, 실험, 모니터링 가능성과 같은 대화형 작업을 수행하는 데 사용하는 Google 계정입니다.

비밀번호, 일회용 코드와 같은 사용자 인증 정보로 사용자 계정으로 인증합니다.
서비스 계정: 워크로드가 서비스 또는 리소스에 액세스하는 데 사용할 수 있는 Google Cloud 계정입니다. 일반적으로 서비스 계정으로 직접 인증하지는 않습니다. 대신 Compute Engine VM과 같은 리소스에 서비스 계정을 연결하거나 서비스 계정 가장을 사용합니다.
제휴 주 구성원: 외부 ID 제공업체의 사용자 또는 서비스 계정을 참조하는 ID입니다. Google Cloud에서 지원하는 두 가지 유형의 제휴 주 구성원은 이름이 비슷합니다.
- 직원 ID 제휴: 인간 사용자가 외부 ID 공급업체에서 관리하는 ID로 Google Cloud 에 로그인할 수 있습니다. 조직에 이미 싱글 사인온 (SSO)이 설정되어 있는 경우 이 유형의 ID를 사용하여 Google Cloud에 인증할 수 있습니다.
  
  직원 ID 제휴를 사용하려면 ID 공급업체가 OpenID Connect (OIDC) 또는 SAML 2.0을 지원해야 합니다.
- 워크로드 아이덴티티 제휴: Google Cloud 외부에서 실행되는 워크로드가 Google Cloud 리소스에서 작동할 수 있습니다.
  
  X.509 클라이언트 인증서를 사용하여 인증하는 워크로드, Amazon Web Services (AWS) 또는 Azure에서 실행되는 워크로드, 온프레미스 Active Directory, GitHub 및 GitLab과 같은 배포 서비스, OpenID Connect (OIDC) 또는 Security Assertion Markup Language (SAML) V2.0을 지원하는 ID 공급업체와 함께 워크로드 아이덴티티 제휴를 사용할 수 있습니다.

gcloud CLI를 사람이 사용하는 경우

대화형 작업의 경우 일반적으로 다음 중 하나로 인증합니다.

사용자 계정
직원 ID 제휴를 사용하는 제휴 사용자 ID

사용자 계정

gcloud CLI의 사용자 계정으로 인증하는 방법은 기기에 웹브라우저가 설치되어 있는지에 따라 달라집니다.

내 기기에 웹브라우저가 있음

웹브라우저가 있는 기기에서 사용자 계정으로 인증하려면 다음 단계를 완료하세요.

다음 명령어를 실행하여 프로세스를 시작합니다.
```
gcloud auth login
```
브라우저 기반 흐름에 따라 gcloud CLI가 향후 명령어를 위해 사용자를 대신하여 리소스에 액세스하도록 인증하고 승인합니다.

gcloud auth login 명령어는 홈 디렉터리에 액세스 사용자 인증 정보를 저장합니다. 인증된 주 구성원이 활성 gcloud CLI 구성의 활성 주 구성원이 됩니다. 재정의되지 않는 한 gcloud CLI는 저장된 사용자 인증 정보를 사용하여 Google Cloud에 액세스합니다.

내 기기에 웹브라우저가 없음

gcloud CLI를 사용해야 하는 기기에 웹브라우저가 없는 경우 신뢰할 수 있는 다른 기기에서 사용자 계정으로 인증할 수 있습니다. 이 프로세스는 다른 신뢰할 수 있는 기기에 설치된 소프트웨어에 따라 달라집니다.

다른 신뢰할 수 있는 기기를 사용하여 인증

다른 신뢰할 수 있는 기기에서 사용할 수 있는 소프트웨어를 선택합니다.

gcloud CLI 및 웹브라우저

--no-browser 플래그를 사용하여 웹브라우저와 gcloud CLI가 설치된 다른 기기에서 인증 프로세스를 완료합니다.

gcloud CLI를 사용하려는 원래 기기에서 다음 명령어를 실행합니다.
Linux 및 macOS
gcloud auth login \ --no-browser
Windows(PowerShell)
gcloud auth login ` --no-browser
gcloud auth login --remote-bootstrap="으로 시작하는 gcloud 명령어를 복사하여 다른 기기에서 사용합니다.
웹브라우저와 gcloud CLI 버전 372.0.0 이상이 설치된 신뢰할 수 있는 다른 기기로 이동합니다.
터미널에서 이전에 복사한 gcloud auth login --remote-bootstrap="로 시작하는 명령어를 실행하고 브라우저 기반 흐름을 완료합니다.
터미널에서 https://localhost로 시작하는 URL을 복사하여 원래 기기에서 사용합니다.
원래 기기로 돌아갑니다.
터미널의 프롬프트에 이전에 복사한 https://localhost URL을 붙여넣습니다. 키보드에서 Enter 또는 Return 키를 눌러 절차를 완료합니다.

웹브라우저만 해당

다른 기기의 웹브라우저를 사용하여 인증 프로세스를 완료하려면 --no-launch-browser 플래그를 사용하세요.

gcloud CLI를 사용하려는 원래 기기에서 다음 명령어를 실행합니다.
Linux 및 macOS
gcloud auth login \ --no-launch-browser
Windows(PowerShell)
gcloud auth login ` --no-launch-browser
https://accounts.google.com/o/oauth2/auth로 시작하는 URL을 복사하여 다른 기기에서 사용합니다.
웹브라우저가 설치되어 있고 신뢰할 수 있는 다른 기기로 이동합니다.
웹브라우저를 열고 이전에 복사한 URL로 이동하여 브라우저 기반 흐름을 완료합니다.
인증 코드를 복사하여 원래 기기에서 사용합니다.
원래 기기로 돌아갑니다.
터미널의 프롬프트에 이전에 복사한 인증 코드를 붙여넣습니다. 키보드에서 Enter 또는 Return을 눌러 절차를 완료합니다.

제휴 사용자 ID

외부 ID 공급업체 (IdP)에서 관리되는 제휴 사용자 ID로 gcloud CLI를 사용할 수 있습니다. 직원 ID 제휴를 사용하여 이를 수행합니다.

다음 안내에서는 IdP와 함께 작동하도록 직원 ID 제휴 풀 및 공급업체가 이미 설정되어 있다고 가정합니다.

제휴 사용자 ID로 gcloud CLI를 사용하려면 로그인 구성 파일을 만든 다음 브라우저 기반 흐름을 사용하여 로그인합니다.

다음 명령어를 실행하여 로그인 구성 파일을 만듭니다.
Linux 및 macOS
gcloud iam workforce-pools create-login-config \ locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \ --output-file=LOGIN_CONFIG_PATH
Windows(PowerShell)
gcloud iam workforce-pools create-login-config ` locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID ` --output-file=LOGIN_CONFIG_PATH
참고: --activate 플래그를 추가하여 로그인 구성 파일을 gcloud CLI의 기본값으로 활성화할 수 있습니다. 그러면 로그인 구성 파일 경로를 매번 지정하지 않고도 gcloud auth login을 실행하여 gcloud CLI를 승인할 수 있습니다.

다음을 바꿉니다.
- WORKFORCE_POOL_ID: 직원 ID 제휴 풀 ID입니다.
- WORKFORCE_PROVIDER_ID: 직원 ID 제휴 공급업체 ID입니다.
- LOGIN_CONFIG_PATH: 로그인 구성 파일을 쓸 경로입니다. 예를 들면 login-config.json입니다.
로그인 구성 파일에는 브라우저 기반 인증 흐름을 사용 설정하고 잠재고객을 직원 ID 풀 공급업체에 구성된 IdP로 설정하도록 gcloud CLI에서 사용된 엔드포인트가 포함됩니다. 파일에 포함된 기밀 정보가 없습니다.

로그인 구성 파일 콘텐츠는 다음과 유사합니다.
```
{
  "universe_domain": "googleapis.com",
  "universe_cloud_web_domain": "cloud.google",
  "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을 사용하여 액세스를 제한합니다. 파일이 검증되지 않으면 이 파일에 대해 쓰기 액세스 권한이 있는 악의적인 행위자가 엔드포인트를 변경하고 사용자 인증 정보를 가로챌 수 있습니다.
환경 변수, 활성 gcloud CLI 구성의 속성으로 로그인 구성 파일을 가리키거나 gcloud auth login 명령어로 직접 사용합니다.
환경 변수

환경 변수와 함께 로그인 구성 파일을 사용하려면 다음 안내를 완료하세요.
1. CLOUDSDK_AUTH_LOGIN_CONFIG_FILE 환경 변수를 로그인 구성 파일의 경로로 설정합니다.
2. 다음 명령어를 실행합니다.
  
  gcloud auth login
3. gcloud CLI는 환경 변수를 참조하여 로그인 구성 파일을 찾은 다음 인증 프로세스를 시작합니다. 브라우저 기반 흐름에 따라 gcloud CLI를 인증하고 승인하여 향후 명령어에 대해 사용자를 대신하여 리소스에 액세스합니다.
gcloud auth login 명령어에 로그인 구성 파일 사용을 중지하려면 CLOUDSDK_AUTH_LOGIN_CONFIG_FILE 환경 변수를 지우세요.
gcloud CLI 구성

gcloud CLI 구성 속성과 함께 로그인 구성 파일을 사용하려면 다음 안내를 완료하세요.
1. 다음 명령어를 사용하여 활성 gcloud CLI 구성의 auth/login_config_file 속성을 로그인 구성 파일의 경로로 설정합니다.
  
  gcloud config set auth/login_config_file LOGIN_CONFIG_PATH
2. 다음 명령어를 실행합니다.
  
  gcloud auth login
3. gcloud CLI는 구성 속성을 참조하여 로그인 구성 파일을 찾은 다음 인증 프로세스를 시작합니다. 브라우저 기반 흐름에 따라 gcloud CLI를 인증하고 승인하여 향후 명령어에 대해 사용자를 대신하여 리소스에 액세스합니다.
gcloud auth login 명령어의 로그인 구성 파일 사용을 중지하려면 다음 명령어로 속성을 설정 해제하세요.
gcloud config unset auth/login_config_file
gcloud auth login

gcloud auth login 명령어로 로그인 구성 파일을 직접 사용하려면 다음 안내를 완료하세요.
- 로그인 구성 파일을 만들 때 --activate 플래그를 사용한 경우 다음 명령어를 실행합니다.
  
  gcloud auth login
- 로그인 구성 파일을 만들 때 --activate 플래그를 사용하지 않은 경우 다음 명령어를 실행합니다.
  
  Linux 및 macOS
  
  gcloud auth login \ --login-config=LOGIN_CONFIG_PATH
  
  Windows(PowerShell)
  
  gcloud auth login ` --login-config=LOGIN_CONFIG_PATH
  
  LOGIN_CONFIG_PATH를 로그인 구성 파일의 경로로 바꿉니다.
gcloud auth login 명령어는 홈 디렉터리에 액세스 사용자 인증 정보를 저장합니다. 인증된 주 구성원이 활성 gcloud CLI 구성의 활성 주 구성원이 됩니다. 재정의되지 않는 한 gcloud CLI는 저장된 사용자 인증 정보를 사용하여 Google Cloud에 액세스합니다.

주의: 파일 시스템에 액세스할 수 있는 모든 사용자가 gcloud auth login로 만든 저장된 액세스 사용자 인증 정보를 사용할 수 있습니다. 시스템이 손상되는 결과를 줄이려면 사람과 워크로드 사용을 엄격하게 분리하고 영구 스토리지가 있는 원격 시스템의 자동화된 워크로드에 gcloud auth login를 사용하지 마세요. 가능한 경우 환경 변수와 함께 보안 비밀 관리자를 대신 사용하세요.

원격 시스템 강화에 관한 자세한 안내는 Google Cloud CLI에서 보안 침해된 OAuth 토큰 완화를 참고하세요.

워크로드와 함께 gcloud CLI 사용

자동화된 워크로드의 경우 일반적으로 다음 중 하나로 인증합니다.

워크로드 아이덴티티 제휴를 사용하는 제휴 워크로드 ID
가장을 사용하는 서비스 계정

제휴 워크로드 아이덴티티

제휴 워크로드 아이덴티티와 함께 gcloud CLI를 사용할 수 있습니다. 워크로드 아이덴티티 제휴를 사용하면 됩니다.

워크로드는 워크로드 아이덴티티 풀로 정의된 주체 역할을 하여 Google Cloud 리소스에 직접 액세스하거나 워크로드 아이덴티티 풀에 연결된 서비스 계정을 가장할 수 있습니다.

권한이 과도하게 부여된 서비스 계정을 방지하고 제휴 주체의 식별자를 사용하여 리소스 액세스를 로깅하려면 직접 액세스 방법을 사용하는 것이 좋습니다. Google Cloud API가 워크로드 아이덴티티 제휴를 지원하지 않는 경우에만 서비스 계정 가장을 사용하세요.

다음 안내에서는 IdP와 함께 작동하도록 워크로드 아이덴티티 제휴 풀과 공급자가 이미 설정되어 있다고 가정합니다.

지원되는 ID 공급업체의 안내를 따라 워크로드 아이덴티티 제휴를 위한 사용자 인증 정보 구성 파일을 만듭니다.
환경 변수, 활성 gcloud CLI 구성의 속성 또는 gcloud auth login 명령어를 사용하여 사용자 인증 정보 구성 파일의 경로를 정의합니다.
환경 변수
CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE 환경 변수를 사용자 인증 정보 구성 파일의 경로로 설정합니다. gcloud CLI는 명령어를 실행할 때마다 파일을 참조하고 IdP에서 사용자 인증 정보를 가져옵니다. 이 사용자 인증 정보는 Google Cloud에 대한 액세스 토큰으로 교환됩니다.

인증 정보 구성 파일 사용을 중지하려면 CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE 환경 변수를 지우세요.
gcloud CLI 구성
다음 명령어를 사용하여 활성 gcloud CLI 구성의 auth/credential_file_override 속성을 사용자 인증 정보 구성 파일의 경로로 설정합니다.
gcloud config set auth/credential_file_override CONFIGURATION_PATH
CONFIGURATION_PATH를 사용자 인증 정보 구성 파일의 경로로 바꿉니다.

gcloud 명령어에 사용자 인증 정보 구성 파일을 기본적으로 사용하지 않으려면 다음 명령어를 사용하여 속성을 설정 해제하세요.
gcloud config unset auth/credential_file_override
gcloud auth login
--cred-file 플래그를 사용하여 다음 명령어를 실행합니다.
Linux 및 macOS
gcloud auth login \ --cred-file=CONFIGURATION_PATH

Windows(PowerShell)
gcloud auth login ` --cred-file=CONFIGURATION_PATH
CONFIGURATION_PATH를 사용자 인증 정보 구성 파일의 경로로 바꿉니다.

gcloud auth login 명령어는 홈 디렉터리에 액세스 사용자 인증 정보를 저장합니다. 인증된 주 구성원이 활성 gcloud CLI 구성의 활성 주 구성원이 됩니다. 재정의되지 않는 한 gcloud CLI는 저장된 사용자 인증 정보를 사용하여 Google Cloud에 액세스합니다.

주의: 파일 시스템에 액세스할 수 있는 모든 사용자가 gcloud auth login로 만든 저장된 액세스 사용자 인증 정보를 사용할 수 있습니다. 시스템이 손상되는 결과를 줄이려면 사람과 워크로드 사용을 엄격하게 분리하고 영구 스토리지가 있는 원격 시스템의 자동화된 워크로드에 gcloud auth login를 사용하지 마세요. 가능한 경우 환경 변수와 함께 보안 비밀 관리자를 대신 사용하세요.

원격 시스템 강화에 관한 자세한 안내는 Google Cloud CLI에서 보안 침해된 OAuth 토큰 완화를 참고하세요.

서비스 계정

다음과 같은 방법으로 서비스 계정과 함께 gcloud CLI를 사용할 수 있습니다.

Compute Engine VM 인스턴스 또는 Cloud Run 서비스와 같이 Compute Engine 메타데이터 서버를 노출하는 리소스에서 gcloud CLI는 기본적으로 리소스에 연결된 서비스 계정을 사용하여 인증합니다.
다른 주 구성원을 사용하여 서비스 계정을 가장합니다.
서비스 계정 키를 사용합니다.

서비스 계정 가장

일반적으로 주 구성원이 사용할 수 없는 리소스 액세스의 경우 서비스 계정 가장을 사용하는 대신 Privileged Access Manager로 권한 에스컬레이션을 관리하는 것이 좋습니다.

Privileged Access Manager가 사용 사례에 적합하지 않은 경우 다음 단계에 따라 서비스 계정으로 gcloud CLI를 사용하세요.

서비스 계정을 가장하려면 프로젝트에서 Service Account Credentials API가 사용 설정되어 있어야 합니다.

API 사용 설정에 필요한 역할
API를 사용 설정하려면 serviceusage.services.enable 권한이 포함된 서비스 사용량 관리자 IAM 역할(roles/serviceusage.serviceUsageAdmin)이 필요합니다. 역할 부여 방법 알아보기
API 사용 설정하기
서비스 계정을 가장하는 데 사용할 주 구성원을 선택합니다.
주 구성원에게 서비스 계정을 가장하는 데 필요한 권한이 있는지 확인하려면 관리자에게 서비스 계정에 대한 서비스 계정 토큰 생성자 (roles/iam.serviceAccountTokenCreator) IAM 역할을 주 구성원에게 부여해 달라고 요청합니다. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이 사전 정의된 역할에는 서비스 계정을 가장하는 데 필요한 iam.serviceAccounts.getAccessToken 권한이 포함되어 있습니다.
관리자는 커스텀 역할이나 다른 사전 정의된 역할을 사용하여 주 구성원에게 이 권한을 부여할 수도 있습니다.
사용자 계정, 제휴 사용자 ID, 제휴 워크로드 ID, 다른 서비스 계정 등 이전에 선택한 주체로 gcloud CLI를 인증합니다.
가장할 서비스 계정을 선택합니다. 기존 서비스 계정을 찾거나 새 서비스 계정을 만듭니다.
서비스 계정의 이메일 주소를 복사합니다.
모든 명령어에 대해 서비스 계정을 가장할지 아니면 단일 명령어에 대해서만 서비스 계정을 가장할지 선택합니다.
모든 명령어
향후 명령어에 gcloud CLI로 서비스 계정 가장을 사용하려면 환경 변수를 설정하거나 활성 gcloud CLI 구성에서 속성을 설정하면 됩니다.
- 환경 변수: CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT 환경 변수를 서비스 계정 이메일 주소로 설정합니다.
  
  서비스 계정 사용을 중지하려면 CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT 환경 변수를 지우세요.
- gcloud CLI 구성: 다음 명령어를 사용하여 활성 gcloud CLI 구성의 auth/impersonate_service_account 속성을 설정합니다.
  
  gcloud config set auth/impersonate_service_account SERVICE_ACCOUNT_EMAIL
  
  SERVICE_ACCOUNT_EMAIL을 서비스 계정의 이메일 주소로 바꿉니다.
  
  gcloud 명령어에 기본적으로 서비스 계정 가장을 사용하지 않으려면 다음 명령어를 사용하여 속성을 설정 해제합니다.
  
  gcloud config unset auth/impersonate_service_account
단일 명령어
단일 명령어에 gcloud CLI로 서비스 계정 가장을 사용하려면 gcloud CLI 서비스 명령어에 --impersonate-service-account 플래그를 추가하면 됩니다.

예를 들어 서비스 계정 가장을 사용하여 Compute Engine VM 인스턴스를 나열하려면 다음 명령어를 실행합니다.
Linux 및 macOS
gcloud compute instances list \ --impersonate-service-account=SERVICE_ACCOUNT_EMAIL

Windows(PowerShell)
gcloud compute instances list ` --impersonate-service-account=SERVICE_ACCOUNT_EMAIL
SERVICE_ACCOUNT_EMAIL을 서비스 계정의 이메일 주소로 바꿉니다.

서비스 계정 키

Google Cloud외부에서 실행되는 대부분의 워크로드에는 워크로드 아이덴티티 제휴를 사용하는 것이 좋습니다. 워크로드가 워크로드 아이덴티티 제휴를 지원하지 않는 격리된 외부 환경에서 실행되는 경우에만 서비스 계정 키를 사용하세요.

워크로드 아이덴티티 제휴는 다음과 같은 이점을 제공합니다.

리소스에 대한 액세스 권한은 Identity and Access Management (IAM)를 통해 부여되며 워크로드는 개별 주 구성원으로 취급됩니다. 즉, 여러 사용 사례에 대해 서비스 계정에 과도한 권한을 부여할 필요가 없습니다.
어떤 워크로드가 어떤 작업을 수행하는지 감사할 수 있습니다. 작업이 서비스 계정 이메일 주소 뒤에 숨겨져 있지 않습니다.
워크로드 아이덴티티 제휴는 단기 액세스 토큰을 사용하여 유출 위험을 줄입니다. 서비스 계정 키는 수동으로 취소하지 않는 한 만료되지 않습니다.

향후 명령어에 gcloud CLI와 함께 서비스 계정을 사용하려면 다음을 실행하세요.

서비스 계정 키를 만들고 환경의 보안 위치에 파일로 저장합니다.
환경 변수, 활성 gcloud CLI 구성의 속성 또는 gcloud auth login 명령어를 사용하여 서비스 계정 키 파일의 경로를 정의합니다.
- 환경 변수: CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE 환경 변수를 서비스 계정 키 파일의 경로로 설정합니다.
  
  서비스 계정 키 사용을 중지하려면 CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE 환경 변수를 지우세요.
- gcloud CLI 구성: 다음 명령어를 사용하여 활성 gcloud CLI 구성의 auth/credential_file_override 속성을 서비스 계정 키의 경로로 설정합니다.
```
gcloud config set auth/credential_file_override KEY_PATH
```
  KEY_PATH을 서비스 계정 키 파일의 경로로 바꿉니다.
  
  gcloud 명령어에 서비스 계정 키를 기본적으로 사용하지 않으려면 다음 명령어를 사용하여 속성을 설정 해제합니다.
```
gcloud config unset auth/credential_file_override
```
- gcloud auth login: --cred-file 플래그를 사용하여 다음 명령어를 실행합니다.
  Linux 및 macOS
  gcloud auth login \ --cred-file=KEY_PATH
  Windows(PowerShell)
  gcloud auth login ` --cred-file=KEY_PATH
  KEY_PATH을 서비스 계정 키 파일의 경로로 바꿉니다.
  
  gcloud auth login 명령어는 홈 디렉터리에 액세스 사용자 인증 정보를 저장합니다. 인증된 주 구성원이 활성 gcloud CLI 구성의 활성 주 구성원이 됩니다. 재정의되지 않는 한 gcloud CLI는 저장된 사용자 인증 정보를 사용하여 Google Cloud에 액세스합니다.
  
  주의: 파일 시스템에 액세스할 수 있는 모든 사용자가 gcloud auth login로 만든 저장된 액세스 사용자 인증 정보를 사용할 수 있습니다. 시스템이 손상되는 결과를 줄이려면 사람과 워크로드 사용을 엄격하게 분리하고 영구 스토리지가 있는 원격 시스템의 자동화된 워크로드에 gcloud auth login를 사용하지 마세요. 가능한 경우 환경 변수와 함께 보안 비밀 관리자를 대신 사용하세요.
  
  원격 시스템 강화에 관한 자세한 안내는 Google Cloud CLI에서 보안 침해된 OAuth 토큰 완화를 참고하세요.
  
  참고: P12 기존 형식 서비스 계정 키의 경우 gcloud auth activate-service-account 명령어를 사용하세요.

액세스 토큰과 함께 gcloud CLI 사용

다른 기기에서 gcloud CLI를 이미 인증한 경우 다음 명령어를 사용하여 해당 기기의 활성 주 구성원의 액세스 토큰을 가져올 수 있습니다.

gcloud auth print-access-token

그런 다음 다른 기기에서 이 액세스 토큰을 사용하여 Google Cloud리소스에 액세스할 수 있습니다. 액세스 토큰을 사용하면 활성 주 구성원을 설정할 필요가 없으며 활성 gcloud CLI 구성에 설정된 활성 주 구성원이 재정의됩니다.

사용자 계정의 액세스 토큰의 기본 수명은 1시간입니다.

액세스 토큰을 사용하여 향후 명령어 또는 단일 명령어에 gcloud CLI를 사용할 수 있습니다.

모든 명령어

향후 명령어에 gcloud CLI와 함께 액세스 토큰을 사용하려면 환경 변수를 설정하거나 활성 gcloud CLI 구성에서 속성을 설정하면 됩니다.

환경 변수: CLOUDSDK_AUTH_ACCESS_TOKEN 환경 변수를 액세스 토큰 문자열로 설정합니다.

액세스 토큰 사용을 중지하려면 CLOUDSDK_AUTH_ACCESS_TOKEN 환경 변수를 선택 해제합니다.
gcloud CLI 구성: 파일에 액세스 토큰을 저장한 다음 다음 명령어를 사용하여 활성 gcloud CLI 구성의 auth/access_token_file 속성을 파일의 경로로 설정합니다.
```
gcloud config set auth/access_token_file ACCESS_TOKEN_PATH
```
ACCESS_TOKEN_PATH를 액세스 토큰 파일의 경로로 바꿉니다.

gcloud 명령어에 액세스 토큰을 기본적으로 사용하지 않으려면 다음 명령어로 속성을 설정 해제하세요.
```
gcloud config unset auth/access_token_file
```

단일 명령어

단일 명령어에 gcloud CLI와 함께 액세스 토큰을 사용하려면 gcloud CLI 서비스 명령어에 --access-token-file 플래그를 추가하면 됩니다.

액세스 토큰을 파일에 저장합니다.
gcloud 서비스 명령어와 함께 --access-token-file 플래그를 사용합니다.

예를 들어 액세스 토큰을 사용하여 Compute Engine VM 인스턴스를 나열하려면 다음 명령어를 실행합니다.
Linux 및 macOS
gcloud compute instances list \ --access-token-file ACCESS_TOKEN_PATH
Windows(PowerShell)
gcloud compute instances list ` --access-token-file ACCESS_TOKEN_PATH
ACCESS_TOKEN_PATH을 액세스 토큰 파일의 경로로 바꿉니다.

사용자 인증 정보 우선순위

하나의 환경에서 여러 인증 방법을 사용할 수 있으므로 gcloud CLI는 사용할 주 구성원을 결정하기 위해 특정 순서로 방법을 평가합니다. gcloud CLI는 제공된 사용자 인증 정보로 시작한 다음 서비스 계정 가장이 요청되었는지 평가합니다.

제공된 사용자 인증 정보의 평가 순서는 다음과 같습니다.

CLOUDSDK_AUTH_ACCESS_TOKEN 환경 변수는 액세스 토큰 문자열로 설정됩니다.
액세스 토큰 파일입니다. 액세스 토큰 파일 경로를 정의하는 데 사용되는 메서드는 다음 순서로 평가됩니다.
1. --access-token-file 명령줄 플래그로, 모든 gcloud CLI 명령어와 함께 사용됩니다.
2. CLOUDSDK_AUTH_ACCESS_TOKEN_FILE 환경 변수
3. 활성 gcloud CLI 구성의 auth/access_token_file 속성입니다.
인증 정보 파일. 인증 정보 파일 경로를 정의하는 데 사용되는 메서드는 다음 순서로 평가됩니다.
1. CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE 환경 변수
2. 활성 gcloud CLI 구성의 auth/credential_file_override 속성입니다.
gcloud auth login 명령어로 설정하거나 core/account 속성을 설정하여 활성 주 구성원을 설정합니다.

서비스 계정 가장 우선순위

서비스 계정 가장이 요청된 경우 gcloud CLI는 가장을 수행하는 주 구성원의 사용자 인증 정보가 제공된 후에 가장할 서비스 계정을 확인합니다. 가장할 서비스 계정을 정의하는 데 사용되는 메서드는 다음 순서로 평가됩니다.

--impersonate-service-account 명령줄 플래그
CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT 환경 변수
활성 구성의 auth/impersonate_service_account 속성으로 정의된 서비스 계정입니다.

범위에 Google Drive 추가

gcloud CLI 범위는 Google Cloud외에 Google Drive 액세스를 포함하도록 확장할 수 있습니다. 즉, Google Drive에서 Google Cloud 액세스 토큰 을 사용할 수 있습니다.

범위를 확장하여 Google Drive를 포함하려면 gcloud CLI를 승인할 때 --enable-gdrive-access 플래그를 추가합니다.

Linux 및 macOS

gcloud auth login \
    --enable-gdrive-access

Windows(PowerShell)

gcloud auth login `
    --enable-gdrive-access

그런 다음 gcloud CLI를 사용하여 Google Drive API를 호출하여 액세스 토큰을 제공할 수 있습니다. 예를 들어 Google Drive의 모든 파일을 나열하려면 다음 요청을 실행하면 됩니다.

Linux 및 macOS

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://www.googleapis.com/drive/v3/files"

Windows(PowerShell)

Invoke-WebRequest `
  -Method GET `
  -Headers @{ "Authorization" = "Bearer $(gcloud auth print-access-token)" } `
  -ContentType "application/json; charset=utf-8" `
  -UseBasicParsing `
  -Uri "https://www.googleapis.com/drive/v3/files" | Select-Object -Expand Content

그런 다음 이전 명령어의 응답에서 파일 ID를 사용하여 Google Docs 파일에서 텍스트를 추출할 수 있습니다.

Linux 및 macOS

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://www.googleapis.com/drive/v3/files/FILE_ID/export?mimeType=text/plain"

Windows(PowerShell)

Invoke-WebRequest `
  -Method GET `
  -Headers @{ "Authorization" = "Bearer $(gcloud auth print-access-token)" } `
  -ContentType "application/json; charset=utf-8" `
  -UseBasicParsing `
  -Uri "https://www.googleapis.com/drive/v3/files/FILE_ID/export?mimeType=text/plain" | Select-Object -Expand Content

Google Drive 액세스의 일반적인 사용 사례는 Google Sheets에 저장된 데이터와 함께 BigQuery를 사용하는 것입니다.

Google Drive API에 대해 자세히 알아보려면 Google Drive API 개요를 참고하세요.

gcloud CLI를 Docker에 사용자 인증 정보 도우미로 추가

Artifact Registry 컨테이너 레지스트리에서 가져오려면 Docker 구성에 gcloud CLI를 사용자 인증 정보 도우미로 추가하면 됩니다.

이렇게 하려면 gcloud auth configure-docker 명령어를 실행하세요.

gcloud auth configure-docker REGION-docker.pkg.dev

주 구성원 및 사용자 인증 정보 관리

gcloud auth login 명령어를 사용하여 동일한 환경에서 여러 주 구성원을 인증하고 gcloud CLI가 주 구성원을 대신하여 리소스에 액세스하도록 승인할 수 있습니다. 하지만 언제든지 하나의 주 구성원만 활성화할 수 있습니다. 다음 섹션에서는 gcloud CLI 구성에서 주 구성원을 관리하는 방법을 설명합니다. 여기에는 주 구성원 나열, 주 구성원 간 전환, 사용자 인증 정보 취소가 포함됩니다.

주 구성원 나열

액세스 사용자 인증 정보가 로컬 시스템에 저장된 주 구성원(즉, gcloud auth login를 사용하여 인증된 주 구성원)을 나열하려면 gcloud auth list 명령어를 실행합니다.

gcloud auth list

gcloud CLI가 주 구성원을 나열하고 활성화된 주 구성원을 표시합니다.

Credentialed Accounts
ACTIVE  ACCOUNT
        alex@altostrat.com
*       bola@altostrat.com
        principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/cruz@cymbalgroup.com

활성 주 구성원의 재정의는 이 목록에 포함되지 않습니다. 여기에는 다음 환경 변수가 포함됩니다.

CLOUDSDK_AUTH_ACCESS_TOKEN
CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE
CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT

이러한 환경 변수가 설정되어 있는지 확인하려면 운영체제에 따라 다음 명령어를 실행하세요.

Linux 및 macOS

echo "$ENVIRONMENT_VARIABLE"

Windows(PowerShell)

echo $env:ENVIRONMENT_VARIABLE

ENVIRONMENT_VARIABLE을 확인하려는 환경 변수로 바꿉니다.

활성 주 구성원의 재정의에는 다음 구성 속성도 포함됩니다.

auth/access_token_file
auth/credential_file_override
auth/impersonate_service_account

이러한 구성 속성이 설정되어 있는지 확인하려면 다음 명령어를 실행하세요.

gcloud config list

활성 주 구성원 전환

사용자 인증 정보가 저장된 활성 주체 (즉, 이전에 gcloud auth login 흐름을 완료한 주체)로 전환하려면 gcloud config set를 실행합니다.

gcloud config set account PRINCIPAL_IDENTIFIER

PRINCIPAL_IDENTIFIER를 주 구성원의 전체 식별자로 바꿉니다.

다음과 같은 방법으로 주 구성원을 전환할 수도 있습니다.

다른 활성 보안 주체를 지정하는 별도의 구성을 만든 다음 해당 구성을 활성화합니다.
--account 명령줄 플래그를 사용하여 단일 명령어의 주 구성원을 지정합니다.
명령줄 플래그, 환경 변수 또는 구성 속성과 같은 재정의를 사용합니다.

세션 길이 설정

관리자는 재인증할 필요 없이 사용자별로 gcloud CLI에 액세스할 수 있는 시간을 지정할 수 있습니다. 예를 들어 승격된 권한을 가진 사용자가 일반 사용자보다 더 자주 재인증하도록 설정할 수 있습니다.

자세한 내용은 Google Cloud 서비스의 세션 길이 설정을 참고하세요.

주 구성원의 사용자 인증 정보 취소

gcloud auth login로 인증된 주체의 사용자 인증 정보를 취소하여 gcloud CLI가 해당 주체를 대신하여 작동하지 못하도록 할 수 있습니다. 취소하면 Google의 승인 서버에서 사용자 인증 정보가 무효화되고 활성 gcloud CLI 구성에서 주체가 삭제됩니다.

사용자 인증 정보를 취소하려면 gcloud auth revoke를 실행합니다.

gcloud auth revoke PRINCIPAL_IDENTIFIER

PRINCIPAL_IDENTIFIER를 주 구성원의 전체 식별자로 바꿉니다.

Google 계정과 연결된 모든 기기에서 gcloud CLI의 액세스 권한을 취소하려면 Google 계정 설정의 서드 파티 앱 및 서비스로 이동하여 Google Cloud SDK와의 모든 연결을 삭제합니다.

저장된 사용자 인증 정보 관리

gcloud CLI는 사용하는 사용자 인증 정보 파일을 gcloud CLI 구성 디렉터리에 저장합니다. 사용자 인증 정보 파일의 위치를 찾으려면 gcloud info를 실행합니다.

gcloud info

gcloud CLI에서 설치에 대한 정보를 출력합니다. 인증 정보 파일은 출력에 정의된 사용자 구성 디렉터리에 저장됩니다.

User Config Directory: [/home/USERNAME/.config/gcloud]

Linux 및 macOS의 경우 gcloud CLI 구성 디렉터리는 일반적으로 /home/USERNAME/.config/gcloud입니다. Windows의 경우 %APPDATA%\gcloud입니다.

다음 단계

gcloud CLI 맞춤설정에 대한 자세한 내용은 gcloud CLI 속성을 참고하세요.
명명된 gcloud CLI 속성 집합 관리에 대한 자세한 내용은 gcloud CLI 구성을 참고하세요.
Cloud 클라이언트 라이브러리 또는 Google API 클라이언트 라이브러리를 사용하는 코드 기반 워크로드를 인증하려면 애플리케이션 기본 사용자 인증 정보 작동 방식을 참고하세요.

gcloud CLI 인증 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

시작하기 전에

인증 방식

인증이 필요하지 않은 경우

작업에 적합한 주 구성원 선택

gcloud CLI를 사람이 사용하는 경우

사용자 계정

내 기기에 웹브라우저가 있음

내 기기에 웹브라우저가 없음

다른 신뢰할 수 있는 기기를 사용하여 인증

gcloud CLI 및 웹브라우저

Linux 및 macOS

Windows(PowerShell)

웹브라우저만 해당

Linux 및 macOS

Windows(PowerShell)

제휴 사용자 ID

Linux 및 macOS

Windows(PowerShell)

환경 변수

gcloud CLI 구성

gcloud auth login

Linux 및 macOS

Windows(PowerShell)

워크로드와 함께 gcloud CLI 사용

제휴 워크로드 아이덴티티

환경 변수

gcloud CLI 구성

gcloud auth login

Linux 및 macOS

Windows(PowerShell)

서비스 계정

서비스 계정 가장

모든 명령어

단일 명령어

Linux 및 macOS

Windows(PowerShell)

서비스 계정 키

Linux 및 macOS

Windows(PowerShell)

액세스 토큰과 함께 gcloud CLI 사용

모든 명령어

단일 명령어

Linux 및 macOS

Windows(PowerShell)

사용자 인증 정보 우선순위

서비스 계정 가장 우선순위

범위에 Google Drive 추가

Linux 및 macOS

Windows(PowerShell)

Linux 및 macOS

Windows(PowerShell)

Linux 및 macOS

Windows(PowerShell)

gcloud CLI를 Docker에 사용자 인증 정보 도우미로 추가

주 구성원 및 사용자 인증 정보 관리

주 구성원 나열

Linux 및 macOS

Windows(PowerShell)

활성 주 구성원 전환

세션 길이 설정

주 구성원의 사용자 인증 정보 취소

저장된 사용자 인증 정보 관리

다음 단계

gcloud CLI 인증