アプリケーション開発

IoTアクセス制御エンジンご利用の流れ

1. アカウント登録
2. API利用申請
3. 認可
4. ゲートウェイ登録
5. デバイス登録
6. デバイス操作

1. アカウント登録

実際に IoT アクセス制御エンジンにアクセスするためには、アカウント登録が必要です。アカウントの登録も API で実行することが可能ですが、ここでは UI が実装されている公式ダッシュボードで実施する手順を示します。

Webブラウザで公式ダッシュボード（https://console.dsymphony.com/）にアクセスしてください。

IoT アクセス制御エンジンへのアカウント登録の際には、以下にリストアップされている OpenID Provider を利用することができます。

Googleアカウント
dアカウント
Facebookアカウント
LINEアカウント

IoT アクセス制御エンジンは、メールアドレスや電話番号といったユーザの個人情報を保持することなく、OpenID Connect プロトコルにより外部 ID プロバイダと連携し、アカウントを作成します。

公式ダッシュボードを例にして、アカウントの登録シーケンスを説明します。

アカウント登録を開始するため、アカウントの登録 API を実行する。
指定された OpenID Provider の認証エンドポイントに対して認証リクエストを行います (メッセージ番号: 2)。本 API を呼び出すと、処理が完了するまでに複数回のリダイレクトが発生します。
例えば、公式ダッシュボードの「Google アカウントで登録」といった ID プロバイダボタンを押下すると、次のような API リクエストが行われます。
[リクエストサンプル]　※一部折り返して表示しています。

curl -sS -X POST https://dsymphony.com/management/v2/accounts \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'redirectUri=XXXX&accountType=1'

XXXX：申請時に指定したリダイレクト URIを入力してください。リダイレクト URI は完全一致の検証が行われます。
認証画面が表示され、ユーザが認証情報の入力を行う。
指定された OpenID Provider が提供する認証画面が表示され、認証を行います (メッセージ番号: 5, 6, 7)。具体的な認証方法については、各 OpenID Provider の実装や設定に依存します。認証に成功すると、リダイレクトにより認可コードがコールバックされます (メッセージ番号: 8, 9)。
ID トークンの取得、アカウント情報の登録が行われる。
OpenID Provider から得た認可コードを用いて ID トークンを取得、これに基づきアカウント情報が登録されます (メッセージ番号: 10, 11, 12)。
アカウント登録完了画面が表示される。
アカウントの登録に成功した場合、最終的に利用申請時に記載した「アカウントの登録 API のリダイレクト先 URI」にリダイレクトされます (メッセージ番号: 13, 14, 15)。

2. API利用申請

IoT アクセス制御エンジンの API 利用に際し、事務局への申請を行う必要があります。アプリケーション開発申請にアクセスし、開発者登録を行ってください。登録は無料です。

なお、申請時には以下の2つの URI を準備する必要があります。

対象となるAPI	意味	URI例
/management/v2/accounts	アカウントの登録 API のリダイレクト先 URI	https://example.jp/symphony-sdk/signup_callback.html
/oauth2/v2/authorize	IoTアクセス制御エンジン連携の認可APIのリダイレクト先 URI	https://example.jp/symphony-sdk/auth_callback.html

3. 認可 (システムへのログイン)

アカウントの登録が完了したら、API 実行に必要となるアクセストークンを取得するために IoT アクセス制御エンジン連携の認証・認可を行います。これは、一般的なシステムのログイン機能に相当するものです。

認可とは、「対象クライアント (例えば、公式ダッシュボード) が IoT アクセス制御エンジン上に存在するリソース (登録されているゲートウェイやデバイス等) にアクセスするための許可」を意味します。具体的には IoT アクセス制御エンジン API 群の実行に対する許可です。

認証は、各 OpenID Provider の認証方法に準じて「誰のリソースであるのか」を問います。認証・認可に成功した場合、アクセストークンおよびリフレッシュトークンが払い出されます。こうした一連の認可フローは OAuth 2.0 Authorization Framework に関連する RFC に準拠しています。

通常、IoT アクセス制御エンジンは、次のような認可画面を表示します。

アクセストークンは一部の API を除き、各 API 呼び出し時に付与されなければなりません。

※アクセストークンを必要としない API

アクセストークンは、API 実行時の Authorization ヘッダに以下の形式で付与します。

Bearer + 半角スペース + {アクセストークン}

例: Authorization: Bearer xxxyyyzzz...

