Soracom

Endorse で認証トークンを発行し、お客様のサーバーに送信します。

お客様のサーバーでは、受信した認証トークンを検証して、送信元のデバイスを確認したり、認証トークンに含まれる IMSI や IMEI を利用します。

Endorse を有効化する

1. SIM グループ画面で [SORACOM Endorse 設定] をクリックします。

   SIM グループ画面を表示する操作について詳しくは、グループの設定を変更する を参照してください。

2. スイッチをクリックして「on」にします。

   

3. 以下の項目を設定します。

   項目	説明
   [認証トークンに含める項目]	認証トークンに含める値を指定します。 指定できる値は、[SIM ID]、[IMSI]、[IMEI]、[MSISDN]、[リクエストパラメータ] です。認証トークンにリクエストパラメータを含める方法について詳しくは、ユーザーデータを利用する を参照してください。
   [認証トークンの有効期間 (秒)]	認証トークンには有効期間 (秒) を設定できます。有効期間が経過した認証トークンは利用しないでください。
   [許可するオリジン]	CORS (Cross-Origin Resource Sharing) ヘッダー (access-control-allow-origin) で許可するオリジンを指定します。
   [許可されたリダイレクト先 URL]	Endorse のレスポンスを使ってクライアントを別の URL にリダイレクトさせる場合に、リダイレクト先の URL の候補を登録します。 このパラメータに含まれない URL が、redirect_url クエリパラメータで指定された場合は、リダイレクトリクエストは拒否されます。

4. [保存] をクリックします。

5. IoT SIM が所属するグループを切り替えます。

   IoT SIM の Endorse の設定が有効になります。

ボディで指定するプロパティについて

以下の key と value のペアを配列で指定します。

{
  "simId": true,
  "imsi": true,
  "imei": true,
  "msisdn": false,
  "requestParameters": true
}

(1) 認証トークンを発行する

Endorse を有効化 したグループに所属する IoT SIM を利用するデバイスで、Air for セルラーを利用して SORACOM に接続していることを確認してから、以下のコマンドを実行します。

• GET の場合

  $ curl https://endorse.soracom.io
  

  {"token":"eyJraWQiOiJ2MS1mMmZlYTA2MGI5M2Y1MTBiZmI3MjJmMmNkNGIzNzc0ZS14NTA5LnBlbSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJodHRwczovL3NvcmFjb20uaW8iLCJhdWQiOiJzb3JhY29tLWVuZG9yc2UtYXVkaWVuY2UiLCJleHAiOjE0NTMyODgwMzYsImp0aSI6InY4UE5nQlBaVUZ6Vk5YWngzeXZ3cGciLCJpYXQiOjE0NTMyODc4NTYsIm5iZiI6MTQ1MzI4Nzc5Niwic3ViIjoic29yYWNvbS1lbmRvcnNlIiwic29yYWNvbS1lbmRvcnNlLWNsYWltIjp7Imltc2kiOiI0NDAxMDMxMzQwNzQ0NDkifX0.eF38eRyVXLB0KNP2mouBBhD5He2gp0eeadOksz9BXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"}
  

  token の値 (eyJra...) が認証トークンです。

• POST の場合

  $ curl -X POST https://endorse.soracom.io \
  -d '{
    "username": "foo",
    "sessionId": "bar"
  }'
  

  {"token":"eyJraWQiOiJ2MS1mMmZlYTA2MGI5M2Y1MTBiZmI3MjJmMmNkNGIzNzc0ZS14NTA5LnBlbSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJodHRwczovL3NvcmFjb20uaW8iLCJhdWQiOiJzb3JhY29tLWVuZG9yc2UtYXVkaWVuY2UiLCJleHAiOjE2Nzk5MjkxNjksImp0aSI6IldlR2tCamVsX0dySFd4UERkRzktR2ciLCJpYXQiOjE2Nzk5MjMxNjksIm5iZiI6MTY3OTkyMzEwOSwic3ViIjoic29yYWNvbS1lbmRvcnNlIiwic29yYWNvbS1lbmRvcnNlLWNsYWltIjp7Imltc2kiOiIyOTUwNTA5MTMyNDQyMjMiLCJpbWVpIjoiODY3Njk4MDQ3NDM3NTgwIiwicmVxdWVzdFBhcmFtZXRlcnMiOnsie1xuICAgICAgXCJ1c2VybmFtZVwiOiBcImZvb1wiLFxuICAgICAgXCJzZXNzaW9uSWRcIjogXCJiYXJcIlxuICAgIH0iOiIifX19.a_1TSEmrTJlKraFIMux4T68VN09g5-j0MRyMJ5nWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"}
  

  token の値 (eyJra...) が認証トークンです。

  認証トークンにユーザーデータを含める場合は、POST を使用できます。詳しくは、ユーザーデータを利用する を参照してください。

(2) 認証トークンをお客様のサーバーに送信する

認証トークンを、任意の方法でお客様のサーバーに送信します。

(3) 公開鍵をダウンロードして認証トークンを検証する

認証トークンは、ウェブアプリケーションでよく使用される JSON Web Token (JWT) 形式です。そのため、認証トークンを検証する際は、各種プログラミング言語向けの JWT ライブラリ を利用できます。

1. 認証トークンをデコードします。

   認証トークン (JWT トークン) のヘッダーとペイロードが取得できます。

   ヘッダー:

   {
     "kid": "v1-f2fea060b93f510bfb722f2cd4b3774e-x509.pem",
     "alg": "RS256"
   }
   

   ペイロード:

   {
     "iss": "https://soracom.io",
     "aud": "soracom-endorse-audience",
     "exp": 1451116301,
     "jti": "hkK7qNyXzEMVAXfTq1MBuA",
     "iat": 1451116121,
     "nbf": 1451116061,
     "sub": "soracom-endorse",
     "soracom-endorse-claim": {
       "imsi": "440XXXXXXXXXXXX",
       "imei": "353XXXXXXXXXXXX",
       "simId": "89000XXXXXXXXXXXXXX"
     }
   }
   

   ペイロードにユーザーデータを含めることもできます。詳しくは、認証トークンにユーザーデータを含める を参照してください。

2. 認証トークンを検証する際に利用する公開鍵をダウンロードします。

   公開鍵のファイル名は、トークンのヘッダーに kid という属性名で含まれています。

   上記の例の場合、v1-f2fea060b93f510bfb722f2cd4b3774e-x509.pem が公開鍵のファイル名です。

   また、公開鍵は、https://s3-ap-northeast-1.amazonaws.com/soracom-public-keys/ 以下に保存されているため、この URL に公開鍵のファイル名を連結すると、公開鍵の URL を取得できます。

   つまり、上記の例の場合、署名検証に必要な公開鍵は https://s3-ap-northeast-1.amazonaws.com/soracom-public-keys/v1-f2fea060b93f510bfb722f2cd4b3774e-x509.pem からダウンロードできます。

3. RFC 7519 に従って、認証トークンを検証します。

   JWT ライブラリなどを利用して検証することもできます。検証に成功した場合は、認証トークンのペイロードに含まれる情報を利用できます。

   • 検証に失敗した場合は、認証トークンのペイロードに含まれる情報は利用しないでください。
   • SORACOM サポートでは、JWT ライブラリの利用方法など、認証トークンの検証方法についてはサポートしません。