Amazon Cognito と OAuth 2.0

01OAuth 2.0 の登場人物と Cognito

OAuth 2.0（RFC 6749）は、ユーザーの代わりにアプリケーションが API を呼ぶための認可（authorization）の枠組みである。登場人物は 4 つに固定されている。OpenID Connect（OIDC）はその上に「誰がログインしたか」を伝える認証（authentication）の層を足した規格で、ID トークンという成果物を追加する。

Resource Owner

リソースの持ち主。通常はエンドユーザー

Client

ユーザーの代わりに API を呼ぶアプリケーション。Web アプリ、SPA、モバイルアプリ、バッチなど

Authorization Server

ユーザーを認証し、同意を取り、トークンを発行するサーバー

Resource Server

トークンを受け取って保護された API を提供するサーバー

Cognito のユーザープールは、このうち Authorization Server の役をまるごと引き受けるマネージドサービスである。ユーザーディレクトリ（ID とパスワード、属性、グループ）を内包し、OIDC 準拠のトークンを発行する。Client と Resource Server は自分で作るものであり、Cognito はそれらを「アプリクライアント」「リソースサーバー」という設定項目として登録させる。

02ユーザープールと ID プール

Cognito には性格の異なる 2 つのプールがある。OAuth の話をするときに主役になるのはユーザープール（user pool）であり、ID プール（identity pool、旧称 federated identities）は OAuth の外側で「トークンを AWS の一時認証情報に交換する」役を担う。名前が似ているため混同されやすいが、規格上の立ち位置はまったく違う。

ユーザープールだけで完結する構成は多い。自作 API を守るだけなら ID プールは不要である。ID プールが必要になるのは、ブラウザやモバイルから S3 や DynamoDB などの AWS サービスを直接呼びたいときに限られる。この場合、認可の主体はトークンのスコープではなく IAM ロールに移る（08 章）。

03認可コードフロー + PKCE

