- バグの正体:JSONキーが1つ足りなかった
- 1人のユーザーに、4つの「username」
- ユーザー名属性とエイリアス属性
- どちらのモードを選ぶべきか
- ログイン識別子、ハンドル名、アイデンティティは別物
- まとめ
小さなソーシャルアプリであるStrobeを、モノリシックなPythonバックエンドからAWS Lambda、API Gateway、Cognito、DynamoDBへ移行している途中で、ログインのバグに遭遇しました。正しい認証情報を送っても401 Unauthorisedが返り、投稿、コメント、いいね、アップロード、フィードと、認証が必要な機能のほぼすべてがそのせいで動かなくなっていました。
修正は1行で済みました。ただ、その修正がなぜ安全なのかを理解するには時間がかかりました。同じシステムの中で「username」という言葉が4つの異なるものを指していたからです。この記事ではそれを解きほぐし、その奥にあるCognitoの設計上の選択、ユーザー名属性とエイリアス属性について見ていきます。
バグの正体:JSONキーが1つ足りなかった
ベアラートークンが必要な機能が、すべて同時に失敗していました。互いに関係のない不具合がたくさん起きているように見えましたが、実はどれも上流にある1つの依存先、つまりログインを共有していました。関係なさそうな機能が一斉に壊れたときは、1つずつデバッグする前に、それらが共有している依存先を探すべきです。
クライアントのログインリクエストには、emailキーが含まれていませんでした。
POST /v1/auth/register {"username": "...", "email": "...", "password": "..."}
POST /v1/auth/login {"username": "...", "password": "..."} ← no "email" key
ところが、Lambdaのlogin()ハンドラーはemailしか読んでいませんでした。
# before
email = (payload.get("email") or "").strip()
if not email or not password:
raise unauthorised_error("Invalid email or password")
payload.get("email")はNoneを返すのでemailは""になり、ハンドラーは最初のチェックの時点で401を返していました。DynamoDBにもCognitoにも一度も到達していなかったので、メールアドレスの確認や結果整合性にまつわるもっともらしい仮説は、どれも関係がありませんでした。決め手になったのは、APIドキュメントではなく実際のリクエストボディを読んだことです。
# after
email = (payload.get("email") or payload.get("username") or "").strip()

このフォールバックが安全なのは、元のアプリの仕様として、登録時に必ずusername = emailが設定され、両方のキーに同じ文字列が入るからにすぎません。もしユーザーがメールアドレスとは別のハンドル名を選べるのであれば、この修正は誤りです。その場合は、値をまずメールアドレスとして検索し、次にユーザー名として検索する必要があります。
1人のユーザーに、4つの「username」
ややこしいのは、1つの言葉が4つの異なるものを指していることです。

| # | 何か | 値の例 | ある場所 |
|---|---|---|---|
| ① | リクエストボディのJSONキー | "username": "alex@example.com" | HTTPリクエスト |
| ② | アプリ独自の属性 | alex@example.com(常にemailと同じ) | DynamoDBの行、APIレスポンス |
| ③ | CognitoのUsername。ユーザープール内の変更できない内部キー | 7f3c9e10-…(UUID) | Cognitoのユーザーオブジェクト。DynamoDBにはcognitoUsernameとしてコピー |
| ④ | InitiateAuthの**AuthParameters.USERNAME** | ③、またはメールアドレスなどの検証済みエイリアス | 認証の呼び出し |
このほかにsubもあります。これはCognitoが生成する、別の変更できないUUIDです。ユーザー名ではありませんが、StrobeのDynamoDBのパーティションキーであり、トークンに含まれるアイデンティティでもあります。
バグは完全に①の中にありました。この記事の残りでは③と④を説明し、なぜStrobeが覚えておかなければならないUUIDを必要とするのかを見ていきます。
ユーザー名属性とエイリアス属性
Cognitoには「メールアドレスでサインインする」方法が2つあります。どちらを使うかはユーザープールの作成時に選び、後から変更することはできません。
- ユーザー名属性(
UsernameAttributes = ["email"])。メールアドレスそのものがサインイン名になります。SignUpにメールアドレスを渡すと、Cognitoは本当のUsernameを、subと同じ値のUUIDに設定します。コンソールではEmailにチェックを入れ、User nameにはチェックを入れません。 - エイリアス属性(
AliasAttributes = ["email"])。どのユーザーにも本当のUsernameがあり、メールアドレスはそれを指す追加のハンドルです。コンソールではUser nameに加えてEmailにもチェックを入れます。
ユーザーオブジェクトは、どちらのモードでもほとんど同じに見えます。見分けるには、aws cognito-idp describe-user-poolがUsernameAttributesとAliasAttributesのどちらを返すかを確認するか、Usernameとsubを比べます。ユーザー名属性モードでは、この2つは同じUUIDです。