アクセストークンおよびリフレッシュトークンには有効期限が設定されています。設定は以下の通りです。

トークン	有効期限
アクセストークン (access_token)	86400 秒 (24 時間)
リフレッシュトークン (refresh_token)	5184000 秒 (60 日)

注釈

アクセストークンには有効期限があり、期限が過ぎたアクセストークンは無効となります。

無効なアクセストークンが付与されたリクエストに対して、IoT アクセス制御エンジンはステータスコード 401 (Unauthorized) を返します。Unauthorized が返却された場合は、アクセストークンと併せて提供されるリフレッシュトークンを使用して再度アクセストークンを取得し直す必要があります。なお、IoT アクセス制御エンジンでは、アクセストークンの再取得と同時にリフレッシュトークンも新しいものに置き換えられます。

また、アクセストークンを無効化した場合はリフレッシュトークンも無効となります。無効なリフレッシュトークンではアクセストークンを再取得することができないため、IoT アクセス制御エンジン連携の認可を再度行う必要があります。なお、リフレッシュトークンはアクセストークンの再取得が行われずに一定の期間が経過した場合も自動的に無効化されます。

認可シーケンスは以下の通りです。

認可を開始するため、IoT アクセス制御エンジン連携の認可 API を実行する。
ユーザに対し、クライアントが IoT アクセス制御エンジン API を利用するための認可を求めます。クライアントとは、IoT アクセス制御エンジン API を利用するアプリケーションのことを指します。本 API は、OAuth 2.0 Authorization Code Flow に従って認可コードの取得を試みます (メッセージ番号: 2)。認可コードの取得に際し、クライアントは主にクライアント ID、スコープ、リダイレクト URI を指定します。クライアント ID は利用申請後に発行されるクライアント識別子で、スコープは IoT アクセス制御エンジン上のリソースのアクセス権限 (利用可能な API) を示します。リダイレクト URI は認可コードを受け取るための URI を意味し、利用申請時に登録した IoT アクセス制御エンジンの認可 API のリダイレクト先 URI と一致している必要があります。
例えば、公式ダッシュボードの「Google アカウントでログイン」といったログインボタンを押下すると、次のような API リクエストが行われます。
[リクエストサンプル]　※一部折り返して表示しています。

curl -sS -X GET https://dsymphony.com/oauth/v2/authorize
  ?response_type=code
  &client_id=XXXX
  &redirect_uri=XXXX
  &scope=management%20device%20archive
  &state=sNCoBl4F_MrK
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256 \
  -H 'Content-Type: application/x-www-form-urlencoded' \

XXXX：利用申請後に発行されたクライアント ID
XXXX：利用申請時に指定したリダイレクト URI
※IoT アクセス制御エンジン連携の認可 API で指定したものと同一でなければなりません。
認可画面が表示され、IoT アクセス制御エンジンへのログインを行う。
リクエストパラメータに問題がない場合、「IoT アクセス制御エンジンにおける認可画面」のような認可画面にリダイレクトされ、ユーザに認可を求めます (メッセージ番号: 3)。ユーザは、アカウント登録時に指定した OpenID Provider のボタンを押下し、IoT アクセス制御エンジンへのログインを試みます (メッセージ番号: 4)。
認可完了画面 (エンドポイント) にリダイレクトされる。
認証・認可に成功すると、「IoT アクセス制御エンジンの認可 API のリダイレクト先 URI」にリダイレクトされ、認可コードが得られます (メッセージ番号: 16, 17, 18)。
アクセストークンを取得する。
認可が完了したら、アクセストークン取得リクエスト API を実行し、アクセストークンの取得を試みます。本 API は OAuth 2.0 Authorization Code Flow に従い、認可サーバからのリダイレクト時に取得した認可コードを用いてアクセストークンおよびリフレッシュトークンと引き換えます (メッセージ番号: 19, 20)。
[リクエストサンプル]　※一部折り返して表示しています。

curl -sS -X POST https://dsymphony.com/oauth/v2/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d
  'response_type=authorization_code
  &code=SplxlOBeZQQYbYS6WxSbIA
  &client_id=XXXX
  &redirect_uri=XXXX
  &code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
  '

XXXX：利用申請後に発行されたクライアント ID
XXXX：利用申請時に指定したリダイレクト URI
※IoT アクセス制御エンジン連携の認可 API で指定したものと同一でなければなりません。

認証・認可のシステム概要は以下の通りです。

