0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@swallows(しょうた)

Amazon Cognito × Google Workspace で SAML ログインを構築する手順

0
Posted at

はじめに

「CognitoでSAML連携して」と言われて、何から手を付けていいかわからない——。

Amazon Cognito と Google Workspace（GWS）の SAML 連携を一から構築した際の手順をまとめたものです。

できるだけ「なぜその設定をするのか」を添えながら書いています。

この記事でやること

  • Cognito User Pool を作成する
  • Google Workspace にカスタム SAML アプリを作成する
  • 両者を連携させて、GWS アカウントでログインできるようにする
  • 動作確認まで行う

前提条件

項目 必要なもの
AWS マネジメントコンソールにログインできること（Cognito操作権限あり）
Google Workspace Admin Console（admin.google.com）に特権管理者でログインできること
コールバックURL バックエンドの認証コールバック先が決まっていること（テスト用なら https://localhost:3000/auth/callback でOK）

全体像を理解する

登場人物は3つだけ

用語 役割 例え
Google Workspace（IdP） 「この人はうちの社員です」と証明する パスポート発行所
Amazon Cognito（SP） その証明を受け取ってトークンを発行する 空港の入国審査
SAML 2.0 2者間の通信ルール パスポートの規格

IdP（Identity Provider）が身元を保証し、SP（Service Provider）がそれを信頼してサービスを提供する、というのが SAML の基本的な考え方です。

認証フローの全体像

ユーザー
  │
  │ ① アプリにアクセス
  ▼
アプリケーション（バックエンド）
  │
  │ ② 未認証なので Cognito へリダイレクト
  ▼
Amazon Cognito
  │
  │ ③ Google Workspace へリダイレクト
  ▼
Google Workspace（ログイン画面）
  │
  │ ④ ログイン成功 → SAML レスポンスを Cognito へ返す
  ▼
Amazon Cognito
  │
  │ ⑤ SAML レスポンスを検証し、トークンを発行
  ▼
アプリケーション（バックエンド）
  │
  │ ⑥ トークンを検証してログイン完了
  ▼
ユーザーがアプリを利用可能に

作業の流れ

GWS と Cognito はお互いの情報を登録し合う必要があるため、以下の順序で進めます。

Phase 1: Cognito User Pool を作成（→ User Pool ID とドメインを取得）
    ↓
Phase 2: GWS に SAML アプリを作成（Cognito の情報を入力 & GWS のメタデータを取得）
    ↓
Phase 3: Cognito に GWS の IdP 情報を登録
    ↓
Phase 4: Cognito のアプリクライアントに IdP を紐づけ
    ↓
Phase 5: 動作確認

Phase 1: Cognito User Pool を作成する

なぜ最初に Cognito を作るのか

Cognito 側で生成される User Pool ID と ドメイン が、GWS の設定に必要になるためです。

手順

  1. AWS マネジメントコンソールにログイン
  2. 右上のリージョンを確認（例：アジアパシフィック（東京） ap-northeast-1）
  3. 検索バーに「Cognito」と入力して開く
  4. 「ユーザープールを作成」をクリック

作成画面が表示されるので、以下の通り入力します。

項目 設定値
アプリケーションタイプ 従来のウェブアプリケーション
アプリケーション名 任意（例：myapp-userpool）
サインイン識別子のオプション メールアドレス にチェック
自己登録を有効化 チェックを外す
リターンURL コールバックURL（例：https://localhost:3000/auth/callback）

💡 ポイント

  • アプリケーションタイプは「従来のウェブアプリケーション」を選びます。バックエンドで認証を処理する構成に合致するためです。
  • サインイン識別子で「メールアドレス」を選ぶのは、Cognito 上のユーザー識別用です。実際のログインは GWS（SAML）経由になります。
  • 自己登録は外します。ユーザーは GWS 経由で自動作成されるため、誰でもサインアップできる必要はありません。

「ユーザーディレクトリを作成する」をクリックして完了です。

作成後に控える値

作成完了画面から、以下の3つを控えてください。後の手順で使います。

