IAM アカウントを使用して接続する

このページでは、Identity and Access Management（IAM）で準備したアカウントを使用して AlloyDB for PostgreSQL インスタンスにログインするプロセスについて説明します。psql コマンドライン クライアントを使用して IAM ベースのログインを実行する方法を示して、プロセスを示しています。

AlloyDB インスタンスへの接続の概要については、接続の概要をご覧ください。

始める前に

IAM 認証情報を使用して AlloyDB インスタンスにログインするには、プロジェクト、クラスタ、インスタンス、IAM ユーザー アカウントの準備が必要です。

詳細については、IAM 認証を管理するをご覧ください。

OAuth 2.0 トークンで認証する

ユーザーまたはアプリケーションは、次の手順で AlloyDB データベースの認証を行うことができます。

  1. まだ行っていない場合は、AlloyDB インスタンスにログインするユーザーまたはサービス アカウントと同じユーザーまたはサービス アカウントを使用して、Google Cloud CLI を承認します。

  2. gcloud auth print-access-token コマンドを使用して、 Google Cloud から OAuth 2.0 トークンをリクエストします。

    gcloud auth print-access-token

    Google Cloud は、このコマンドの出力として OAuth 2.0 トークンを出力します。

    セキュリティを強化するには、次の手順で AlloyDB 認証でのみ使用するようにトークンを制限します。

    1. まだ追加していない場合は、gcloud auth application-default login コマンドを使用して、現在の環境のアクセス認証情報に alloydb.login スコープを追加します。

      gcloud auth application-default login --scopes=https://www.googleapis.com/auth/alloydb.login,https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/userinfo.email,openid

    2. gcloud auth application-default print-access-token コマンドを使用して制限付き OAuth 2.0 トークンを出力し、トークンのスコープを AlloyDB 認証に限定します。

      gcloud auth application-default print-access-token –-scopes=https://www.googleapis.com/auth/alloydb.login

    OAuth 2.0 トークンを使用すると、ユーザー自身または他のユーザーが、 Google Cloud に対して認証されたリクエストを送信できます。トークンはパスワードと同じレベルのセキュリティで扱います。トークンを安全に保存するか、保存しないでください。このページの後半の psql の使用例では、1 つのアクションで OAuth 2.0 トークンをリクエスト、使用、破棄する方法を示しています。

  3. 次の認証情報を使用して、標準の PostgreSQL 手法で AlloyDB インスタンスにログインします。

    • 前の手順で取得したアクセス トークンをパスワードとして提示します。

    • IAM ユーザー アカウントの場合、データベース ユーザー名はアカウントの完全なメールアドレスです。

    • IAM サービス アカウントの場合、データベース ユーザー名は、.gserviceaccount.com サフィックスを除いたアカウントのメールアドレスです。

次の psql コマンドは、コマンドラインから IAM ユーザーにログインする方法の 1 つを示しています。gcloud auth print-access-token の出力を PGPASSWORD 環境変数に割り当てます。この変数は、psql がデータベースのログイン パスワードとして使用します。

PGPASSWORD=$(gcloud auth print-access-token) psql \
  -h INSTANCE_ADDRESS \
  -U USERNAME \
  -d DATABASE

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

  • INSTANCE_ADDRESS: 接続する AlloyDB インスタンスの IP アドレス。

  • USERNAME: インスタンスで認証する IAM ユーザーの ID。

    IAM ユーザー アカウントの場合は、ユーザー アカウントの完全なメールアドレスを指定します。例: kai@altostrat.com

    IAM サービス アカウントの場合は、.gserviceaccount.com サフィックスを除いたサービス アカウントのアドレスを指定します。たとえば、サービス アカウント my-service@my-project.iam.gserviceaccount.com を指定するには、ここで値 my-service@my-project.iam を使用します。

  • DATABASE: 接続先のデータベースの名前。

psql は、コマンドラインで入力された 100 文字を超えるパスワードを切り捨てます。OAuth 2.0 トークンとともに psql をログイン パスワードとして使用するには、プロンプトが表示されたら手動で貼り付けるのではなく、この例に示すように PGPASSWORD 環境変数を設定する必要があります。

AlloyDB Auth Proxy または AlloyDB 言語コネクタを使用して自動的に認証する

AlloyDB Auth Proxy または AlloyDB Language コネクタを使用すると、IAM ベースの AlloyDB ユーザーを自動的に認証し、OAuth 2.0 トークンを指定しなくてもインスタンスに接続できます。

AlloyDB Auth Proxy を使用するには、--auto-iam-authn フラグを有効にして AlloyDB Auth Proxy クライアントを実行する必要があります。AlloyDB Language Connectors を使用するには、IAM 認証をプログラムで有効にする必要があります。

言語コネクタを使用する場合は、言語ごとに対応するオプションがあります。詳細については、AlloyDB 言語コネクタを構成するをご覧ください。

プロキシ クライアントまたは Language Connectors の実行に使用する IAM アカウントは、データベース ユーザーとして追加したアカウントと同じである必要があります。たとえば、IAM ユーザー アカウント kai@altostrat.com を使用してワークロードを実行する場合は、プロキシ クライアントまたは Language Connectors を使用して、OAuth 2.0 トークンを指定せずに kai@altostrat.com データベース ユーザーを自動的に認証できます。この例では、自動認証は kai@altostrat.com 以外のデータベース ユーザーでは機能しません。

Auth Proxy の実行の詳細については、AlloyDB Auth Proxy を使用して接続するをご覧ください。

言語コネクタの実行の詳細については、AlloyDB 言語コネクタを使用して接続するをご覧ください。

IAM 認証のトラブルシューティング

IAM ベースの認証の試行が失敗した原因を特定する手順は次のとおりです。

  1. Google Cloud コンソールで、[ログ エクスプローラ] ページに移動します。

    [ログ エクスプローラ] に移動

  2. [リソースタイプ] で [AlloyDB インスタンス] をクリックします。

  3. [重大度] で [アラート] をクリックします。

    [アラート] が選択できない場合は、選択した期間内に認証エラーが記録されていません。ログ エクスプローラのコントロールを使用してウィンドウを調整する必要がある場合があります。

  4. [クエリ結果] で、ログエントリに次のいずれかのメッセージがないか確認します。

    Request had invalid authentication credentials.
    アクセス トークンが無効です。
    Caller does not have required permission to use project.
    IAM プリンシパルに必要な IAM ロールまたは権限がありません。エラー メッセージの全文には、不足しているロールまたは権限が指定されています。
    IAM principal does not match database user.

    アクセス トークンで指定された認証済み IAM プリンシパルが、接続するデータベース ユーザーと一致しません。

    トークンで指定されたプリンシパルを表示するには、次のコマンドを実行します。

    curl -H "Content-Type: application/x-www-form-urlencoded" -d "access_token=ACCESS_TOKEN" https://www.googleapis.com/oauth2/v1/tokeninfo

    ACCESS_TOKEN を OAuth 2.0 アクセス トークンに置き換えます。

    Request had insufficient scopes.
    アクセス トークンに alloydb.login スコープまたは cloud-platform スコープが含まれていません。これらのスコープの少なくとも 1 つは必須です。