이 페이지는 Cloud Translation API를 통해 번역되었습니다.

gcloud CLI 승인

Google Cloud에 액세스하려면 일반적으로 Google Cloud CLI를 승인해야 합니다. 이 페이지에서는 사용할 수 있는 승인 옵션과 승인에 사용하는 계정을 관리하는 방법을 설명합니다. Compute Engine 인스턴스나 Cloud Shell을 사용하는 경우에는 gcloud CLI를 승인하지 않아도 됩니다.

계정 유형

사용자 계정 또는 서비스 계정으로 gcloud CLI를 승인하여 Google Cloud에 액세스할 수 있습니다.

사용자 계정은 최종 사용자를 해당 애플리케이션에 인증할 수 있는 Google Cloud 계정입니다. 가장 일반적인 사용 사례(특히 gcloud CLI를 대화형으로 사용하는 경우)에서는 사용자 계정을 사용하는 것이 좋습니다.

서비스 계정은 특정 사용자가 아닌 Google Cloud 프로젝트와 연결된 Google Cloud 계정입니다. Cloud Run 함수, App Engine, Compute Engine 또는 Google Kubernetes Engine을 사용하는 경우 기본 제공되는 서비스 계정을 사용할 수 있습니다. 여러 컴퓨터에서 gcloud CLI 스크립트를 실행하려면 서비스 계정을 사용하는 것이 좋습니다.

승인 유형 선택

Google Cloud 리소스를 관리하려면 Google Cloud CLI를 승인해야 합니다. Google Cloud CLI와 Google Cloud 모두 인증 및 승인에 OAuth2를 사용합니다.

다음 승인 유형 중 1가지를 선택합니다.

유형	설명
사용자 계정	명령줄에서 gcloud CLI를 사용하거나 단일 머신에서 사용할 수 있도록 gcloud CLI로 스크립트를 작성하는 경우에 권장됩니다.
서비스 계정	프로덕션 환경에서 머신 배포 프로세스의 일부로 또는 모든 사용자가 `root`에 액세스할 수 있는 Compute Engine 가상 머신 인스턴스에서 사용하기 위해 gcloud CLI를 설치하고 설정하는 경우에 권장됩니다.

인증 및 Google Cloud에 대한 자세한 내용은 인증 개요를 참조하세요.

사용자 계정으로 승인

이 섹션에서는 사용자 계정으로 승인하는 방법을 설명합니다.

Google 계정으로 인증

다음 gcloud CLI 명령어를 사용하여 사용자 계정을 통한 액세스를 승인합니다.

명령어	설명
`gcloud init`	액세스를 승인하고 다른 일반적인 설정 단계를 수행합니다.
`gcloud auth login`	액세스만 승인합니다.

승인 중 이러한 명령어는 Google Cloud에서 계정 사용자 인증 정보를 가져오고 이를 로컬 시스템에 저장합니다. 지정된 계정이 구성에서 활성 계정이 됩니다. gcloud CLI는 저장된 사용자 인증 정보를 사용하여 Google Cloud에 액세스합니다. 단일 gcloud CLI 설치에 사용할 사용자 인증 정보를 저장할 수 있는 계정의 수에는 제한이 없지만 한 번에 계정 하나만 활성화됩니다.

gcloud init 실행

gcloud init는 액세스를 승인하고 다른 일반적인 설정 단계를 수행합니다. gcloud init에서 웹 기반 승인 흐름을 사용하여 사용자 계정을 인증하고 액세스 권한을 부여합니다.

액세스를 승인하고 다른 일반적인 설정 단계를 수행하려면 다음 안내를 따르세요.

gcloud init을 실행합니다.
```
gcloud init
```
또는 명령어가 웹브라우저를 자동으로 열지 못하도록 하려면 다음을 실행합니다.
```
gcloud init --console-only
```
ssh를 사용하여 원격 시스템에서 명령어를 실행하며 해당 시스템의 브라우저에 액세스 권한이 없는 경우 --console-only 플래그를 사용하는 것이 유용합니다. 그런 다음에는 제공된 URL을 로컬 시스템의 브라우저에서 수동으로 열어 승인 프로세스를 완료해야 합니다.
브라우저 기반 승인 흐름을 따라 계정을 인증하고 액세스 권한을 부여합니다.

