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

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

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

Endorse を有効化する

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

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

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

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

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

[保存] をクリックします。
IoT SIM が所属するグループを切り替えます。
IoT SIM の Endorse の設定が有効になります。

SORACOM CLI / SORACOM API の場合

SORACOM CLI または SORACOM API を利用しても、IoT SIM の詳細情報を取得できます。

SORACOM CLI を利用する場合は、soracom groups put-config を使用します。
SORACOM API を利用する場合は、Group:putConfigurationParameters API を使用します。

ボディで指定するプロパティについても参照してください。

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

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

`key`	`value` の型	`value`
`enabled` *	Boolean	Endorse の on/off を設定します。 `true`: on `false`: Off
`parametersToEndorse` *	Object	認証トークンに含める値を指定します。指定できる値は、`imsi`、`imei`、`msisdn`、`requestParameters` です。リクエストパラメータを含める方法について詳しくは、ユーザーデータを利用するを参照してください。例: `{ "imsi": true, "imei": true, "msisdn": false, "requestParameters": true }`
`tokenTimeoutSeconds`	Number	認証トークンには有効期間 (秒) を設定できます。有効期間が経過した認証トークンは利用しないでください。
`allowOrigin`	String	CORS (Cross-Origin Resource Sharing) ヘッダー (`access-control-allow-origin`) で許可するオリジンを指定します。
`authorizedRedirectUrls`	Array of strings	Endorse のレスポンスを使ってクライアントを別の URL にリダイレクトさせる場合に、リダイレクト先の URL の候補を指定します。このパラメータに含まれない URL へのリダイレクトリクエストは拒否されます。

想定していない値を指定した場合の動作は、定義されていません。SORACOM CLI / SORACOM API で設定を変更したあとで、SORACOM ユーザーコンソールで意図通りに設定されていることを確認してください。

(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 ライブラリを利用できます。

認証トークンは必ず検証してください

Endorse が発行する認証トークンは、Endorse が持つ秘密鍵で署名されています。秘密鍵に対応する公開鍵を使って、認証トークンを検証してください。お客様サーバーに認証トークンと同じフォーマットのデータが届いたとしても、悪意を持つ第三者が発行した認証トークンの可能性があります。その場合は、IMSI、IMEI、ユーザーデータなどを利用してはいけません。認証トークンは必ず検証してください。

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

認証トークン (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"
  }
}

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

認証トークンを検証する際に利用する公開鍵をダウンロードします。
公開鍵のファイル名は、トークンのヘッダーに 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 からダウンロードできます。
RFC 7519 に従って、認証トークンを検証します。
JWT ライブラリなどを利用して検証することもできます。検証に成功した場合は、認証トークンのペイロードに含まれる情報を利用できます。
- 検証に失敗した場合は、認証トークンのペイロードに含まれる情報は利用しないでください。
- SORACOM サポートでは、JWT ライブラリの利用方法など、認証トークンの検証方法についてはサポートしません。

Soracom

Users