IoT アクセス制御エンジン連携の認可 API に付与するパラメータは以下の通りです。

パラメータ	必須	説明
response_type	必須	必ず code でなければなりません。
client_id	必須	利用申請後に発行されるクライアント識別子 (クライアント ID) です。
redirect_uri	必須	利用申請時に登録した IoT アクセス制御エンジン連携の認可 API のリダイレクト先 URI です。認可コードがリダイレクトによってコールバックされます。
scope	必須	要求するアクセス権限。大文字と小文字を区別する文字列で、スペース区切りのリストです。使用可能な文字列は management 、archive 、device です。
state	-	リクエストとコールバックの間で状態を維持するために使用するランダムな値です。リクエスト時に付与した値は、認可サーバからリダイレクトによってクライアントにコールバックされる際、同値が付与されます。必須パラメータではありませんが、コールバック時にクライアントにてその値を確認し、Cross-Site Request Forgery (CSRF) の可能性を軽減することが推奨されます。
code_challenge	-	Proof Key for Code Exchange (PKCE) に対応した認可リクエストには、code_challenge と code_challenge_method を使用します。 code_challenge_method で指定された変換メソッドを code_verifier に適用し、code_challenge を生成します。指定可能な変換メソッドは S256 あるいは plain のみです。 code_verifier は [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~" からなる文字列です。攻撃者の類推を困難とするためには、少なくとも 256 bit のエントロピーとすべきです。ランダムな43〜128文字で構成します。 S256: クライアントが対応している場合は、必ず S256 を使用しなければなりません。次のような計算ロジックにより URL セーフな値を生成します。 code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) plain: 平文では期待する効果が十分に得られないため、S256 が使用出来ないような制約のある環境に限定して適用してください。この場合、code_verifier は URL セーフな文字列とします。 code_challenge = code_verifier
code_challenge_method	-	code_verifier に適用する変換メソッドを指定します。S256 あるいは plain を指定します。未指定の場合、自動的にデフォルトの plain が選択されます。

注釈

code_challenge、code_challenge_method は必須パラメータではありませんが、特にクライアントがネイティブアプリである場合など、認可コードの横取り攻撃をされる可能性が高い環境においては、使用を強く推奨します。

スコープに対応する API は以下の通りです。1つ以上指定する必要があります。

スコープ	利用可能となるAPI	認可画面上での表現
management	Management API	デバイス管理
archive	Archive API	データ保存
device	Device API	デバイス操作

4. ゲートウェイ登録

実際のデバイスと IoT アクセス制御エンジンを中継する機器やソフトウェアをゲートウェイと呼びます。IoT アクセス制御エンジンからゲートウェイを操作するためには、ゲートウェイ登録を行い、ゲートウェイとユーザとを関連付ける必要があります。

公式ダッシュボードでは、「ゲートウェイ探索」から実施することが出来ます。

ゲートウェイが初めて IoT アクセス制御エンジンに接続されると、当該ゲートウェイはユーザが未割り当てな状態で一時的に IoT アクセス制御エンジン上にキャッシュされます。ゲートウェイには必ずゲートウェイを一意に識別するための UUID (ゲートウェイ識別子) が割り当てられています。ユーザは、この UUID から IoT アクセス制御エンジンに一時的に登録されているユーザが未割り当てのゲートウェイを検索します。既にユーザと紐付いているゲートウェイを検索することは出来ません。指定したゲートウェイが発見された場合、ゲートウェイ登録を行うことが出来ます。ゲートウェイ登録に成功すると、当該ゲートウェイの所有者は登録したユーザに関連付けされます。

項目	別名	説明
ゲートウェイ識別子	UUID	ゲートウェイを一意に識別するための ID です。フォーマット: UUID 形式 (UUIDv1 , UUIDv4) 例: 01234567-89ab-4cde-f012-3456789abcde

項目

別名

説明

ゲートウェイ識別子

UUID

ゲートウェイを一意に識別するための ID です。

フォーマット: UUID 形式 (UUIDv1 , UUIDv4)

例: 01234567-89ab-4cde-f012-3456789abcde

注釈

ゲートウェイの一時登録情報は、「15分間」ユーザが未割り当てな状態が続くとシステムから自動的に削除されるため、ユーザは時間内にゲートウェイ登録を行う必要があります。15分以上経過してゲートウェイの検索が出来なくなってしまった場合には、再度ゲートウェイを起動、接続し直すことで、再び未割り当てな状態に戻ります。

ゲートウェイの仮登録シーケンスは以下の通りです。

ゲートウェイの登録シーケンスは以下の通りです。

ゲートウェイの仮登録を行う。
ゲートウェイの起動時には、IoT アクセス制御エンジンとの MQTTS 接続が確立された後、UUID を含むゲートウェイ情報の送信が行われます。ユーザに関連付けられていない未割り当てのゲートウェイ情報であった場合、一時的にシステムにキャッシュされます。一連の処理はユーザ操作を伴わず、自動的に行われます。
仮登録されているゲートウェイを探索する。
ゲートウェイの検索 API は、指定した UUID に該当するゲートウェイを検索、取得するための API です。ゲートウェイの登録 API の実行時に必要となるゲートウェイ識別子 (ゲートウェイ ID) を含むゲートウェイ情報を取得出来ます (メッセージ番号: 1, 3)。既にユーザに関連付けられているゲートウェイは検索されません。
ゲートウェイを登録する。
ゲートウェイの登録 API は、指定したゲートウェイをユーザと関連付けるための API です。既にユーザに関連付けられているゲートウェイを登録することは出来ません (メッセージ番号: 4, 7)。

5. デバイス登録

ゲートウェイ登録が完了した段階では IoT アクセス制御エンジンがゲートウェイが認識しているデバイスが登録されていないため、デバイス操作等を行うことは出来ません。そのためには、デバイス登録が必要です。

公式ダッシュボードでは、「デバイス登録」から実施することが出来ます。

デバイス登録の機能には以下の2つのモードがあります。

ゲートウェイが認識している全ての未登録デバイスを一括して登録する。
ゲートウェイが認識している未登録デバイスを個別に登録する。

モード	使用方法	API実行時のデバイス名の指定
一括登録	デバイスの登録 API 実行時、gatewayId のみ指定します。	不可全てのデバイスは、ゲートウェイ (プラグイン) 側で設定されているデフォルト値で登録されます。ただし、登録後にデバイス設定の変更 API で変更することは可能です。
個別登録	デバイスの登録 API 実行時、gatewayId および thingId を指定します。	可デバイス名を指定して登録することが出来ます。

モード

使用方法

API実行時のデバイス名の指定

一括登録

デバイスの登録 API 実行時、gatewayId のみ指定します。

不可

全てのデバイスは、ゲートウェイ (プラグイン) 側で設定されているデフォルト値で登録されます。ただし、登録後にデバイス設定の変更 API で変更することは可能です。

個別登録

デバイスの登録 API 実行時、gatewayId および thingId を指定します。

可

デバイス名を指定して登録することが出来ます。

また、デバイス登録ではデバイスが提供する機能 (アクションと呼ぶ) やアーカイブ設定も併せて登録されます。

未登録デバイス一覧の取得シーケンスは以下の通りです。

デバイス登録シーケンスは以下の通りです。

未登録デバイス一覧を取得する。
まず、未登録デバイス一覧の取得 API を使用して、指定されたゲートウェイが認識しているデバイスの内、まだ IoT アクセス制御エンジンに登録されていないデバイスの一覧を取得します。デバイスの登録 API を一括登録モードで実行する場合には、本 API を実行しなくても構いません。
任意のデバイスを登録する。
デバイスの登録 API を使用して、指定されたゲートウェイが認識しているデバイスの内、まだ IoT アクセス制御エンジンに登録されていないデバイスを登録します。従前の説明の通り、一括登録モードではゲートウェイが認識している全ての未登録デバイスを一括して登録することができ、個別登録モードはゲートウェイが認識している未登録デバイスを個別に登録する場合に使用します。

デバイスが提供する機能 (アクション) の列挙については、ゲートウェイに対してサービス情報リクエストを行って、プラグインから提供される未登録デバイスのサービス情報を収集、解析することで実現しています。サービス情報リクエストのレスポンスは、Swagger 2.0 によって定義化されたデバイス Web API フォーマットに従っており、各機能 (サービス) がプロファイル単位で記述されています。

6. デバイス操作

ゲートウェイが認識しているデバイスを IoT アクセス制御エンジンに登録が完了したら、デバイス操作を行うための準備は整いました。

公式ダッシュボードでは、「利用可能サービス」から実施することが出来ます。

基本的なデバイス操作のステップは以下の通りです。

デバイス一覧から、操作対象のシング ID を取得する。
登録済みデバイス一覧の取得 API を実行し、シング ID を含むデバイス情報を取得します。シング ID はデバイス登録時に生成されるため毎回呼び出す必要はありませんが、クライアントの設定画面等でデバイス登録や操作対象とするデバイスの選択が出来ることが推奨されます。これは、同じ型番のデバイスであってもゲートウェイ (プラグイン) 側で異なるサービス ID が割り当てられる可能性があり、その場合シング ID も併せて異なる値を示すからです (例えば、デバイス故障で差し替えたり、同じ型番のデバイスを新たに追加した場合にも起こり得ます)。
アクション一覧から、実行するアクションのパラメータを取得する。
デバイスに紐づくアクション一覧の取得 API を実行し、操作対象となるデバイスのアクション情報を取得します。アクション情報にはアクション ID のほか、Device API の実行時に付与するパラメータセットも含まれます。通常、クライアントがアクション情報から動的にパラメータセットを取得することは稀ですが、公式ダッシュボードのように細かなパラメータ列挙というような機能を実現するために使用されます。

開発フェーズにおいては、プロファイル (Swagger) の定義を確認するほか、公式ダッシュボードでデバイス登録を行い、実際に各アクションの実装を確認すると良いでしょう。
アクションを実行する。
アクションに対応した Device API を実行し、デバイス操作や情報取得を行います。対象デバイスはシング ID かニックネーム、タグ名で指定します。
注釈

デバイス操作は、次の全ての条件を満たしている状態でなければ成立しません。
- ゲートウェイがデバイスを認識していること。
- ゲートウェイが IoT アクセス制御エンジンに接続されていること。
- ゲートウェイ、デバイスが IoT アクセス制御エンジンに登録されていること。

デバイス操作シーケンスは以下の通りです。

登録済みデバイス一覧を取得する。
従前の説明の通り毎回実施する必要はありませんが、ここではシング ID を得るために登録済みデバイス一覧の取得 API を実行するシーケンスを示します。
任意の Device API を実行する。
Device API とは、任意のデバイス操作や情報取得を行う API 群です。API はプロファイルに従って実行されるため、リクエストパス、メソッド、各種パラメータはその提供元であるゲートウェイやプラグインの実装に依存します。

なお、Device API はゲートウェイ ID を指定する場合と指定しない場合とでは、デバイスにリクエストが到達するまでの経路が異なる場合があります。ゲートウェイ ID を指定したケースでは、指定されたゲートウェイにのみサービス実行リクエストが送信されます。ゲートウェイ ID を指定しないケースでは、操作対象のデバイスを認識している全てのゲートウェイに対し、有効なレスポンスが得られるまで順にリクエストを繰り返します。対象となるデバイスは、登録済みデバイスの中で同様のアクション情報を持ちサービス ID が一致するデバイスです。こうした動作を経路制御と呼びます。

以下に、経路制御の動作仕様をまとめます。ここではタイムアウトとオフラインの振る舞いとを便宜上分けて説明しますが、これらが発生した場合にクライアントに返却されるエラーレスポンスは共通の result=300 (接続不良エラー) です。各種エラーコードについては「エラーコード一覧」を参照してください。

経路制御	使用方法	動作	タイムアウトとオフライン
静的	Device API 実行時、gatewayId を指定します。	指定されたゲートウェイにのみサービス実行リクエストが送信されます。	タイムアウト: ゲートウェイからのレスポンスが30秒以内に返却されなかった場合オフライン: ゲートウェイの接続状態がオフライン
動的	Device API 実行時、gatewayId を指定しません。	操作対象のデバイスを認識している全てのゲートウェイに対し、有効なレスポンスが得られるまで順にリクエストを繰り返します。繰り返しに際し、次に示す優先度に従ってサービス実行リクエストの送信先ゲートウェイが選択されます。優先度: 1. 接続状態がオンラインのゲートウェイ 2. ゲートウェイタイプが hgw であるゲートウェイ 3. ゲートウェイの登録日時が古いゲートウェイ	タイムアウト: 複数ゲートウェイへのリクエストが発生するケースでは、タイムアウト時間は30秒以上となる可能性があります。オフライン: 全てのゲートウェイの接続状態がオフライン

注釈

ここでは、基本的な呼び出し方法であるシング ID による Device API のシンプルな実行シーケンスを示しています。

IoT アクセス制御エンジンは、シング ID だけでなくニックネームやタグ名を指定して Device API を実行することも可能です。ニックネームやタグ名は、シング ID に任意の文字列を設定するエイリアスのような機能です。