gcloud init에 대한 자세한 내용은 gcloud CLI 초기화를 참조하세요.

gcloud auth login을 실행하면 사용자 계정만 승인됩니다. 다른 설정 단계를 수행하지 않고 액세스를 승인하려면 다음 옵션 중 하나를 사용합니다.

브라우저가 있는 머신에서 gcloud CLI를 승인하려면 다음 단계를 따르세요.
1. gcloud CLI 승인:
```
gcloud auth login
```
2. 브라우저 기반 승인 흐름을 따라 계정을 인증하고 액세스 권한을 부여합니다.
브라우저가 없는 머신에서 gcloud CLI를 승인해야 하고 브라우저가 있는 다른 머신에 gcloud CLI를 설치할 수 있는 경우 --no-browser 플래그를 사용합니다.
1. gcloud CLI 승인:
```
gcloud auth login --no-browser
```
2. gcloud auth login --remote-bootstrap="으로 시작하는 긴 명령어를 복사합니다.
3. 웹브라우저와 gcloud CLI 도구 버전 372.0 이상이 로컬로 설치된 신뢰할 수 있는 다른 머신의 명령줄에서 이 명령어를 붙여넣고 실행합니다.
4. 웹브라우저를 사용하여 머신에서 긴 URL 출력을 복사합니다.
5. 'Enter the output of the above command' 프롬프트에서 긴 URL을 첫 번째 머신에 붙여넣고 Enter 키를 눌러 승인을 완료합니다.
브라우저가 없는 머신에서 gcloud CLI를 승인해야 하고 브라우저가 있는 다른 머신에 gcloud CLI를 설치할 수 없는 경우 --no-launch-browser 플래그를 사용합니다. --no-launch-browser 플래그는 명령어가 웹브라우저를 자동으로 열지 못하도록 합니다.
1. gcloud CLI 승인:
```
gcloud auth login --no-launch-browser
```
2. https://accounts.google.com/o/oauth2/auth...로 시작하는 긴 URL을 복사합니다.
3. 이 URL을 웹브라우저가 있고 신뢰할 수 있는 다른 머신의 브라우저에 붙여넣습니다.
4. 웹브라우저가 있는 머신에서 승인 코드를 복사합니다.
5. '인증 코드 입력' 프롬프트에서 승인 코드를 첫 번째 머신에 다시 붙여넣고 Enter 키를 눌러 승인을 완료합니다.
액세스 토큰이 이미 있으면 다음 방법 중 하나를 사용해서 액세스 토큰을 gcloud CLI로 전달합니다.
- 액세스 토큰을 파일에 저장하고 --access-token-file 플래그를 통해 경로를 설정합니다.
- 액세스 토큰을 파일에 저장하고 auth/access_token_file 속성에 경로를 설정합니다.
- CLOUDSDK_AUTH_ACCESS_TOKEN 환경 변수를 액세스 토큰 값으로 설정합니다.

Workforce Identity Federation으로 인증

이 섹션에서는 Workforce Identity Federation을 사용하여 gcloud CLI에 로그인하는 방법을 설명합니다.

gcloud CLI 브라우저 기반 로그인

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

로그인 구성 파일을 만듭니다.

로그인 구성 파일을 만들려면 다음 명령어를 실행합니다. 선택적으로 --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 풀 ID
- 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/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 환경 변수가 설정되어 있으면 지웁니다.

gcloud CLI 헤드리스 로그인

헤드리스 흐름을 사용하여 gcloud CLI에 로그인하려면 다음을 수행합니다.

OIDC

IdP 앱에 사용자를 로그인하고 OIDC 토큰을 가져옵니다.

