サービス ID で認証する

Google Distributed Cloud（GDC）エアギャップのサービス ID は、ワークロードまたはサービスがリソースとマイクロサービスにプログラムで安全にアクセスするための専用 ID を提供します。これらは、ユーザーではなくアプリケーションやワークロードで使用される特別な ID であり、ユーザーのログインには使用できません。ユーザーアカウントと同様に、サービス ID に権限とロールを付与して、アクセス権限を定義します。

このコンセプトには 2 つの用語が使用されています。GDC コンソールでは主にサービス ID という用語が使用されますが、gdcloud コマンドと API のやり取りではサービスアカウントという用語がよく使用されます。後者は、基盤となる Kubernetes カスタムリソース ProjectServiceAccount の名前を反映しています。どちらの用語も、ワークロードの非人間 ID を指します。このドキュメントでは、サービス ID を主な用語として使用します。

サービス ID は、次のような GDC インフラストラクチャの管理に役立ちます。

内部の Distributed Cloud サービスとワークロードが、Distributed Cloud コントロールプレーンのアプリケーションプログラミングインターフェース（API）に安全にアクセスできるようにします。たとえば、データベースサービスが Kubernetes API とやり取りしてデータベースを作成および削除します。
Distributed Cloud のお客様のワークロードが Distributed Cloud サービスにアクセスし、承認されたアプリケーションプログラミングインターフェース（API）呼び出しを行います。たとえば、サービス ID は、Vertex AI Workbench ノートブックを使用して Speech-to-Text API で音声ファイルを文字変換することで、顧客を管理できます。
Distributed Cloud と連携する外部ワークロード。たとえば、サービス ID は、ドキュメントをデジタル化するが、光学式文字認識（OCR）API を使用して現在の OCR エンジンを置き換えたい Distributed Cloud の外部のアプリケーションを管理できます。
分散クラウドサービスまたはシステムコントローラが顧客リソースまたはユーザークラスタに安全にアクセスできるようにします。たとえば、サービス ID は、管理クラスタで実行されているサービスコントローラがお客様が管理するユーザークラスタ内でワークロードを実行する必要がある認証と認可のワークフローを管理できます。

サービス ID のアカウントは、GDC コンソール、gdcloud CLI、または API を使用して管理できます。gdcloud CLI では、サービス ID 機能はグローバル ProjectServiceAccount API に基づいて構築されています。ProjectServiceAccount リソースはグローバルに構成されるため、gdcloud ユニバース内のすべてのゾーンで動作します。

始める前に

サービス ID はプロジェクト内でのみ作成できます。プロジェクトの作成方法については、プロジェクトを作成するをご覧ください。

サービス ID の管理には、サービス ID（ProjectServiceAccount リソースで表される）と、それに関連付けられた認証情報（公開鍵と秘密鍵のペア）の両方が含まれます。サービス ID とその認証情報を管理するために必要な権限を取得するには、組織の IAM 管理者またはプロジェクトの IAM 管理者に、そのプロジェクトでプロジェクトの IAM 管理者（project-iam-admin）ロールを付与するよう依頼してください。

サービス ID を作成する

サービス ID の作成には、アカウントとそれに関連付けられた認証情報の作成が含まれます。

アカウントを作成

サービス ID のアカウントを作成するには、GDC コンソール、gdcloud CLI、または API を使用して、プロジェクトに ProjectServiceAccount リソースを作成します。

コンソール

GDC コンソールにログインします。
ナビゲーションメニューで、[ID とアクセス] > [サービス ID] を選択します。
[サービス ID を作成] をクリックします。[サービス ID の詳細] ページが開きます。
[サービス ID 名] フィールドに、サービス ID の名前を入力します。例: testserviceidentity。
[作成] をクリックします。

gdcloud

アカウントを作成します。

gdcloud iam service-accounts create NAME \
    --project=PROJECT

次の値を置き換えます。

NAME: ProjectServiceAccount の名前。名前はプロジェクト Namespace 内で一意である必要があります。
PROJECT: サービス ID を作成するプロジェクト。gdcloud init がすでに設定されている場合は、--project フラグを省略します。

このコマンドは、Management API サーバーのプロジェクト Namespace に ProjectServiceAccount を作成します。

API

