G-gen の武井です。 Google Cloud（旧称 GCP）の Identity and Access Management（IAM）にて、権限不足に伴うエラーが発生した場合の対処方法について説明します。

前提知識

用語

Google Cloud (旧称 GCP) の Identity and Access Management（IAM）を理解する上で、重要な用語は以下のとおりです。

用語	意味
Google アカウント	IAM の実行主体 (人)
Google グループ	上記をグループ化したもの
サービスアカウント	IAM の実行主体 (サービス)
IAM ロール	各種リソースに対して実行可能な権限のセット
IAM ポリシー	各種リソースに対して「誰が」、「何をできるか」を規定するもの

用語同士の関係を、図と実例で説明します。

Google アカウント / グループ (実行主体) に対し、Compute Engine で VM マシンの作成や削除が可能な権限を含む IAM ロール を付与
VM マシンに紐づけたサービスアカウント (実行主体) に対し、Cloud Storage でバケット内オブジェクトの表示や取得が可能な権限を含む IAM ロール を付与
上記の関係性 (リソースに対し誰が何をできるか) を実現するために規定 (設定) したものが IAM ポリシー

IAM ロールとは、Google Cloud リソースに対して、特定の操作を実行可能にするための権限セットです。プリンシパル（実行主体。Google アカウント、グループ、サービスアカウント等）に対して、リソース上で付与します。

IAM ロールは以下の3種類に分類されます。

タイプ	管理者	特徴
基本ロール	Google Cloud	Cloud IAM 導入前より存在。オーナー / 編集者 / 閲覧者の 3 ロールのみ
事前定義ロール	Google Cloud	特定のサービス (リソース) へのアクセスを細かく制御したロール
カスタムロール	ユーザー	ユーザーが指定する権限に応じたきめ細かなアクセス制御を可能としたロール

上記のうち「基本ロール」には広い権限が含まれているため、可能であればより狭い範囲の権限を持つ事前定義ロールか、ユーザー独自で定義するカスタムロールを使うことが推奨されています。

IAM の基本知識については、以下の記事も参考にしてください。

実例をもとに、IAM の権限不足に起因するエラーが発生した際の対処方法について説明します。

Cloud Run functions で動作するプログラムが、Secret Manager のシークレット値を取得する処理で例外が発生しました。Cloud Run functions には、サービスアカウントを紐づけており、その権限でシークレット値を取得する想定です。

エラーログには、以下のメッセージが含まれています。

403 Permission 'secretmanager.versions.access' denied for resource 'projects/myproject/secrets/mysecret/versions/latest' (or it may not exist).

Cloud Logging からエラーログを確認します。以下は実際のスクリーンショットです。先ほど記載したものと同様のエラーメッセージが表示されています。

ログには secretmanager.versions.access と記されていることから、この権限が不足していることで例外が発生していると推測できます。あるいは、このシークレットが存在していない可能性もありますが、存在は確認できているものとします。

このことから、Cloud Run functions に紐づけているサービスアカウントに対して、上記の権限を含む IAM ロールを紐づけることでエラーが解消できると判断します。

最適な IAM ロールを選択する際に役立つのが、公式リファレンスです。

ある権限がどのロールに含まれているかを確認するには、IAM roles and permissions index というドキュメントを使います。

このドキュメントでは、権限（permission）名から IAM ロールを検索できるようになっており、今回のようなエラーが発生した際に活用できます。

今回の例では secretmanager.versions.access という権限が不足していましたので、この権限がどの IAM ロールに含まれるか調べてみます。

ページ内の検索ボックスに権限名を入力すると、一致する権限名が表示されます。この権限名をクリックすると、その権限を持つロールの一覧が確認できます。

また同ドキュメントでは逆に、IAM ロール名で検索して、その IAM ロールがどんな権限（permission）を持っているかを検索することもできます。

前述の IAM roles and permissions index には、すべての基本ロールと事前定義ロールの情報が記載されていますが、一般的には Google Cloud プロダクトごとに、IAM ロールがまとまっているページが存在しますので、そちらを参照しても構いません。

次に最適な IAM ロールの候補選定です。最小権限の原則にもとづき、必要最低限の権限セットで構成された IAM ロールを選択します。

さきほどのリファレンスドキュメントで検索し、結果として表示されたロール名をクリックすると、そのロールがどの権限（permissions）を持っているかが一覧表示されます。

以下は IAM ロールの記載の例です。

オーナー（roles/owner）やSecret Manager 管理者（roles/secretmanager.admin）は、エラーは解決できますが最適なロールではありません。なぜなら今回実現したい操作は「シークレット値の取得」だけですが、必要以上の権限が付与されているためです。

最小権限の原則にもとづけば、Secret Manager のシークレットアクセサー（roles/secretmanager.secretAccessor）が適切であるとわかります。

ロール名	概要	評価
roles/owner	オーナー権限レベル	△
roles/secretmanager.admin	Secret Manager の管理者レベル	△
roles/secretmanager.secretAccessor	シークレットへのアクセスを許可	◯