KMIoT API — Cognito 対応・単独運用

現場データを “安全・最短” で扱うための API 群

Amazon Cognito で認証し、一般ユーザでもすぐに安全に利用開始。センサ・グラフ・画像・アラートを一気通貫に提供します。

Security Model

認証とセッションの考え方（Cognito）

Amazon Cognito User Pool と Hosted UI を利用し、OAuth2 Authorization Code Flow + PKCE で access token (JWT) を取得します。API は受け取った JWT を検証します。

SPA（フロント→APIを直接／Bearerヘッダ）：Cookie を認証に使わないため、API 側の CSRF トークンは不要。
BFF（ブラウザ→BFF は Cookie セッション／BFF→API はトークン）：ブラウザ→BFFの書き込み系は CSRF 対策が必須（SameSite 設定＋二重送信トークンやOrigin/Referer チェック）。

※ OAuth リダイレクトの state（必須）と nonce は、ログイン要求のなりすまし防止の仕組みであり、API の CSRF トークンとは別物です。

Cognito User Pool Hosted UI OAuth2 Code Flow

認証フロー（簡略）

ログイン：ユーザは Hosted UI（/oauth2/authorize）へ遷移し認証・同意
トークン交換：リダイレクトで得た code を /oauth2/token に POST（client_id/secret または PKCE）
API 呼び出し：Authorization: Bearer <access_token> を付与
更新/ログアウト：refresh token で再発行／アプリ側でセッション終了

API Surface

主要エンドポイント（抜粋）

Sensors

GET /v2/sensorinfo/th（温湿度）／/door（ドア）／/jinkan（人感）

Graph

POST /v2/graphdata：期間・センサID配列でポイント列（chart 用）と行テキストを返却

Images

POST /v2/imagedata_session（テスト用：署名 Cookie 発行）／GET /v2/imagedata/{deviceid}/zip（範囲 ZIP）

Alert

POST /v2/alertsetting：1台／全台のアラート更新（discriminator: sensorkind）

Security

全体として Bearer(JWT) を要求。SPA（PKCE + Authorization ヘッダ）では CSRF トークン不要。BFF（Cookie セッション）の場合は 書き込み系に CSRF 必須（二重送信トークン＋Origin/Referer チェック＋SameSite 設定）。

※ 認証は Cognito に統一。旧 /v2/login 等は不要です。詳細仕様は Swagger（OpenAPI 3.0.3）をご参照ください。

Web（Hosted UI）→ API 呼び出し

# 1) ユーザを Cognito Hosted UI にリダイレクト
GET https://<domain>.auth.<region>.amazoncognito.com/oauth2/authorize?&n
  response_type=code&client_id=<CLIENT_ID>&n
  redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&scope=openid+email+profile

# 2) code を受け取りトークン交換（バックエンド）
curl -sS -X POST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -u '<CLIENT_ID>:<CLIENT_SECRET>' \
  -d 'grant_type=authorization_code' \
  -d 'code=<CODE_FROM_CALLBACK>' \
  -d 'redirect_uri=https://app.example.com/callback' \
  https://<domain>.auth.<region>.amazoncognito.com/oauth2/token | jq
# => access_token, refresh_token を取得

# 3) API 呼び出し（温湿度一覧）
ACCESS=<access_token>
curl -sS https://<host>/v2/sensorinfo/th \
  -H "Authorization: Bearer ${ACCESS}" | jq

curl 例：グラフデータ / 画像 ZIP

# 4) グラフデータ取得（期間 [ms] とセンサID配列）
curl -sS https://<host>/v2/graphdata \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${ACCESS}" \
  --data '{
    "from": 1755584741000,
    "to":   1755671125000,
    "sensors": [{"sensorId":"20100479a"}]
  }' | jq

# 5) 画像の ZIP ダウンロード（JST ファイル名判定／mode で上限動作）
curl -sS -D - \
  "https://<host>/v2/imagedata/C0001002/zip?&n
  from=2025-08-20T00:00:00Z&to=2025-08-21T00:00:00Z&mode=truncate" \
  -H "Authorization: Bearer ${ACCESS}" -o images-20250820.zip

FAQ

よくあるご質問

Q. Cognito 連携は可能ですか？

A. はい。User Pool + Hosted UI による OAuth2 Code Flow（PKCE）を標準サポートしています。

Q. CSRF は必要ですか？

ケースにより異なります。

SPA（PKCE + Bearer ヘッダ）→ API 直叩き：不要（Cookie を認証に使わないため）。
BFF（ブラウザ→BFF は Cookie セッション）：必須。特に 書き込み系エンドポイントでは 二重送信トークン（例：Cookie＋ヘッダ）や Origin/Referer チェック、SameSite（Lax/Strict）を組み合わせます。

CORS は CSRF の代替になりません（同一サイトからの悪用は防げないため）。

Q. 画像はどうやって配布？

A. 署名 Cookie または ZIP ストリームで配布します。