#author("2021-09-09T05:40:20+09:00","","")
[[FrontPage]]
&size(24){APIユーザートークン認証ガイド(暫定ドキュメント)};
- (※var)の項目は、設定による可変~
#contents
* ユーザートークン認証 [#c34fba60]
IMD食品栄養データAPIの使用に際し、アクセス元IPアドレスによる認証を使用できない場合、アクセストークンによる認証を実装する必要がある。（スマホアプリ等から直接APIにアクセスを行う場合等）~
API使用者は適切に、ユーザーアカウントを管理し、アプリ等使用者にトークンを配布し、またAPIサーバーからのトークン問合せに応答する必要がある。
図(暫定)
+-------------+ +-------------+
|トークン管理 |<---- トークン問合せ ---- | APIサーバー |
| サーバー |----- トークン応答 ---> | |
+-------------+ +-------------+
| A |
| | |
| +------------+ | |
+---- トークン --> |クライアント| ---- トークン -+ |
| | <--- 食品データ -+
+------------+
** API使用者によるトークンの管理 [#p25a5922]
API使用者は、ユーザー毎に、APIにアクセスするために必要なトークンを振り出し、管理しなければならない。~
*** クライアントへのトークン配布 [#x80b0f25]
トークンは、外部に漏洩しない適切な方法で、トークンをクライアントに配布しなければならない。~
*** トークン問合せサーバーの実装 [#k777d465]
API使用者は、APIサーバーからトークンの使用可否についての問合せを受け付け、適切に応答しなければならない。~
** クライアントのトークン送出 [#bbb25254]
スマホアプリ等、APIにアクセスを行うクライアントは、APIへりアクセス時に Authorization ヘッダーを用いてトークンを送出しなければならない。~
* 仕様 [#q6b810a4]
** トークンの仕様 [#z26c0771]
トークンは以下の仕様を遵守すること。
- 半角英数及び記号-(マイナス)_(アンダースコア).(ピリオド)で構成される文字列であること
- 文字列の長さは、64文字以上4096文字以下であること
- 文字種が6以上であること
** トークンの送出 [#q9e726e8]
クライアントは全てのアクセスに際して、HTTPリクエストヘッダーに以下の通りアクセストークンを送出する。
Authorization: Bearer (アクセストークン)
Authorizationヘッダーは、typeをBearerとし、credentialsにアクセストークン文字列を指定する。
アクセストークンによる認証が成功した場合、APIサーバーはHTTPレスポンスコード200を返却する。レスポンスヘッダーに X-MobadaiApi-Authenticated が含まれ、値は true となる。&br;
アクセストークンによる認証に失敗した場合、APIサーバーはHTTPレスポンスコード401を返却する。レスポンスヘッダーに X-MobadaiApi-Authenticated は含まれない。
** トークン問合せサーバーの仕様 [#ie868129]
APIサーバーへのアクセスにおいて送出されたトークンが新規トークンであった場合、API使用者の用意するトークン問合せサーバーに対してトークンの使用可否を問い合わせる。~
トークン問合せサーバーは、HTTPを用いる。サーバーはTLS1.2以上を採用したhttpsでなければならない。~
トークン問合せはGETメソッドを使用する。問合せ先のURLは、API使用者により任意に設定される（※各提供先向けのページ https://nmmq.mobidy.jp/utils/economyapi/ でAPI使用者が任意に設定）。~
*** トークン問合せクエリー [#ie868129]
問い合わせ先URLに対して以下のクエリーを付加してアクセスを実行する。
認証ハッシュは、連携設定で「トークン検証時認証ハッシュ送出」がオンの時、sha1( アクセストークン+認証キー ) の値をセットする。
|変数名|内容|必須|h
|access_token|アクセストークン|必ず付加|
|authid|提供先ID|設定により|
|authkey|認証ハッシュ|設定により|
クエリ例
https://auth.yourdomain.jp/verify?access_token=dwsQJUuB86uxgTeacx5DsL8VZkQbHuCuhuoUhPbMLHZMJtK9Ey95fp55YTFWWP
uacn8DBme2s3blpF1X8GN6P6gi0xZlqaUVHxPGJhZUqLUknUQUJawzwzAn&authid=yourid&authkey=8a0e890c4d45a0d91da72c3b0e8e0189adc9e081
*** トークン有効時のレスポンス [#xe9baad2]
- レスポンスコード
レスポンスコード200を返す。
- レスポンスボディ
トークンの残り有効期間(秒)を表す expires_in を含むJSONを返す。~
例:
{ "expires_in":86400 }
トークンが有効である場合、有効期間は最大24時間(※var)とし、これ以上の値が設定された場合は、24時間に設定される。~
トークンが有効期間を過ぎた場合、APIサーバーに於いて使用を拒否され、また当該トークンは以後24時間(※var)再使用が拒否される。~
*** トークン無効時のレスポンス [#i2725944]
- レスポンスコード
レスポンスコード400を返す。
- レスポンスボディ
規定なし
トークンが無効である場合、レスポンスが行われた後24時間(※var)、当該のトークンはAPIサーバーに於いて使用を拒否される。~
** トークン問合せのレート制限 [#ece0f790]
トークン問合せは、1時間あたり10000回(※var)までに制限される。制限を超えた場合、トークン問合せは行われず使用は拒否される。
** APIアクセスのレート制限 [#ef875cd8]
トークンを使用したAPIへのアクセスは、1時間あたり500回(※var)までに制限され、かつ、短時間に多数のクエリーを受け付けないように抑制される。レート制限が発動した時は、当該のトークンはAPIサーバーに於いて使用を拒否される。~
![[PukiWiki]](image/pukiwiki.png "[PukiWiki]")