my-project-sa.yaml などの ProjectServiceAccount カスタムリソース YAML ファイルを作成します。
```
apiVersion: resourcemanager.global.gdc.goog/v1
kind: ProjectServiceAccount
metadata:
  name: NAME
  namespace: PROJECT
spec:
  keys:
  - algorithm: ALGORITHM
  id: KEY_ID
  key: BASE64_ENCODED_KEY
  validAfter: "START_TIME"
  validBefore: "EXPIRATION_TIME"
```
次の変数を置き換えます。
- NAME: ProjectServiceAccount リソースの名前。名前はプロジェクトの Namespace 内で一意である必要があります。
- PROJECT: サービス ID を作成するプロジェクト。
- ALGORITHM: 鍵のアルゴリズム。ES256 鍵のみがサポートされています。
- KEY_ID: 鍵の固有識別子。この ID は、検証に使用する鍵を特定するために使用されます。
- BASE64_ENCODED_KEY: 照合する PEM 形式の Base64 エンコードされた公開鍵。この公開鍵の生成に使用される秘密鍵は、ECDSA P256 PEM 形式で指定する必要があります。
- START_TIME: キーが有効になる開始時間（2025-02-07T00:59:34Z など）。
- EXPIRATION_TIME: 鍵の有効期限（2026-02-07T00:59:34Z など）。
ProjectServiceAccount カスタムリソースをグローバル API サーバーに適用します。
```
kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG apply -f my-project-sa.yaml
```
GLOBAL_API_SERVER_KUBECONFIG 変数を、グローバル API サーバーの kubeconfig ファイルのパスに置き換えます。

認証情報を作成

ワークロードまたはアプリケーションがサービス ID（作成したアカウントで表される）として認証できるようにするには、認証情報を生成する必要があります。認証情報を作成するには、暗号化された秘密鍵と公開鍵のペアを生成し、公開鍵をサービス ID に関連付けます。

サービス ID の認証情報を作成するには、GDC コンソール、gdcloud CLI、または API を使用します。

コンソール

GDC コンソールにログインします。
ナビゲーションメニューで、[ID とアクセス] > [サービス ID] を選択します。
キーに追加するサービス ID の名前をクリックします。
[新しいキーを作成] をクリックします。
新しいキーが [キー] リストに表示され、キーが正常に作成されたことを確認するダイアログが表示されます。

gdcloud

gdcloud コマンドは、アプリケーションのデフォルト認証情報の JSON ファイルと公開鍵と秘密鍵のペアを作成します。

gdcloud iam service-accounts keys create APPLICATION_DEFAULT_CREDENTIALS_FILENAME \
    --project=PROJECT \
    --iam-account=NAME \
    --ca-cert-path=CA_CERTIFICATE_PATH

次の値を置き換えます。

APPLICATION_DEFAULT_CREDENTIALS_FILENAME: JSON ファイルの名前。
PROJECT : 鍵を作成するプロジェクトを選択します。gdcloud init がすでに設定されている場合は、--project フラグを省略できます。
NAME: 鍵を追加するサービス ID の名前。
CA_CERTIFICATE_PATH: 省略可。認証エンドポイントを検証するための認証局（CA）証明書のパス。このパスを指定しない場合、システム CA 証明書が使用されます。CA はシステムの CA 証明書にインストールする必要があります。

Distributed Cloud は、秘密鍵が署名する JSON ウェブトークン（JWT）の検証に使用する ProjectServiceAccount 鍵に公開鍵を追加します。秘密鍵は、アプリケーションのデフォルト認証情報の JSON ファイルに書き込まれます。

次の例は、アプリケーションのデフォルト認証情報の JSON ファイルを示しています。

{
"type": "gdch_service_account",
"format_version": "1",
"project": "project_name",
"private_key_id": "abcdef1234567890",
"private_key": "-----BEGIN PRIVATE KEY-----\nETC\n-----END PRIVATE KEY-----\n",
"name": "service_identity_name",
"ca_cert_path": "/path/to/ca.crt",
"token_uri": "https://service-identity.<Domain>/authenticate"
}

この例では次の値を使用します。

project: 組織内のプロジェクト名前空間。
private_key_id: 鍵に割り当てられた ID。
private_key: CLI が生成する PEM 形式の ECDSA P256 秘密鍵。
name: サービス ID の名前。
ca_cert_path: 認証エンドポイントの検証に使用される認証局（CA）証明書のパス。
token_uri: 認証エンドポイントのアドレス。

API