토큰을 가져오는 방법에 관한 자세한 내용은 IdP의 OIDC 문서를 참고하세요.
IdP에서 반환한 OIDC 토큰을 로컬 머신의 안전한 위치에 저장합니다.

다음 명령어를 실행하여 구성 파일을 생성합니다.

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: 직원 풀 사용자 프로젝트와 연결된 프로젝트 번호

주 구성원에게 이 프로젝트에 대한 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"
  }
}

SAML

사용자를 IdP 앱에 로그인하고 SAML 어설션을 가져옵니다.

IdP에서 SAML 어설션을 가져오는 방법에 관한 자세한 내용은 IdP의 SAML 문서를 참고하세요.
IdP에서 반환한 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입니다.
WORKFORCE_POOL_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"
}

토큰 교환을 사용하여 gcloud에 로그인하려면 다음 명령어를 실행합니다.

gcloud auth login --cred-file="config.json"

그러면 gcloud가 IdP 사용자 인증 정보를 임시 Google Cloud 액세스 토큰으로 투명하게 교환하여 Google Cloud에 다른 gcloud 호출을 수행할 수 있게 됩니다.

출력은 다음과 비슷합니다.

Authenticated with external account user credentials for:
[principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/USER_ID].

사용자 인증 정보 계정과 현재 활성 계정을 나열하려면 다음 명령어를 실행합니다.

gcloud auth list

서비스 계정으로 승인

gcloud auth login 명령어는 로컬 파일 시스템에 저장된 사용자 인증 정보 파일을 사용하여 서비스 계정으로 액세스를 승인할 수 있습니다. 이 사용자 인증 정보는 서비스 계정을 가장할 권한이 있는 사용자 인증 정보, 워크로드 아이덴티티 제휴의 사용자 인증 정보 구성 파일 또는 서비스 계정 키일 수 있습니다.

서비스 계정 가장을 사용하여 서비스 계정 승인

gcloud CLI가 가장된 서비스 계정 사용자 인증 정보를 사용하도록 승인하려면 다음을 실행합니다.

Google Cloud 콘솔에서 서비스 계정 페이지로 이동합니다.

서비스 계정으로 이동
기존 계정을 선택하거나 서비스 계정 만들기를 클릭하여 새 계정을 만듭니다.
주 구성원에게 서비스 계정을 가장하는 데 필요한 권한이 있는지 확인하려면 관리자에게 서비스 계정에 대한 서비스 계정 토큰 생성자(roles/iam.serviceAccountTokenCreator) IAM 역할을 주 구성원에게 부여해 달라고 요청합니다. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이 사전 정의된 역할에는 서비스 계정을 가장하는 데 필요한 iam.serviceAccounts.getAccessToken 권한이 포함되어 있습니다.
관리자는 커스텀 역할이나 다른 사전 정의된 역할을 사용하여 주 구성원에게 이 권한을 부여할 수도 있습니다.
gcloud auth login을 실행하여 사용자 ID로 gcloud CLI를 승인합니다.
기본적으로 서비스 계정에서 제공하는 ID와 액세스를 사용하도록 gcloud CLI를 설정하려면 gcloud CLI 구성 명령어를 사용합니다.
```
gcloud config set auth/impersonate_service_account SERVICE_ACCT_EMAIL
```
기본적으로 gcloud CLI에서 가장된 서비스 계정 사용자 인증 정보를 사용하지 않으려면 gcloud CLI 구성 명령어를 사용하여 플래그를 설정 해제합니다.
```
gcloud config unset auth/impersonate_service_account
```

워크로드 ID 제휴를 사용하여 서비스 계정 승인

워크로드 아이덴티티 제휴의 외부 사용자 인증 정보를 사용하여 서비스 계정으로 gcloud CLI를 승인하려면 다음을 실행합니다.

Google Cloud 콘솔에서 서비스 계정 페이지로 이동합니다.