値 確認場所 例
User Pool ID ユーザープール概要画面 ap-northeast-1_AbCdEfGhI
Cognito ドメイン アプリケーションの統合 > ドメイン https://xxxxxxxx.auth.ap-northeast-1.amazoncognito.com
App Client ID アプリケーションの統合 > アプリクライアント 英数字の文字列

Phase 2: Google Workspace で SAML アプリを作成する

この Phase でやること

  • GWS にカスタム SAML アプリを作成する
  • Cognito の情報（ACS URL / Entity ID）を GWS に登録する
  • GWS のメタデータ（XML ファイル）を取得する

Step 2-1: カスタム SAML アプリを追加する

  1. https://admin.google.com/ に特権管理者でログイン
  2. 左メニュー「アプリ」→「ウェブアプリとモバイルアプリ」
  3. 「アプリを追加」→「カスタム SAML アプリを追加」
  4. アプリ名を入力（例：myapp-cognito）
  5. 「続行」をクリック

Step 2-2: Google の IdP 情報をダウンロードする

「Google ID プロバイダの詳細」画面が表示されます。

  1. 「メタデータをダウンロード」をクリック
  2. → GoogleIDPMetadata.xml がダウンロードされます
    このファイルは Phase 3 で Cognito にアップロードするので、大切に保管してください。
  3. 「続行」をクリック

💡 この XML の中身
このファイルには、以下の3つの情報がすべて含まれています。

情報 説明
Entity ID Google の IdP としての識別子
SSO URL Google のログインエンドポイント
X.509 証明書 SAML レスポンスの署名を検証するための証明書

Cognito にこの XML をアップロードすると、3つとも自動的に登録されます。

Step 2-3: サービスプロバイダ（Cognito）の情報を入力する

「サービスプロバイダの詳細」画面で、Cognito の情報を入力します。

項目 入力する値
ACS URL https://<Cognitoドメイン>/saml2/idpresponse
エンティティ ID urn:amazon:cognito:sp:<User Pool ID>
開始 URL 空欄
Name ID フォーマット EMAIL
Name ID Primary email

具体例：

ACS URL:       https://myapp-auth.auth.ap-northeast-1.amazoncognito.com/saml2/idpresponse
エンティティ ID: urn:amazon:cognito:sp:ap-northeast-1_????

⚠️ ここが一番ミスしやすい箇所です

  • ACS URL の1文字でも違うと SAML 認証が失敗します
  • Entity ID の User Pool ID は Phase 1 で控えた値を正確にコピーしてください
  • 末尾のスラッシュ（/）を余計に入れないでください

「続行」をクリック。

Step 2-4: 属性マッピングを設定する

「属性のマッピング」画面で「マッピングを追加」をクリックし、以下の3つを設定します。

Google Directory の属性 アプリの属性（手入力）
Primary email email
First name firstName
Last name lastName

設定したら「完了」をクリック。

Step 2-5: SAML アプリを有効化する

作成されたアプリは**デフォルトで無効（OFF）**です。有効にしないとログインできません。

  1. 作成したアプリをクリック
  2. 「ユーザー アクセス」を開く
  3. 「全員に対してオン」に変更
  4. 「保存」をクリック

💡 反映について
GWS の変更は反映まで数分かかる場合があります。すぐにテストして失敗した場合は、少し待ってから再試行してみてください。

Phase 3: Cognito に SAML IdP を登録する

この Phase でやること

Phase 2 でダウンロードした GoogleIDPMetadata.xml を Cognito にアップロードし、GWS を IdP として登録します。

手順

  1. AWS コンソール > Cognito > 作成した User Pool を開く
  2. 「サインインエクスペリエンス」タブをクリック
  3. 「フェデレーテッド ID プロバイダーのサインイン」→「ID プロバイダーを追加」
  4. 「SAML」を選択

以下を入力します。

項目 入力する値
プロバイダー名 任意（例：GoogleWorkspace）
メタデータドキュメント 「ファイルをアップロード」→ GoogleIDPMetadata.xml を選択

属性マッピングを設定する

同じ画面の下部で属性マッピングを設定します。

SAML 属性（手入力） ユーザープール属性（ドロップダウン）
email email
firstName given_name
lastName family_name