公開鍵と秘密鍵のペアを生成します。次のコマンドでは、この目的でよく使用されるツールである openssl を例として使用します。
```
openssl ecparam -name prime256v1 -genkey -noout -out "key.pem"
openssl ec -in "key.pem" -pubout > "pub.pem"
```

公開鍵を Base64 でエンコードし、鍵 ID を取得します。

KEY_ID=$(openssl pkey -in key.pem -pubout -outform der | openssl dgst -sha256 | sed 's/^.* //')
BASE64_ENCODED_KEY=$(cat pub.pem | base64)

前の手順で生成した鍵情報を含めて、ProjectServiceAccount カスタムリソース YAML ファイルを作成または更新します。
```
apiVersion: resourcemanager.global.gdc.goog/v1
kind: ProjectServiceAccount
metadata:
  name: NAME
  namespace: PROJECT
spec:
  keys:
  - algorithm: ALGORITHM
  id: KEY_ID
  key: BASE64_ENCODED_KEY
  validAfter: "START_TIME"
  validBefore: "EXPIRATION_TIME"
```
次の変数を置き換えます。
- NAME: ProjectServiceAccount リソースの名前。名前はプロジェクトの Namespace 内で一意である必要があります。
- PROJECT: 鍵を作成するプロジェクト。
- ALGORITHM: 鍵のアルゴリズム。ES256 鍵のみがサポートされています。
- KEY_ID: 鍵の固有識別子。この ID は、検証に使用する鍵を特定するために使用されます。
- BASE64_ENCODED_KEY: 照合する PEM 形式の Base64 エンコードされた公開鍵。この公開鍵の生成に使用される秘密鍵は、ECDSA P256 PEM 形式で指定する必要があります。
- START_TIME: キーが有効になる開始時間（2025-02-07T00:59:34Z など）。
- EXPIRATION_TIME: 鍵の有効期限（2026-02-07T00:59:34Z など）。
ProjectServiceAccount カスタムリソースをグローバル API サーバーに適用します。
```
kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG apply -f my-project-sa.yaml
```
GLOBAL_API_SERVER_KUBECONFIG 変数を、グローバル API サーバーの kubeconfig ファイルのパスに置き換えます。
秘密鍵を含むアプリケーションのデフォルト認証情報の JSON ファイルを作成します。JSON ファイルの KEY_ID 変数が、ProjectServiceAccount 仕様で使用した KEY_ID 変数と同じ値に設定されていることを確認します。
```
cat <<EOF > "key_file.json"
{
  "format_version": "1",
  "name": "NAME",
  "private_key": "$(tr '\n' '\t' < "key.pem" | sed 's/\t/\\n/g')",
  "private_key_id": "KEY_ID",
  "project": "PROJECT",
  "token_uri": "AUTH_URL",
  "type": "gdch_service_account"
}
EOF
```
次の変数を置き換えます。
- NAME: サービス ID の名前。
- KEY_ID: 鍵の固有識別子。この ID は、検証に使用する鍵を特定するために使用されます。また、ProjectServiceAccount 仕様で使用される KEY_ID 値と一致する必要があります。
- PROJECT: 組織内のプロジェクト Namespace。
- AUTH_URL: 認証エンドポイントのアドレス。

生成されたキーファイルを使用して、このサービス ID として gdcloud CLI を認証する方法については、キーを使用してサービス ID を承認するをご覧ください。

サービス ID を表示する

このセクションでは、サービス ID とそれに関連付けられた公開鍵を表示する方法について説明します。

サービス ID のリストを表示する

プロジェクト内のサービス ID のリストを表示するには、GDC コンソールまたは gdcloud CLI を使用します。

コンソール

GDC コンソールにログインします。
プロジェクトを選択します。
ナビゲーションメニューで、[Identity & Access > Service Identities] をクリックして、プロジェクトのサービス ID のリストを表示します。

gdcloud

プロジェクトのサービス ID アカウントを一覧表示します。

gdcloud iam service-accounts list \
    --project=PROJECT

PROJECT をプロジェクト ID で置き換えます。

サービス ID の公開鍵のリストを表示する

プロジェクトのサービス ID アカウントに登録されている公開鍵を一覧表示します。

gdcloud iam service-accounts keys list \
    --project=PROJECT \
    --iam-account=NAME

次のように置き換えます。

PROJECT: プロジェクト ID。
NAME: 使用するサービス ID アカウントの名前。

サービス ID の権限を付与する

