SORACOM Endorse で発行された認証トークンを検証する

SORACOM Endorse (以下、Endorse) を使用して認証トークンを発行します。

クライアントデバイスでは、この認証トークンおよび署名の有効性を検証してから、IMSI や IMEI を利用します。

認証トークンを発行する

Endorse の設定はグループに対して行います

ここでは、グループの設定を変更する操作のみを説明します。グループの仕組みやグループを作成する操作ついて詳しくは、グループ設定を参照してください。

SIM グループ画面で [SORACOM Endorse 設定] をクリックします。
SIM グループ画面を表示する操作について詳しくは、グループの設定を変更するを参照してください。
スイッチをクリックして「ON」にします。

認証トークンに含めるパラメータにチェックを入れます。「許可するオリジン」、「認可されたリダイレクト先 URL」も必要に応じて記載してください。
上記の画面のとおりに設定します。
[保存] をクリックします。
IoT SIM が所属するグループを切り替えます。
IoT SIM の Endorse の設定が有効になります。

SDK を使用して Endorse を設定する

当セクションでは、Endorse の設定に SDK を使用します。

まず、SDK が最新であるかを確認してください。ターミナルなどから以下のコマンドを実行してください。

$ gem soracom version

「Soracom API tool v1.1.0」以降であることを確認してください。

導入方法や設定などは、SORACOM SDK for Ruby を参照してください。

設定の例と各キーの説明は、以下のとおりです。

設定の例

{
  "SoracomEndorse": {
    "enabled": true,
    "parametersToEndorse": {
      "imsi": true,
      "imei": true,
      "msisdn": false,
      "requestParameters": true
    },
    "tokenTimeoutSeconds": 600,
    "allowOrigin": "https://soracom.io",
    "authorizedRedirectUrls": ["https://soracom.io", "http://localhost:3000"]
  }
}

各キーの説明

SoracomEndorse.enabled: SORACOM Endorse を有効にするか否か
SoracomEndorse.parametersToEndorse: トークンに含むべきパラメータを選択。選択可能なパラメータは imsi, imei, msisdn, requestParameters
SoracomEndorse.tokenTimeoutSeconds: (optional) トークンの発行時からの有効な期間の秒数を設定
SoracomEndorse.allowOrigin: (optional) CORS ヘッダを有効にする場合に指定。設定した文字列がレスポンスの access-control-allow-origin ヘッダに設定される
SoracomEndorse.authorizedRedirectUrls: (optional) SORACOM Endorse のレスポンスを使ってクライアントを別の URL にリダイレクトとさせる場合に、リダイレクト先の URL の候補を指定。(このパラメータに含まれない URL へのリダイレクトリクエストは拒否されます)

CLI での設定

以下のフォーマットでファイルを作成してください。(ここでは、endorse.json というファイル名で保存します。)

{
  "parametersToEndorse": {
    "imsi": true,
    "imei": true,
    "msisdn": false,
    "requestParameters": true
  },
  "enabled": true,
  "tokenTimeoutSeconds": 600
}

事前に設定対象のグループを作成してください。グループの設定方法はグループ設定を参照してください。

設定対象のグループ ID を指定して、以下のコマンドを実行し、設定を適用します。

$ soracom group update-configuration --group-id XXXXXXXXXXXXXXXXXXXXXXXXXXX --namespace SoracomEndorse --params file:///Users/xxxxx/endorse/endorse.json | jq .configuration.SoracomEndorse
{
  "parametersToEndorse": {
    "imsi": true,
    "imei": true,
    "msisdn": false,
    "requestParameters": true
  },
  "enabled": true,
  "tokenTimeoutSeconds": 600
}

上記コマンド内で指定した以下のファイルは、先ほど作成した Endorse の設定を記載したファイルです。

file:///Users/xxxxx/endorse/endorse.json (ファイルは、フルパスで指定してください。)

ファイルからではなく、--param の引数として、直接 JSON を記述することも可能です。ここでは、ファイルに記載したものを指定しています。

以上で、Endorse の設定は完了です。

SORACOM CLI または SORACOM API で、ボディに指定するプロパティの設定例は、以下のとおりです。

[
  {
    "key": "enabled",
    "value": true
  },
  {
    "key": "parametersToEndorse",
    "value": {
      "imsi": true,
      "imei": true,
      "msisdn": false,
      "requestParameters": true
    }
  },
  {
    "key": "tokenTimeoutSeconds",
    "value": 600
  },
  {
    "key": "allowOrigin",
    "value": "https://soracom.io"
  },
  {
    "key": "authorizedRedirectUrls",
    "value": ["https://soracom.io", "http://localhost:3000"]
  }
]

Endorse のトークンを取得する

先ほど設定したグループに属する IoT SIM で通信を行っているデバイスから、以下のエンドポイントにアクセスすることでトークンを取得できます。

https://endorse.soracom.io

サポートしている HTTP メソッドは、GET, POST です。

では、以下のコマンドを実行し、トークンを取得してみましょう。

$ curl https://endorse.soracom.io
{"token":"eyJraWQiOiJ2MS1mMmZlYTA2MGI5M2Y1MTBiZmI3MjJmMmNkNGIzNzc0ZS14NTA5LnBlbSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJodHRwczovL3NvcmFjb20uaW8iLCJhdWQiOiJzb3JhY29tLWVuZG9yc2UtYXVkaWVuY2UiLCJleHAiOjE0NTMyODgwMzYsImp0aSI6InY4UE5nQlBaVUZ6Vk5YWngzeXZ3cGciLCJpYXQiOjE0NTMyODc4NTYsIm5iZiI6MTQ1MzI4Nzc5Niwic3ViIjoic29yYWNvbS1lbmRvcnNlIiwic29yYWNvbS1lbmRvcnNlLWNsYWltIjp7Imltc2kiOiI0NDAxMDMxMzQwNzQ0NDkifX0.eF38eRyVXLB0KNP2mouBBhD5He2gp0eeadOksz9BXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"}

上記のようにトークンが取得できました。

トークンの有効性を検証する

トークンは Json Web Token (JWT) フォーマットとなっており、各種プログラミング言語向けの JWT ライブラリを用いることで含まれる情報の取得や、改ざんなどがされていないかどうかを簡単に確認できます。

上記のトークンを JWT の仕様に従ってデコードすると、下記のような情報がペイロードに含まれています。

{
  "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"
  }
}

簡単に中身やその有効性を確認する方法としては、http://jwt.io にある Debugger を用いるのが便利です。以下に上記トークンを同サイトの Debugger でデコードした様子を示します。

Endorse

左側のペインにある Encoded の部分に発行されたトークンを貼り付けると、Decoded されたトークンを確認できます。

また、Endorse が発行するトークンは、SORACOM が持つ秘密鍵でその内容に署名がなされており、対応する公開鍵をダウンロードしていただくことで改ざんがされていないかどうか検証することができます。

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

Endorse

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

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

Endorse の署名検証に用いる公開鍵は、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 からダウンロードできます。

署名の検証も http://jwt.io の Debugger で試すことができます。上記 URL からダウンロードした公開鍵を、Debugger の Public Key or Certificate の部分に貼り付けると、トークンが改ざんされていないことを示す Signature Verified が表示されます。

Endorse

以上で、「SORACOM Endorse で発行されたトークンを検証する」は完了です。

ユーザーデータも利用できますので Getting Started: ユーザーデータを利用するを参照してください。