Cognitoユーザーの状態遷移は「作り方」で決まる:AdminCreateUserとSignUpの2レーン
目次
本記事では、Amazon Cognito のユーザーが「誰がどう作ったか」で開始ステータス(FORCE_CHANGE_PASSWORD / UNCONFIRMED)が決まり、以後たどる状態遷移のレーンがまったく別物になることを、公式ドキュメントと AWS CLI の実機検証で解説します。「初回ログイン時に強制的にパスワードを変更させたい」という要件を例に、ユーザー作成方式の選択が実装前に決めるべき設計判断であることを示します。
はじめに
こんにちは、クラウドビルダーズのhashimotoです。
Cognito の実装を進める中で、管理者作成(AdminCreateUser や Terraform の aws_cognito_user)と、フロントエンドからの自己サインアップ(SignUp)では、ユーザーの開始ステータスや初回ログインのフローが大きく異なることに気付きました。見た目はどちらも「ユーザーを作成する」だけですが、内部では別の状態遷移をたどります。本記事では、この2つのレーンの違いを整理し、「どちらのレーンでユーザーを作るか」が実装前に決めるべき設計判断であることを、実機検証を交えて解説します。
この記事の要約
- Cognito のユーザーは作成方式で開始ステータスが決まる。管理者作成(
AdminCreateUser)はFORCE_CHANGE_PASSWORD始まり、自己サインアップ(SignUp)はUNCONFIRMED始まり。 - この2レーンは通常のフローでは互いに遷移しない。
SignUpで作ったユーザーをCONFIRMEDにしてもFORCE_CHANGE_PASSWORDにはならず、途中でレーンを乗り換えることはできない。 - したがって「どちらのレーンでユーザーを作るか」は、初回ログイン体験の要件から逆算して実装前に決めるべき設計判断である。
1. CognitoのUserStatusを公式ドキュメントで整理する
2つのレーンの違いを理解する鍵が、ユーザーの状態(UserStatus)です。公式の UserType API リファレンス では、UserStatus は次の値を取ると定義されています。本記事で中心になるのは表の上3つです。
| UserStatus | 意味(公式の説明) |
|---|---|
UNCONFIRMED | ユーザーは作成されたが、確認されていない |
CONFIRMED | ユーザーが確認された |
FORCE_CHANGE_PASSWORD | ユーザーは確認済みで、一時パスワードでサインインできるが、初回サインイン時に他の操作の前にパスワードを新しい値に変更する必要がある |
RESET_REQUIRED | 確認済みだが、サインイン前にコードを要求しパスワードをリセットする必要がある |
EXTERNAL_PROVIDER | サードパーティ IdP でサインインしたユーザー |
(ARCHIVED / UNKNOWN / COMPROMISED も列挙にありますが、公式に「現在は使われていない(no longer used)」とされています。)
ここで見落としがちなのが、FORCE_CHANGE_PASSWORD は定義上「確認済み(confirmed)」の状態であるという点です。「未確認だからパスワード変更が必要」なのではなく、「確認は済んでいるが、一時パスワードで作られたため初回に変更が必須」という状態です。つまり UNCONFIRMED とは、確認ステータスの観点からして別物です。
2. ユーザー作成方式で決まる「2レーン」
2-1. 管理者作成レーン(AdminCreateUser)
管理者側がユーザーを作る方法は複数ありますが、実はすべて同じ API に行き着きます。
- AWS コンソールの「ユーザーを作成」
- Terraform の
aws_cognito_user(temporary_password指定) - AWS CLI の
admin-create-user
これらはいずれも内部的に AdminCreateUser 方式で、同じレーンに乗ります。本記事の実機検証では CLI と Terraform の経路で FORCE_CHANGE_PASSWORD 始まりを確認しています(コンソールの「ユーザーを作成」も同じ API を呼ぶ方式です)。流れは次のとおりです。
- 一時パスワード付きでユーザーが作成され、
FORCE_CHANGE_PASSWORDで開始 - ユーザーが一時パスワードで初回サインイン
- 新しいパスワードの設定を要求される(パスワード変更チャレンジ)
- 新パスワードを設定すると
CONFIRMEDに遷移
2-2. 自己サインアップレーン(SignUp)
一方、フロントエンドのサインアップ画面からユーザー自身が登録する場合は SignUp API が使われ、別のレーンに乗ります。
- ユーザー自身がパスワードを決めて登録し、
UNCONFIRMEDで開始 - 確認コード(メール・SMS)の入力、または管理者による
AdminConfirmSignUpでCONFIRMEDに遷移
2-3. 2つのレーンは交わらない
重要なのは、この2レーンが通常のフローでは互いに遷移しないことです。
SignUpで作ったユーザーをCONFIRMEDにしても、FORCE_CHANGE_PASSWORDには遷移しませんUNCONFIRMEDのままサインインを試みるとUserNotConfirmedExceptionになります(パスワード変更チャレンジが返ってくるわけではありません)FORCE_CHANGE_PASSWORDは「管理者が一時パスワードを設定したユーザー」の入口です
状態遷移を2レーン並べて描くと次のようになります。

