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

当ガイドでは、Endorse を使用してトークンを発行します。このトークンおよび署名検証の有効性を検証します。

コンソールを使用して Endorse を設定する

Endorse は利用する IoT SIM の所属するグループに設定します。トークンに含めるべきパラメータを選択できます。

グループの設定方法は基本的な使い方: SIM グループを設定するを参照してください。

Endorse は利用する IoT SIM の所属するグループに設定します。トークンに含めるべきパラメータを選択できます。

ユーザーコンソールでの設定

ユーザーコンソールでは、グループ設定画面から Endose を有効化します。

Endorse setup

トークンに含めたいパラメータにチェックを入れてください。「許可するオリジン」、「認可されたリダイレクト先 URL」も必要に応じて記載してください。

上記の画面の通り設定します。

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 の設定は完了です。

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: ユーザーデータを利用するを参照してください。