서비스 계정으로 이동
기존 계정을 선택하거나 서비스 계정 만들기를 클릭하여 새 계정을 만듭니다.
지원되는 ID 공급업체의 안내를 따라 워크로드 아이덴티티 제휴를 위한 사용자 인증 정보 구성 파일을 만듭니다.
서비스 계정을 활성화하려면 --cred-file 플래그로 gcloud auth login을 실행합니다.
```
gcloud auth login --cred-file=CONFIGURATION_FILE
```
CONFIGURATION_FILE을 워크로드 아이덴티티 제휴의 사용자 인증 정보 구성 파일 경로로 바꿉니다.

서비스 계정 키를 사용하여 서비스 계정 승인

서비스 계정 키를 사용하여 서비스 계정으로 gcloud CLI를 승인하려면 다음을 수행합니다.

Google Cloud 콘솔에서 서비스 계정 페이지로 이동합니다.

서비스 계정으로 이동
기존 계정을 선택하거나 서비스 계정 만들기를 클릭하여 새 계정을 만듭니다.
서비스 계정 키를 만들려면 IAM 안내에서 서비스 계정 키 만들기를 참고하세요.
서비스 계정을 활성화하려면 --cred-file 플래그로 gcloud auth login을 실행합니다.
```
gcloud auth login --cred-file=KEY_FILE
```
KEY_FILE을 서비스 계정 키 파일의 경로로 바꿉니다.

계정 나열

로컬 시스템에 사용자 인증 정보가 저장된 계정을 나열하려면 gcloud auth list를 실행합니다.

gcloud auth list

gcloud CLI가 계정을 나열하고 활성화된 계정을 표시합니다.

Credentialed accounts:
 - user-1@gmail.com (active)
 - user-2@gmail.com

활성 계정 전환

활성 계정을 전환하려면 gcloud config set를 실행합니다.

gcloud config set account ACCOUNT

여기서 [ACCOUNT]는 계정의 전체 이메일 주소입니다.

다음을 실행하여 다른 계정을 지정하는 별도의 구성을 만들고 구성을 전환하여 계정을 전환할 수도 있습니다.

gcloud config configurations activate CONFIGURATION

각 호출에 따라 gcloud CLI에서 사용하는 계정을 전환하려면 --account 플래그를 사용하여 활성 계정을 재정의합니다.

승인된 세션 길이 설정

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

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

계정의 사용자 인증 정보 취소

사용자 인증 정보를 취소하여 특정 계정을 통한 gcloud CLI의 액세스를 차단할 수 있습니다. 계정을 전환하기 위해 사용자 인증 정보를 취소할 필요는 없습니다.

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

gcloud auth revoke ACCOUNT

모든 머신의 gcloud CLI 액세스 권한을 취소하려면 계정에 액세스할 수 있는 앱 목록에서 gcloud CLI를 삭제합니다.

사용자 인증 정보 파일 작업

사용자 인증 정보 파일 찾기

사용자 인증 정보 파일의 위치를 찾으려면 gcloud info를 실행합니다.

gcloud info

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

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

애플리케이션 기본 사용자 인증 정보 설정

gcloud CLI는 gcloud auth application-default 명령어 그룹으로 애플리케이션 기본 사용자 인증 정보(ADC) 관리를 지원합니다. 사용자 인증 정보를 ADC에 사용하려면 gcloud auth application-default login를 실행하세요.

gcloud auth application-default login

이러한 사용자 인증 정보는 gcloud CLI에서 사용되지 않습니다. ADC를 설정하는 다른 방법은 애플리케이션 기본 사용자 인증 정보 설정을 참고하세요.

unset GOOGLE_APPLICATION_CREDENTIALS
gcloud config unset auth/impersonate_service_account
gcloud auth application-default login

다음 단계

인증 및 Google Cloud에 대한 자세한 내용은 인증 개요 참조하기
gcloud CLI 맞춤설정에 대한 자세한 내용은 gcloud CLI 속성 참조하기
명명된 gcloud CLI 속성 집합 관리에 대한 자세한 내용은 gcloud CLI 구성 참조하기