どちらのレーンも最終的に CONFIRMED に到達しますが、そこに至る道はレーンごとに固定で、途中で乗り換えることはできません。
なお例外として、管理者が AdminSetUserPassword API で一時パスワード(Permanent: false)を設定すると、作成方式に関係なくそのユーザーは FORCE_CHANGE_PASSWORD に遷移するとされています(本記事では未検証)。ただしこれは管理者による事後的なパスワード再設定の操作であり、「どちらのレーンでユーザーを作るか」という本記事の設計判断とは別の話です。
3. AWS CLIで実機検証する
公式ドキュメントの定義を、実際に Cognito User Pool を立てて確認します。検証には、レスポンスの生の値(UserStatus や例外名)がそのまま見える AWS CLI を使います。
検証環境の前提は次のとおりです。
- 自己サインアップを有効化した User Pool(
allow_admin_create_user_only = false)。必須属性として標準属性nameを設定 - App client は secret なしのパブリッククライアント。認証フローは
ALLOW_USER_PASSWORD_AUTH(CLI 検証用)とALLOW_USER_SRP_AUTH(後半の Amplify 用)を有効化
3-1. 管理者作成 → FORCE_CHANGE_PASSWORD で始まる
admin-create-user でユーザーを作成し、直後のステータスを確認します(--message-action SUPPRESS は招待メールの送信を抑止するオプションです)。
aws cognito-idp admin-create-user --user-pool-id "$POOL" \
--username v-admin-named \
--user-attributes Name=name,Value='Named User' \
--temporary-password "$TMP_PW" --message-action SUPPRESS
aws cognito-idp admin-get-user --user-pool-id "$POOL" \
--username v-admin-named --query 'UserStatus' --output text結果は次のとおりです。
FORCE_CHANGE_PASSWORD管理者作成レーンは FORCE_CHANGE_PASSWORD で始まることが確認できます。
続けて、一時パスワードで初回サインインし、レーンの終点まで進めてみます。サインインするとパスワード変更チャレンジが返り(API のレスポンス上は ChallengeName: NEW_PASSWORD_REQUIRED という名前で返ります)、新パスワードで応答すると CONFIRMED に遷移します。
aws cognito-idp initiate-auth --client-id "$CLIENT" \
--auth-flow USER_PASSWORD_AUTH \
--auth-parameters USERNAME=v-admin-named,PASSWORD="$TMP_PW" \
--query 'ChallengeName' --output text
# => NEW_PASSWORD_REQUIRED
aws cognito-idp respond-to-auth-challenge --client-id "$CLIENT" \
--challenge-name NEW_PASSWORD_REQUIRED --session "$SESSION" \
--challenge-responses USERNAME=v-admin-named,NEW_PASSWORD="$NEW_PW"
# => AuthenticationResult(トークン)が返る = サインイン成功
aws cognito-idp admin-get-user --user-pool-id "$POOL" \
--username v-admin-named --query 'UserStatus' --output text
# => CONFIRMED$SESSIONには、initiate-authのレスポンスに含まれるSessionの値を渡します(チャレンジ応答はこのセッションと対で行います)
これで「一時パスワード発行 → FORCE_CHANGE_PASSWORD → 初回サインインで新パスワード設定 → CONFIRMED」という管理者作成レーンの一本道を確認できました。
3-2. 自己サインアップ → UNCONFIRMED で始まる
次に、同じ User Pool で sign-up(フロントエンドのサインアップ画面が呼ぶのと同じ API)を実行します。今度はユーザー自身がパスワードを決めて登録する形です(コマンド中の $PW が、ユーザー自身が決めたパスワードにあたります)。
aws cognito-idp sign-up --client-id "$CLIENT" \
--username v-selfsignup --password "$PW" \
--user-attributes Name=name,Value='Self User' \
--query 'UserConfirmed' --output text
aws cognito-idp admin-get-user --user-pool-id "$POOL" \
--username v-selfsignup --query 'UserStatus' --output text結果は次のとおりです。
False
UNCONFIRMEDsign-up のレスポンスは UserConfirmed: false、ステータスは UNCONFIRMED。こちらのレーンは UNCONFIRMED で始まることが確認できます。
3-3. UNCONFIRMED のままサインインすると UserNotConfirmedException
UNCONFIRMED のユーザーでそのままサインインを試みます。
aws cognito-idp initiate-auth --client-id "$CLIENT" \
--auth-flow USER_PASSWORD_AUTH \
--auth-parameters USERNAME=v-selfsignup,PASSWORD="$PW"結果は次のとおりです。
An error occurred (UserNotConfirmedException) when calling the
InitiateAuth operation: User is not confirmed.UserNotConfirmedException が返ります。ここがポイントで、パスワード変更チャレンジは発生しません。自己サインアップのユーザーはパスワードを自分で決めて登録しているので、「一時パスワードを新しい値に変える」という概念自体がこのレーンには存在しないためです。確認コード等で CONFIRMED にした後は、登録時に自分で決めたパスワードでそのままサインインできます。
4. 実装での着地:レーン選択は設計判断
2レーンの違いが実装に直結する例として、「初回ログイン時に強制的にパスワードを変更させたい」という要件を考えます。管理者がアカウントを払い出す業務システムなどでよくある要件です。
4-1. 自己サインアップレーンでは実現できない
前節で見たとおり、SignUp で作られたユーザーは UNCONFIRMED から始まり、確認後は登録時のパスワードでそのままサインインできます。初回パスワード変更のチャレンジ自体が発生しないため、このレーンの標準フローでは「初回強制パスワード変更」という体験は実現できません。
4-2. 実現するには管理者作成レーンに乗せる
この要件を満たすには、ユーザーを管理者作成レーン(AdminCreateUser)に乗せる必要があります。ユーザー自身に画面から登録させたい場合でも、フロントエンドから直接 SignUp を呼ぶのではなく、次のような構成にします。
フロントエンド → バックエンドAPI → AdminCreateUserバックエンド API が AdminCreateUser を呼んで一時パスワード付きでユーザーを作成すれば、ユーザーは FORCE_CHANGE_PASSWORD から始まり、初回サインインで必ずパスワード変更を求められます。
4-3. FE実装:Amplify v6での初回ログイン
管理者作成レーンの初回ログインを、フロントエンド(AWS Amplify v6)で実装する例です。signIn の戻り値の nextStep.signInStep で初回パスワード変更が要求されているかを判定し、confirmSignIn で新パスワードを送ります。
import { signIn, confirmSignIn } from 'aws-amplify/auth';
const { nextStep } = await signIn({ username, password: tempPassword });
if (nextStep.signInStep === 'CONFIRM_SIGN_IN_WITH_NEW_PASSWORD_REQUIRED') {
// 新パスワード入力画面を表示し、ユーザーの入力を受け取って送信する
const result = await confirmSignIn({ challengeResponse: newPassword });
// result.isSignedIn === true でサインイン完了(ユーザーは CONFIRMED へ)
}- 初回パスワード変更を表すステップ名は、Amplify v6 では
CONFIRM_SIGN_IN_WITH_NEW_PASSWORD_REQUIREDです(UserStatus のFORCE_CHANGE_PASSWORDとは別の文字列なので、この名前で分岐します) - Amplify の
signInは既定で SRP フローを使うため、App client の認証フローでALLOW_USER_SRP_AUTHを有効化しておく必要があります(SRP フローでも同じく初回パスワード変更ステップが返ることは実機で確認済みです) - User Pool に必須属性があり、かつユーザー作成時に未設定の場合は、
confirmSignInのoptions.userAttributesで属性も一緒に渡す必要があります
さいごに
- Cognito のユーザーは「誰がどう作ったか」で開始ステータスが決まり、以後の状態遷移のレーンが固定されます。管理者作成(
AdminCreateUser)はFORCE_CHANGE_PASSWORD始まり、自己サインアップ(SignUp)はUNCONFIRMED始まりで、通常のフローでは両者は互いに遷移しません。 - 「初回ログイン時に強制的にパスワードを変更させたい」のような初回ログイン体験の要件は、レーン選択そのものです。あとからレーンを乗り換えることはできないため、要件から逆算してユーザー作成方式を決めることが、Cognito 導入時の設計判断になります。
- 本記事の状態遷移とステータスの定義は、公式の UserType API リファレンスの記述を AWS CLI の実機検証で裏取りしたものです。