サービス ID に権限を付与するには、GDC コンソールまたは gdcloud CLI を使用してロールバインディングを作成し、1 つ以上のロールを割り当てます。

コンソール

GDC コンソールにログインします。
プロジェクトを選択します。
ナビゲーションメニューで、[Identity & Access > Access] を選択します。
[メンバー] リストで、[メンバーを追加] をクリックします。[ユーザーとロール] ページが表示されます。
[メンバータイプ] リストで [サービス ID] を選択します。
[サービス ID] リストで、ロールバインディングを割り当てるサービス ID を選択します。
[ロール] リストで、サービス ID に割り当てるロール（バックアップ作成者など）を選択します。
省略可: 別のロールを追加するには、[別のロールを追加] をクリックします。追加のロールを選択します。
[追加] をクリックします。

gdcloud

サービス ID アカウントは、プロジェクト Namespace 内のロールまたは別の Namespace のロールにバインドできます。

アカウントをプロジェクトの Namespace 内のロールにバインドします。
```
gdcloud iam service-accounts add-iam-policy-binding \
    --project=PROJECT \
    --role=ROLE \
    --iam-account=NAME
```
次のように置き換えます。
- PROJECT: ロールバインディングを作成するプロジェクト。gdcloud init がすでに設定されている場合は、--project フラグを省略できます。
- ROLE: アカウントに割り当てる事前定義ロール。ロールは Role/name 形式で指定します。ここで、Role は Kubernetes タイプ IAMRole で、name は事前定義されたロールの名前です。たとえば、プロジェクト閲覧者のロールを割り当てるには、ロールを IAMRole/project-viewer に設定します。
- NAME: 使用するサービス ID アカウントの名前。
アカウントを別の Namespace 内のロールにバインドします。
```
gdcloud iam service-accounts add-iam-policy-binding \
    --role=ROLE \
    --role-namespace=ROLE_NAMESPACE \
    --iam-account=NAME
```
次のように置き換えます。
- ROLE: アカウントに割り当てる事前定義ロール。ロールは Role/name 形式で指定します。ここで、Role は Kubernetes タイプ IAMRole で、name は事前定義されたロールの名前です。たとえば、プロジェクト閲覧者のロールを割り当てるには、ロールを IAMRole/project-viewer に設定します。
- ROLE_NAMESPACE: プロジェクトの名前空間以外の、アカウントにバインドするロールの名前空間。
- NAME: 使用するサービス ID アカウントの名前。

サービス ID を認証して使用する

サービス ID として動作するように gdcloud や他のツールを構成するには、まずサービス ID のキーファイルを使用して gdcloud に対して認証を行う必要があります。認証が完了すると、サービス ID の認証情報を使用してトークンまたは kubeconfig ファイルを生成できます。

鍵を使用してサービス ID を承認する

gdcloud auth activate-service-account コマンドは、サービス ID を使用して gdcloud CLI を認証します。これにより、ユーザーアカウントではなく、サービス ID アカウントの権限を使用して Distributed Cloud リソースに対してアクションを実行できます。

キーを使用してサービス ID を承認します。

認証情報鍵ファイルを作成します（まだ作成していない場合）。
次のコマンドを実行して、サービス ID を有効にします。
```
gdcloud auth activate-service-account --key-file=KEY_FILE
```
KEY_FILE は、認証情報キーファイル（通常は JSON 形式）のパスに置き換えます。

有効化が成功すると、gdcloud はユーザーの認証情報ではなく、サービス ID の認証情報を使用します。

サービス ID の ID トークンを出力する

サービス ID を承認すると、その ID トークンを出力できます。このトークンは、HTTP リクエストの認証に署名なしトークンとして使用できます。つまり、このトークンを所有するすべてのユーザーに、AUDIENCES パラメータで定義されたサービスへのアクセス権が付与されます。

指定されたサービス ID アカウントの ID トークンを出力します。

gdcloud auth print-identity-token --audiences=AUDIENCES

AUDIENCES は、トークンの対象となる受信者またはサービスに置き換えます。指定できるユーザーリストは 1 つのみです。

kubeconfig ファイルを生成する

サービス ID を承認したら、クラスタを認証するための kubeconfig ファイルを生成できます。