エイリアス方式がStrobeに課すコスト
Strobeのユーザープールはエイリアス属性を使っています。この1つの選択で、コードにある3つのことが説明できます。
1. ユーザー名をメールアドレスの形にできないので、アプリがUUIDを生成する。 エイリアス方式のユーザープールでは、Cognitoはメールアドレス形式のUsernameをすべて拒否します。そうしないと、ある文字列がユーザーXのUsernameであり、同時にユーザーYのメールエイリアスでもある、という状態が起こりえて、ログインが曖昧になるからです。そこでStrobeは、ランダムなUUIDでサインアップし、メールアドレスを属性として付け加えます。
cognito_username = str(uuid.uuid4())
signup_resp = cognito.sign_up(
ClientId=APP_CLIENT_ID,
Username=cognito_username,
Password=password,
SecretHash=_secret_hash(cognito_username),
UserAttributes=[{"Name": "email", "Value": email}],
)
sub = signup_resp["UserSub"] # immutable identity -> DynamoDB partition key
このUUIDはほかのどこにも記録されないので、アプリはそれをcognitoUsernameとして保存し、グループへの追加や削除など、後から呼び出す管理用APIで使います。
2. エイリアスは検証済みになって初めて機能する。 Strobeには確認コードを受け付けるエンドポイントがないため、ユーザーの確認はサーバー側で行います。ところがAdminConfirmSignUpが変えるのはユーザーのステータスをCONFIRMEDにすることだけで、email属性を検証済みにはしません。それには2回目の呼び出しが必要です。
cognito.admin_confirm_sign_up(UserPoolId=USER_POOL_ID, Username=cognito_username)
cognito.admin_update_user_attributes(
UserPoolId=USER_POOL_ID,
Username=cognito_username,
UserAttributes=[{"Name": "email_verified", "Value": "true"}],
)
どちらの呼び出しもUUIDを使う必要があります。2回目が終わるまで、メールアドレスはエイリアスになっておらず、誰も特定できないからです。
3. サインアップの時点ではメールアドレスの一意性が保証されない。 ユーザー名属性モードでは、サインアップ時にメールアドレスが重複しているとUsernameExistsExceptionが発生します。エイリアスモードでは、重複したメールアドレスでもサインアップできてしまい、Cognitoがその衝突を解決するのは検証のときです。そのとき、使うAPIによっては、エイリアスが新しいほうのアカウントに移ることがあります。すると、エイリアスのインデックスを使って「メールアドレス → ユーザー」を解決すると、間違ったアイデンティティにたどり着くおそれがあります。そこでStrobeは、一意性を自前のテーブルで担保し、メールアドレスで行を検索して、正確なUUIDで認証しています。
matched_user = _find_user_by_email(email) # DynamoDB, not Cognito's alias index
if matched_user is None or "cognitoUsername" not in matched_user:
raise unauthorised_error("Invalid email or password")
tokens = _authenticate(matched_user["cognitoUsername"], password)
これはAWS自身のガイダンスとも一致しています。ユーザープールでエイリアスを使う場合は、サインイン用の属性ではなく、subでユーザーを識別すべきだということです。
どちらのモードを選ぶべきか
| ユーザー名属性を選ぶのは… | エイリアス属性を選ぶのは… |
|---|---|
| B2B、SaaS、社内ツールの多くのように、メールアドレス(または電話番号)そのものがアカウントであるとき | ソーシャルアプリ、フォーラム、ゲームのようにユーザーがハンドル名を持ち、それでサインインすることもあるとき |
| サインイン用の識別子を1つにして、アプリ側の管理を減らしたいとき | すでにユーザー名を持っていて、それを引き続き使えるようにする必要があるユーザーを移行するとき |
| サインアップ時に重複したメールアドレスをCognitoに拒否させたいとき | ユーザーが変更できるハンドル名を使いたいとき。本当のUsernameは固定したまま、preferred_usernameをエイリアスとして追加する |
| ユーザーがメールアドレスを検証する前にサインインできてもよいとき | メールアドレスでのサインインの前に検証を必須にするのが、フローに合っているとき |
ユーザーが入力する識別子がメールアドレスだけのStrobeには、ユーザー名属性のほうがシンプルで合っていたはずです。保存すべきUUIDもなく、追加の検証の呼び出しも要らず、メールアドレスの一意性もCognitoが担保してくれます。エイリアス方式が間違いだったわけではありませんが、ユーザーが気づくことのない手間を増やしていました。
ログイン識別子、ハンドル名、アイデンティティは別物
Strobeは、元のAPIの仕様を守るためにusername = emailのままにしています。移行としては妥当ですが、設計としては弱いものです。
- メールアドレスが漏れる。 StrobeのAPIは投稿やコメントに
author.usernameを返し、ユーザー検索もこの値で照合します。そのため、すべての投稿者のメールアドレスが公開され、検索もできてしまいます。 - 3つの役割が1つのフィールドにまとめられている。 ログイン識別子(非公開で、変わることがある)、公開ハンドル名(誰にでも見え、ユーザーが選ぶ)、内部のアイデンティティ(変わらない)は、それぞれ要件が異なります。1つのフィールドで3つすべてを満たすことはできません。
- 重複したフィールドはずれていく。 常に同じ値でなければならない2つのフィールドは、まさに今回のようなバグを招きます。システムのある部分は
emailを読み、別の部分はusernameを送る、というものです。
もっときれいなモデルでは、役割を分けます。アイデンティティはsubで、すべての外部キーと認可のチェックに使います。ログイン識別子はメールアドレスで、できればユーザー名属性を使います。表示名は別の任意のハンドル名で、メールアドレスにはせず、ユーザーがそれでログインしたい場合に限って、サインイン識別子(エイリアスとしてのpreferred_username)にします。
同じことはサインインフォームにも当てはまります。入力欄に「メールアドレスまたはユーザー名」と書くなら、バックエンドは本当に両方を受け付けなければなりません。2回検索するか、単一のidentifierフィールドにするかであって、値が同じ間しか機能しないフィールド名のエイリアスではいけません。
まとめ
- 仮説を立てる前に、実際のリクエストの中身を読む。バグはJSONキーが1つ足りないことであって、Cognitoの問題ではありませんでした。
- ものごとを正確に名づける。「username」は、JSONキー、アプリの属性、Cognitoの内部キー、認証パラメータを意味していました。混乱のほとんどは、コードではなく言葉から生まれていました。
- Cognitoのサインイン方式は意図して選ぶ。後から変更できず、エイリアス方式には、メールアドレス形式の禁止、検証という関門、弱い一意性がついてきます。
- ユーザーは
subで識別し、ログイン識別子は非公開にし、メールアドレスを公開のハンドル名として使わない。