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

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

はじめに

SORACOM Endorse (以下、Endorse) は、IoT SIM を使用しているデバイスに対して、SORACOM が認証プロバイダーとしてデバイスの認証サービスを提供します。 SIM を使用した認証を Wi-Fi などの SIM 以外の通信にも使うことが可能となります。

Endorse は、デバイスが IoT SIM を使用しており、SORACOM Air の回線を通じてネットワーク接続可能な状態であることを証明するトークンを発行します。 このトークンは一定の有効期間を持ち、IMSI (International Mobile Subscriber Identity) や通信モジュールの IMEI (International Mobile Equipment Identity) などを含めることができます。

また、Endorse サーバによって非対称鍵による署名がなされているため、クライアントデバイスはそのトークンを提示することで、別のサービスに対して自身の持つ IMSI や IMEI といった情報を証明することができます。

なお、Endorse は コンソール、API での設定可能です。

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

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

グループの設定方法はこちらを参照してください。

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

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

トークンに含めたいパラメータにチェックを入れてください。「許可するオリジン」、「認可されたリダイレクト先 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 でデコードした様子を示します。

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

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

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

{
  "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 が表示されます。

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

以降、補足として、ユーザーデータの利用について触れます。

ユーザーデータの利用

Endorse のトークンには IMSI, IMEI, MSISDN などのサーバ側で付与される情報に加え、任意の Key Value ペアを requestParameters として含むことが可能です。 例えば、Web サイトや認証サーバから Endorse エンドポイントにクライアントをリダイレクトさせてトークンを取得させるような場合に、元のサイト側のセッション ID などをトークンに含ませるなどのユースケースが考えられます。

requestParameters を利用するには、まず Endorse の SoracomEndorse.parametersToEndorse に {requestParameters: true} を設定します。 その上で、GET であればクエリパラメータとして、POST であればリクエストボディとして送信された Key Value ペアが Endorse のトークンに含まれます。

requestParameters に {“username”: “foo”, “sessionId”: “bar”} を含むトークンを取得する例を示します。

• GET の場合

$ curl https://endorse.soracom.io?username=foo&sessionId=bar

また、クエリパラメータとして redirect_url というパラメータでクライアントをリダイレクトさせたい URL を設定すると、トークンをクライアントに送る代わりに、トークンを soracom_endorse_token というクエリパラメータとして設定しつつ、指定の URL にクライアントをリダイレクトさせます。

$ curl https://endorse.soracom.io?username=foo&sessionId=bar&redirect_url=https://example.com/login

本機能を利用する場合は、リダイレクト先の URL を SoracomEndorse.authorizedRedirectUrls に予め設定しておく必要があります。指定された URL が設定されていない場合は、リクエストは拒否されます。

• POST の場合

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

上記のリクエストを行った場合の応答に含まれる情報の例を下記に示します。

{
  "iss": "https://soracom.io",
  "aud": "soracom-endorse-audience",
  "exp": 1451116301,
  "jti": "hkK7qNyXzEMVAXfTq1MBuA",
  "iat": 1451116121,
  "nbf": 1451116061,
  "sub": "soracom-endorse",
  "soracom-endorse-claim": {
    "imsi": "440XXXXXXXXXXXX",
    "requestParameters": {
      "username": "foo",
      "sessionId": "bar"
    }
  }
}

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

今後も様々な機能の追加を検討していきますので、是非ご要望をお聞かせください。 ​