⚠️ 注意
ここで入力する SAML 属性名は、Phase 2 の Step 2-4 で GWS 側に設定した「アプリの属性」と完全に一致している必要があります。

「ID プロバイダーを追加」をクリックして完了です。

Phase 4: アプリクライアントに IdP を紐づける

Phase 3 で登録した IdP を、アプリクライアントに紐づけます。これをしないと、ログイン画面に Google のオプションが表示されません。

手順

  1. User Pool の「アプリケーションの統合」タブ
  2. アプリクライアントをクリック
  3. 「ログインページ」または「ホストされた UI」セクションの「編集」をクリック
  4. 以下を設定：
項目 設定値
ID プロバイダー GoogleWorkspace にチェック
OAuth 2.0 許可タイプ 認証コード付与（Authorization code grant）
OpenID Connect スコープ openid, email, profile
  1. 「変更を保存」をクリック

Phase 5: 動作確認

テストログインの手順

  1. User Pool >「アプリケーションの統合」> アプリクライアント
  2. 「ホストされた UI を表示」をクリック
  3. ブラウザに Cognito のログイン画面が表示される
  4. Google Workspace のサインインボタンをクリック
  5. GWS アカウントでログイン

成功の判定

コールバック URL にリダイレクトされ、URL に ?code=XXXXXXXX が含まれていれば成功です。

https://localhost:3000/auth/callback?code=be7489c9-ac60-4473-ac97-f74ebf26d431

localhost なのでページ自体は表示されませんが、URL バーに code= があれば SAML 連携は正常に動いています。

よくあるエラーと対処法

症状 原因 対処
Google ログイン画面が表示されない IdP がアプリクライアントに紐づいていない Phase 4 を再確認
Google ログイン後にエラー ACS URL または Entity ID の不一致 GWS 側の SAML アプリ設定を確認。1文字のずれでも失敗する
not_a_saml_app エラー GWS 側のアプリが無効 GWS で対象アプリが「オン」になっているか確認
属性が空になる 属性マッピングの名前不一致 GWS 側（Step 2-4）と Cognito 側（Phase 3）の属性名を照合

バックエンド連携用の情報まとめ

動作確認まで完了したら、バックエンドチームに以下の情報を渡します。

コンソールから確認が必要な値

項目 確認場所
User Pool ID Cognito > User Pool > 概要画面
App Client ID アプリケーションの統合 > アプリクライアント
App Client Secret 同上（「シークレットを表示」をクリック）

User Pool ID から自動的に決まる値

以下は User Pool ID とドメインから機械的に組み立てられます。

Issuer URL:
  https://cognito-idp.<リージョン>.amazonaws.com/<User Pool ID>

JWKS エンドポイント:
  https://cognito-idp.<リージョン>.amazonaws.com/<User Pool ID>/.well-known/jwks.json

トークンエンドポイント:
  https://<Cognitoドメイン>/oauth2/token

認可エンドポイント:
  https://<Cognitoドメイン>/oauth2/authorize

GWS 側とCognito 側の設定値の関係

最後に、両者の設定がどう対応しているかを整理します。

Cognito → GWS に渡した値

値 GWS 側の設定場所
urn:amazon:cognito:sp:<UserPoolID> SAML アプリ > エンティティ ID
https://<ドメイン>/saml2/idpresponse SAML アプリ > ACS URL

GWS → Cognito に渡した値

値 渡し方
Entity ID（Google 側） GoogleIDPMetadata.xml に含まれている
SSO URL 同上
X.509 証明書 同上

XML をアップロードすることで3つとも自動登録されるため、個別に入力する必要はありません。

属性マッピングの対応

GWS 側（Step 2-4） Cognito 側（Phase 3）
Primary email → email email → email
First name → firstName firstName → given_name
Last name → lastName lastName → family_name

両方の「真ん中の値」（email, firstName, lastName）が一致していることが重要です。

おわりに

やってみると、Cognito と GWS の設定自体はそこまで複雑ではありません。ただしお互いの値を正確に登録し合う必要があるため、コピペミスが命取りになります。

この記事が、同じように「SAML って何？」から始まった方の参考になれば幸いです。

参考資料

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?