gcloud CLI を承認する

Google Cloud にアクセスするには、通常 Google Cloud CLI を認可する必要があります。ここでは使用可能な認可オプションを示すとともに、認可に使用するアカウントを管理する方法についても説明します。Compute Engine インスタンスまたは Cloud Shell を使用している場合、gcloud CLI を認可する必要はありません。

アカウントのタイプ

Google Cloud へアクセスできるように gcloud CLI を認可するには、ユーザー アカウントまたはサービス アカウントのいずれかを使用します。

ユーザー アカウントは、エンドユーザーがアプリケーションに認証できるようにする Google Cloud アカウントです。最も一般的な使用例、特に gcloud CLI をインタラクティブに使用する場合には、ユーザー アカウントを使用することをおすすめします。

サービス アカウントは、Google Cloud プロジェクトに関連付けられている Google アカウントであり、特定のユーザーではありません。 Cloud Run functions、App Engine、Compute Engine、Google Kubernetes Engine を使用する場合は、組み込みのサービス アカウントを使用できます。複数のマシンで gcloud CLI スクリプトを実行するには、サービス アカウントをおすすめします。

認可タイプを選択する

Google Cloud リソースを管理するには、Google Cloud CLI を認可する必要があります。Google Cloud CLI と Google Cloud のどちらも、認証と認可には OAuth2 を使用します。

次のいずれかの認可タイプを選択します。

タイプ 説明
ユーザー アカウント コマンドラインから gcloud CLI を使用する場合、または 1 つのマシンで使用する gcloud CLI でスクリプトを記述する場合におすすめします。
サービス アカウント Cloud SDK を本番環境へのマシンのデプロイの一環としてインストールして設定する場合や、すべてのユーザーが root にアクセスできる Compute Engine 仮想マシン インスタンスで使用する場合におすすめします。

認証と Google Cloud の詳細については、認証の概要をご覧ください。

ユーザー アカウントを使用して認可する

ユーザー アカウントでのアクセスを認可するには、以下の gcloud CLI コマンドを使用します。

コマンド 説明
gcloud init アクセスを認可し、他の共通設定手順を実行します。
gcloud auth login アクセスの承認のみを行います。

承認の際、このコマンドは、Google Cloud からアカウントの認証情報を取得して、ローカル システムに保存します。指定したアカウントが、構成のアクティブ アカウントになります。gcloud CLI は、保存されている認証情報を使用して Google Cloud にアクセスします。1 つの gcloud CLI 環境で認証情報を保存できるアカウントの数に制限はありませんが、有効なアカウントは常に 1 つだけです。

gcloud init を実行する

gcloud init は、アクセスを認可し、他の共通設定手順を実行します。gcloud init では、ウェブベースの承認フローを使用してユーザー アカウントを認証し、アクセス権限を付与します。

アクセスを認可し、他の共通設定手順を行うには、次のコマンドを実行します。

  1. gcloud init を実行します。

    gcloud init

    ウェブブラウザが自動的に開かないようにするには、代わりに次のコマンドを実行します。

    gcloud init --console-only

    リモート システムで ssh を使用してコマンドを実行するときに、そのシステム上のブラウザにアクセスできない場合、--console-only フラグを使用すると便利です。この場合、指定された URL をローカル システムのブラウザで開いて、承認プロセスを完了する必要があります。

  2. ブラウザベースの承認フローに従ってアカウントを認証し、アクセス権限を付与します。

gcloud init の詳細については、gcloud CLI の初期化をご覧ください。

gcloud auth login を実行します。

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. 「上記のコマンドの出力を入力してください」というプロンプトがある最初のマシンに長い 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 環境変数にアクセス トークンの値を設定します。

サービス アカウントを使用して承認する

gcloud auth login コマンドでは、ローカル ファイル システムに保存されている認証情報ファイルを使用して、サービス アカウントによるアクセスを承認できます。この認証情報には、サービス アカウントの権限を借用する権限を持つユーザー認証情報、Workload Identity 連携の認証情報構成ファイル、サービス アカウント キーのいずれかを使用できます。

サービス アカウントの権限借用を使用してサービス アカウントを承認する

gcloud CLI に対して、権限が借用されたサービス アカウント認証情報の使用を承認するには、次の手順を行います。

  1. Google Cloud コンソールで、[サービス アカウント] ページに移動します。

    [サービス アカウント] に移動

  2. 既存のアカウントを選択するか、[サービス アカウントの作成] をクリックして新しいアカウントを作成します。

  3. プリンシパルに、サービス アカウントの権限を借用するために必要な権限を持たせるには、サービス アカウントに対するサービス アカウント トークン作成者（roles/iam.serviceAccountTokenCreator）の IAM ロールをプリンシパルに付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセスを管理するをご覧ください。

    この事前定義ロールには、サービス アカウントの権限を借用するために必要な iam.serviceAccounts.getAccessToken 権限が含まれています。

    管理者は、カスタムロールや他の事前定義ロールを使用して、この権限をプリンシパルに付与することもできます。

  4. gcloud auth login を実行して、ユーザー ID を使用して gcloud CLI を承認します。

  5. デフォルトでサービス アカウントによって提供される ID とアクセス権を使用するように gcloud CLI を設定するには、gcloud CLI config コマンドを使用します。

    gcloud config set auth/impersonate_service_account SERVICE_ACCT_EMAIL

  6. デフォルトで、gcloud CLI によって権限が借用されたサービス アカウント認証情報の使用を停止するには、gcloud CLI config コマンドでフラグを設定解除します。

    gcloud config unset auth/impersonate_service_account

Workload Identity 連携を使用してサービス アカウントを承認する

Workload Identity 連携の外部認証情報を使用してサービス アカウントで gcloud CLI を承認するには、次の操作を行います。

  1. Google Cloud コンソールで、[サービス アカウント] ページに移動します。

    [サービス アカウント] に移動

  2. 既存のアカウントを選択するか、[サービス アカウントの作成] をクリックして新しいアカウントを作成します。

  3. サポートされている ID プロバイダの手順に沿って、Workload Identity 連携の認証情報構成ファイルを作成します。

  4. サービス アカウントを有効にするには、--cred-file フラグを指定して gcloud auth login を実行します。

    gcloud auth login --cred-file=CONFIGURATION_FILE

    CONFIGURATION_FILE は、Workload Identity 連携の認証情報構成ファイルのパスに置き換えます。

サービス アカウント キーを使用してサービス アカウントを承認する

サービス アカウント キーを使用してサービス アカウントで gcloud CLI を承認するには、次の手順を行います。

  1. Google Cloud コンソールで、[サービス アカウント] ページに移動します。

    [サービス アカウント] に移動

  2. 既存のアカウントを選択するか、[サービス アカウントの作成] をクリックして新しいアカウントを作成します。

  3. サービス アカウント キーを作成するには、IAM の手順を参照してサービス アカウント キーを作成してください。

  4. サービス アカウントを有効にするには、--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 サービスのセッション継続時間を設定するをご覧ください。

アカウントの認証情報を取り消す

特定のアカウントによる 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 の構成をご覧ください。