# keenauth test login でテストユーザーをサインインさせる

`keenauth test login` は、`development` 環境のテストユーザーをサインインさせ、トークンを表示します。ログインページをクリックして操作しなくても、API を呼び出したりバックエンドをテストしたりできます。ブラウザと同じように実際のホステッドログインを経由し、開発用の固定コード `424242` を使用します（[本番以外の環境におけるテストユーザーとメッセージ](/docs/guides/test-environments) を参照してください）。

このコマンドには API キーも `keenauth login` のセッションも必要ありません。サインインするのはあなたではなく、テストユーザーだからです。

## 始める前に

- **テストユーザー。** メールアドレスのローカル部分に `+test` タグが必要です（例: `ada+test@example.com` や `ada+test_1@example.com`）。先にユーザーを作成してください（例: `keenauth users create --email ada+test@example.com`）。それ以外のアドレスは、コマンドがリクエストを送信する前に拒否し、終了コード 2 で終了します。
- **公開アプリケーション。** `--client-id` で、環境のネイティブアプリケーションまたはシングルページアプリケーションの ID を指定します。そのアプリケーションでは、メールコードによるサインイン（パスワードレスの `email_otp`）が許可されている必要があります。
- **リダイレクト URI。** 既定では、コマンドは `http://127.0.0.1:<ランダムなポート>/callback` を使用します。アプリケーションに `http://127.0.0.1/callback` を登録してください。ループバックのリダイレクト URI は任意のポートを受け付けます（RFC 8252）。このアドレスでは何も待ち受けていません。リダイレクトはコマンド自身が読み取ります。登録済みの別のリダイレクト URI を使う場合は、`--redirect-uri` を指定します。
- **環境の発行者。** `--issuer` で指定するか、`KEENAUTH_ISSUER` を設定してください（例: `https://acme-dev.keenauth.app`）。

## 使用方法

```sh
export KEENAUTH_ISSUER=https://acme-dev.keenauth.app
keenauth test login --user ada+test@example.com --client-id app_01j9z3k4m5n6p7q8r9s0t1v2w3
```

| フラグ | 説明 |
|---|---|
| `--user` | テストユーザーのメールアドレス（必須）。 |
| `--client-id` | 環境の公開アプリケーションの ID（必須）。 |
| `--issuer` | 環境の発行者 URL。デフォルト: 環境変数 `KEENAUTH_ISSUER`。 |
| `--scope` | 要求するスコープ（スペース区切り）。デフォルト: `openid profile email`。リフレッシュトークンを受け取るには `offline_access` を追加します。 |
| `--resource` | アクセストークンの対象となる API のリソース指定子（RFC 8707）。 |
| `--redirect-uri` | アプリケーションに登録済みのリダイレクト URI。 |
| `--output`, `-o` | `json`、`yaml`、`table` のいずれか。フラグを省略すると、ターミナルでは表形式、それ以外では JSON で出力します。 |

出力には `token_type`、`access_token`、`id_token`（`openid` を要求した場合）、`refresh_token`（`offline_access` を要求した場合のみ）、`expires_in`、`scope` が含まれます。トークンはパスワードと同様に扱ってください。期限が切れるまで、テストユーザーとして機能します。コマンドはトークンを標準出力にのみ書き出し、コードを表示することは一切ありません。

```sh
ACCESS_TOKEN=$(keenauth test login --user ada+test@example.com --client-id app_01j9z3k4m5n6p7q8r9s0t1v2w3 -o json | jq -r .access_token)
curl -H "Authorization: Bearer $ACCESS_TOKEN" http://localhost:3000/api/orders
```

## コマンドの動作

1. 環境のディスカバリードキュメントを読み込み、PKCE（`S256`）、`state`、`nonce` を含む認可リクエストを開始します。
2. ホステッドログインでアドレスを入力し、メールコードを要求して、`424242` を送信します。その後、環境が第 2 要素としてメールコードを要求した場合は、そのコードを求め、再び `424242` を送信します。
3. リダイレクト URI へのリダイレクトをたどり、`state` と `iss` を検証して、認可コードをトークンエンドポイントで交換します。
4. ID トークンが、リクエストの `nonce` を使ってお使いのアプリケーション向けに発行者から発行されたことを確認し、トークンを表示します。

サインインで他の操作が必要な場合（例: パスワード、パスキー、認証アプリ、そのアドレスのドメインのエンタープライズシングルサインオン、同意画面、組織の選択）、コマンドはエラーで停止します。

## 環境

固定コードを受け付けるのは `development` 環境だけです。このコマンドは開発環境でのみ使用してください。

- `staging` では、テストアドレスに何も送信されませんが、固定コードは拒否されます（`401 invalid_credentials`）。
- `production` では、`+test` のアドレスは通常のアドレスとして扱われます。メールコードは実際にそのアドレスに送信され、固定コードは拒否されます。

サーバーがある手順を拒否した場合、CLI はサーバーの問題応答を変更せずに表示します（`error`、`code`、`status`、`detail`、`request_id`）。例: `code: test_feature_not_in_production`。

## 終了コード

| コード | 意味 |
|---|---|
| `0` | テストユーザーがサインインしました。トークンが表示されています。 |
| `1` | サインインに失敗しました。OAuth エラー、`state`・`iss`・`nonce` の不一致、またはコマンドが完了できない手順があります。 |
| `2` | 使用方法のエラーです。アドレスに `+test` タグがない、必須フラグまたは発行者がない、値が無効のいずれかです。リクエストは送信されていません。 |
| `3` | サーバーが `401` または `403` を返しました（例: `invalid_credentials`、`test_feature_not_in_production`）。 |