ブラウザやモバイルを持つアプリで標準となる手順が、認可コードグラント（authorization code grant）に PKCE（RFC 7636）を足したものである。Cognito ではユーザープールにドメインを設定すると、そのドメイン配下に Managed Login のサインイン画面と /oauth2/* エンドポイントが生える。以下の図で規格上の手順と Cognito の具体的な URL を対応させる。

手順の要点を規格の言葉で整理すると次のようになる。

1. Client が一時的な乱数 code_verifier を生成し、その SHA-256 ハッシュ code_challenge を作る（PKCE）
2. ブラウザを Authorization Server の認可エンドポイントへ送る。Cognito では https://{ドメイン}/oauth2/authorize。/login を直接指定すると Managed Login の画面へ直行する
3. Authorization Server がユーザーを認証する。ここが Cognito の Managed Login。ユーザープールのディレクトリで認証するか、外部 IdP に委譲する
4. 認証に成功すると、Authorization Server は短命の認可コードを redirect_uri に付けて返す。トークンそのものはブラウザの URL に載らない
5. Client はバックチャネルで /oauth2/token にコードと code_verifier を送る。Cognito は S256 ハッシュが 2 で受け取った code_challenge と一致するか確かめ、横取りされたコードでは交換できないようにする
6. Authorization Server がトークンを返す（04 章）
7. Client は Resource Server にアクセストークンを Bearer ヘッダで送る
8. Resource Server は Cognito の JWKS で署名を検証する（09 章）

043 種類のトークン

トークンエンドポイントは 3 つのトークンを返す。ID トークンとアクセストークンは JWT で、リフレッシュトークンは不透明な文字列である。ID トークンは OIDC の成果物、アクセストークンとリフレッシュトークンは OAuth 2.0 の成果物であり、目的がまったく違う。

Cognito のアクセストークンには aud クレームがなく、代わりに client_id が入る。また Cognito は ID トークンとアクセストークンを別の鍵で署名する。どちらの鍵もユーザープールの JWKS に含まれるので、検証側は kid で選べばよい（09 章）。

05グラント種別とアプリクライアント設定

OAuth 2.0 にはトークンを得る手順（grant）が複数ある。Cognito のアプリクライアントは、そのうち 3 つを設定項目として持つ。どれを許可するかは「そのクライアントがどんなアプリか」で決まる。

アプリクライアントには、グラント以外にも OAuth の規格を Cognito の設定に翻訳した項目が並ぶ。

client_id

アプリクライアント ID。トークンの aud / client_id クレームになる

client_secret

任意。機密クライアント（サーバーサイド）だけが持つ。トークンエンドポイントでは Authorization: Basic base64(client_id:client_secret) で提示する

callback URL

規格の redirect_uri の許可リスト。完全一致でしか許可されない

sign-out URL

/logout から戻す先の許可リスト

identity providers

このクライアントで使える IdP。Cognito のディレクトリ自身も「Cognito user pool」という 1 つの IdP として並ぶ

OAuth scopes

このクライアントが要求できるスコープの上限（06 章）

ID プールへの連携や外部 IdP のフェデレーションを使う場合も、入口はすべてこのアプリクライアント経由になる。1 つのユーザープールに用途の違うアプリクライアントを複数作り、それぞれにグラントとスコープを絞るのが基本形である。

06スコープとリソースサーバー

スコープ（scope）は「このアクセストークンで何ができるか」を表す文字列で、Client が認可リクエストで要求し、Authorization Server が承認してアクセストークンの scope クレームに書き込む。Cognito のスコープは 2 系統に分かれる。

OIDC 標準スコープと Cognito 予約スコープ

カスタムスコープとリソースサーバー

自作 API のためのスコープは、まず Cognito にリソースサーバーを登録して定義する。識別子（例 https://api.example.com や orders）と、その配下のスコープ名（例 read、write）を登録すると、orders/read のように識別子とスコープ名を / でつないだ文字列がカスタムスコープになる。

GET /oauth2/authorize?response_type=code
  &client_id=1example23456789
  &redirect_uri=https://app.example.com/callback
  &scope=openid+email+orders/read+orders/write
  &state=…&code_challenge=…&code_challenge_method=S256

発行されたアクセストークンの scope クレームは "openid email orders/read orders/write" のようになり、API 側はこの文字列を見て操作を許可する。API Gateway の Cognito オーソライザーはメソッドごとに必要スコープを設定でき、トークンに含まれていなければ 403 を返す。クライアントクレデンシャルグラントで得られるのはこのカスタムスコープだけである。

07フェデレーション

ユーザープールは Authorization Server であると同時に、外部 IdP（Google、Apple、Facebook、Amazon、任意の OIDC プロバイダ、SAML 2.0 プロバイダ）に対しては Client として振る舞う。つまり OAuth の手順が二段重ねになる。アプリから見える相手は常に Cognito であり、外部 IdP のトークンはアプリに渡らない。

外部 IdP を設定するときに Google などのコンソールに登録する「承認済みリダイレクト URI」は、アプリの URL ではなく https://{ユーザープールのドメイン}/oauth2/idpresponse である。内側の OAuth の Client は Cognito なので、コールバックも Cognito に返るためである。SAML の場合は /saml2/idpresponse になる。

アプリ側から特定の IdP を直接指定したいときは、認可リクエストに identity_provider=Google のようなパラメータを足す。省略すると Managed Login が IdP の選択画面を出す。

08ID プールで AWS 認証情報に交換する

ID プールは OAuth の外側にある。入力はユーザープール（または外部 IdP）の ID トークンで、出力は IAM の一時認証情報である。内部では STS の AssumeRoleWithWebIdentity が呼ばれ、どの IAM ロールを引き受けるかは ID プールのロール設定（認証済み / 未認証ロール、またはトークンのクレームに基づくロールマッピング）で決まる。

ID プールの「ログインプロバイダ」にユーザープールを登録するときは、cognito-idp.{region}.amazonaws.com/{userPoolId} という発行者名とアプリクライアント ID の組で指定する。ユーザープールを経由せず、Google などの外部 IdP のトークンを ID プールに直接渡すこともできるが、ユーザーディレクトリやグループを一元管理したいなら、ユーザープールで受けてから ID プールに渡す二段構成が扱いやすい。

09トークンの検証

Resource Server はアクセストークンを受け取るたびに検証する。Cognito の JWT は RS256 で署名されており、公開鍵はユーザープールごとの JWKS エンドポイントで配布される。検証の手順は OIDC の一般論と同じで、Cognito 固有なのは URL とクレーム名だけである。

発行者      https://cognito-idp.{region}.amazonaws.com/{userPoolId}
JWKS        {発行者}/.well-known/jwks.json
OIDC 設定   {発行者}/.well-known/openid-configuration

1. JWT ヘッダの kid に一致する鍵を JWKS から選び、署名を検証する。JWKS は鍵のローテーションに備えてキャッシュしつつ、未知の kid が来たら再取得する
2. iss が自分のユーザープールの発行者と一致することを確認する
3. exp が現在時刻より後であることを確認する
4. token_use を確認する。API なら access、アプリ内のユーザー識別なら id
5. 宛先を確認する。ID トークンは aud、アクセストークンは client_id が自分のアプリクライアント ID と一致すること
6. 必要なら scope や cognito:groups を見て認可する

API Gateway の Cognito ユーザープールオーソライザー、ALB の認証アクション、AppSync の Cognito 認可モードは、この手順を代行してくれる。自前で書く場合は aws-jwt-verify（Node.js）のような検証ライブラリを使うと、上記の手順が一通り実装されている。

10エンドポイント一覧と設計指針

ユーザープールのドメイン配下に生えるエンドポイントを、規格上の名前と並べて整理する。

以上の構造から、次の指針が導かれる。

• ブラウザやモバイルを持つアプリは認可コード + PKCE を選ぶ。インプリシットは新規では使わない
• API には必ずアクセストークンを送る。ID トークンはアプリの中で使い切る
• 自作 API の権限はリソースサーバーのカスタムスコープで表現し、API 側で scope クレームを検査する。ユーザーの所属による認可は cognito:groups で補う
• サーバー間通信はクライアントクレデンシャル専用のアプリクライアントを別に作り、カスタムスコープだけを許可する
• フロントエンドから AWS サービスを直接呼ぶときだけ ID プールを足す。そのときの認可は IAM ロールで決まるため、ロールの信頼ポリシーと権限を最小にする
• 外部 IdP を足すときは、IdP 側に登録する redirect URI が /oauth2/idpresponse であることを忘れない
• トークン寿命は既定の 1 時間 / 30 日から始め、失効を早く効かせたい API ではアクセストークンを短くしてリフレッシュに頼る
• 検証コードは JWKS をキャッシュしたオフライン検証にし、Cognito への同期呼び出しをリクエスト経路に置かない