gdcloud core/organization_console_url プロパティを設定します。
```
gdcloud config set core/organization_console_url
https://GDC_URL
```
GDC_URL は、組織の URL に置き換えます。
アクティブなサービス ID を使用してクラスタにアクセスするための kubeconfig ファイルを生成します。
- ゾーンクラスタの場合:
```
export KUBECONFIG=KUBECONFIG_PATH
gdcloud clusters get-credentials CLUSTER_NAME --zone ZONE
```
  次のように置き換えます。
  - KUBECONFIG_PATH: 生成された kubeconfig ファイルを保存するパス。
  - CLUSTER_NAME: ゾーンクラスタの名前。
    
    注: クラスタ名のリストは、ログイン構成 URL（
    https://GDC_URL/.well-known/login-config）で確認できます。
  - ZONE: クラスタが配置されているゾーンの名前。
- グローバル API サーバーの場合:
```
export KUBECONFIG=KUBECONFIG_PATH
gdcloud clusters get-credentials global-api
```
  KUBECONFIG_PATH は、生成された kubeconfig ファイルを保存するパスに置き換えます。

kubeconfig ファイルが生成され、サービス ID として認証するように構成されます。次の例は、YAML ファイルの例を示しています。

apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: <REDACTED>
    server: <REDACTED>
  name: cluster-name
contexts:
- context:
    cluster: cluster-name
    user: gdch_console-<REDACTED>_cluster-name
  name: cluster-name-gdch_console-<REDACTED>_cluster-name
current-context: cluster-name-gdch_console-gdc1-staging-gpcdemolabs-com_cluster-name
kind: Config
preferences: {}
users:
- name: gdch_console-<REDACTED>_cluster-name
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1
      args:
      - --audience=<REDACTED>
      command: gdcloud-k8s-auth-plugin
      env: null
      installHint: Run 'gdcloud components install gdcloud-k8s-auth-plugin' to use
        plugin
      interactiveMode: Never
      provideClusterInfo: false

サービス ID を削除する

サービス ID を削除すると、ProjectServiceAccount とそれに関連付けられた公開鍵が削除され、既存の秘密鍵が無効になります。また、アプリケーションはそのサービス ID を使用してプロジェクトリソースにアクセスできなくなります。

サービス ID を削除するには、GDC コンソールまたは gdcloud CLI を使用します。

コンソール

GDC コンソールにログインします。
ナビゲーションメニューで、[ID とアクセス] > [サービス ID] を選択します。
削除するサービス ID のチェックボックスをオンにします。
[削除] をクリックします。
確認ダイアログが表示されます。[削除を確定するには、次の内容を入力してください] フィールドに「remove」と入力します。
[削除] をクリックします。

gdcloud

次のコマンドを実行して、サービス ID を削除します。

gdcloud iam service-accounts delete NAME \
    --project=PROJECT

次のように置き換えます。

NAME: 削除するサービス ID アカウントの名前。
PROJECT: プロジェクト ID。

認証情報を削除

サービス ID アカウント全体を削除せずに特定の鍵ペアを無効にする場合は、サービス ID のアカウントから公開鍵を削除します。この操作を行うと、対応する秘密鍵が無効になります。

公開鍵を削除するには、GDC コンソールまたは gdcloud CLI を使用します。

コンソール

GDC コンソールにログインします。
ナビゲーションメニューで、[ID とアクセス] > [サービス ID] を選択します。
削除する鍵があるサービス ID の名前をクリックします。
[削除] をクリックします。
確認ダイアログで [削除] をクリックします。

gdcloud

プロジェクトのサービス ID アカウントから、鍵 ID を持つ公開鍵を削除します。

gdcloud iam service-accounts keys delete KEY_ID \
    --project=PROJECT \
    --iam-account=NAME

次のように置き換えます。

KEY_ID: 鍵の固有識別子。
PROJECT: プロジェクト ID。
NAME: サービス ID アカウントの名前。

サービス ID で認証する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

サービス ID を作成する

アカウントを作成

コンソール

gdcloud

API

認証情報を作成

コンソール

gdcloud

API

サービス ID を表示する

サービス ID のリストを表示する

コンソール

gdcloud

サービス ID の公開鍵のリストを表示する

サービス ID の権限を付与する

コンソール

gdcloud

サービス ID を認証して使用する

鍵を使用してサービス ID を承認する

サービス ID の ID トークンを出力する

kubeconfig ファイルを生成する

サービス ID を削除する

コンソール

gdcloud

認証情報を削除

コンソール

gdcloud

サービス ID で認証する