JSON Web Token
JSON Web Token
Mobage JS SDK で用いられている JSON Web Token (JWT) とは、現在 IETF で策定中の仕様で執筆時現在の最新仕様は JSON Web Token (JWT) draft-ietf-oauth-json-web-token-15 になります。
JWT とは二者間でデータをやり取りする際のデータ表現で、本文は JSON object です (正確には JWT Claims Set と言います)。
JWT では、この JSON object に対して JSON Web Signature (JWS) によって署名が成されているか、または JSON Web Encryption (JWE) によって暗号化されています。Mobage JS SDK で取り扱う JWT は常に JWS 形式で、その署名形式は JWT Header に記載されており、alg フィールドで指定されています。現在は RS256 という署名アルゴリズムのみが指定されます。
JWT 形式を取り扱うライブラリは様々な言語で揃っています。たとえば、下記のような言語別ライブラリがあります。なお、利用方法は各ライブラリのドキュメントを参照して下さい。
各言語の JWT library
| 言語 | ライブラリ名 | URL |
|---|---|---|
| Ruby | ruby-jwt | https://github.com/progrium/ruby-jwt |
| Java | jsontoken | https://code.google.com/p/jsontoken/ |
| Perl | JSON::WebToken | https://github.com/xaicron/p5-JSON-WebToken |
JWT の検証
JWT 中の JWT Claims Set には幾つかの予約 Claims があります。これらについては 4.JWT Claims を参照して下 さい。
Mobage JS SDK で用いる JWT Claims Set は多くの場合で下の表に示す意味になります。
Mobage JS SDK で用いる JWT Claims Set
| Claim | Type | 意味 |
|---|---|---|
| jti | string | JWT のユニーク識別子 |
| iss | string | JWT を発行したサーバーの URI |
| aud | string | この JWT を利用出来る Client の Client Identifier |
| sub | string | この JWT の主体となる Mobage ユーザーの User ID |
| iat | integer | この JWT が発行された日時を表す UNIX Timestamp 値 |
| exp | integer | この JWT が無効になる日時を表す UNIX Timestamp 値 |
iss フィールドに関しては取り扱う JWT ごとに異なり、またその JWT が service/sandbox 環境のいずれかを判断する指標にもなります。現在 Mobage JS SDK で利用する JWT の発行者 (Issuer) を表す iss プロパティの値は以下に示す通りです。
Issuer と環境別の iss の値
| Issuer | 環境 | iss の値 |
|---|---|---|
| Mobage Connect | sandbox | https://sb-connect.mobage.jp |
| service | https://connect.mobage.jp | |
| Widget Service | sandbox | https://sb-widget.mobage.jp |
| service | https://widget.mobage.jp | |
| Async Confirmation | sandbox | https://sb-hub.mobage.jp |
| service | https://hub.mobage.jp |
その上で以下の観点で JWT Claims Set を検証する必要があります。
- iss が表「Issuer と環境別の iss の値」に記載された値に合致するかどうか
- aud がアプリケーションの Client Identifier に一致するかどうか
- iat が現在日時より過去かどうか
- exp が現在日時より未来かどうか
より汎用的な検証コードとしては下記 Perl で書かれたサンプルを参照して下さい。なお、Public Key の値は最後の「署名形式が RS256 の場合の公開鍵」に記載されています。
JWS の署名生成アルゴリズムは、RS256 です。以下のように必ずヘッダに含まれる alg が RS256 となっていることを確認してください。
#!/usr/bin/env perl
use strict;
use warnings;
use Carp;
use JSON::WebToken;
our %PUBLIC_KEY = (
service => "public_key_of_service",
sandbox => "public_key_of_sandbox",
);
our %ISSUER = (
"`https://connect.mobage.jp"` => "service",
"`https://sb-connect.mobage.jp"` => "sandbox",
"`https://widget.mobage.jp"` => "service",
"`https://sb-widget.mobage.jp"` => "sandbox",
"`https://hub.mobage.jp"` => "service",
"`https://sb-hub.mobage.jp"` => "sandbox",
);
sub verify_jwt {
my ($jwt, $client_id, $environment) = @_;
my $jwt_claims;
eval {
$jwt_claims = decode_jwt(
$jwt, sub {
my ($header, $claims) = @_;
if (exists $ISSUER{$claims->{iss}}) {
croak sprintf("Not acceptable iss (iss: %s)", $claims->{iss});
}
if ($ISSUER{$claims->{iss}} ne $environment) {
croak "Invalid environment";
}
if ($claims ->{aud} ne $client_id) {
croak sprintf("Not acceptable aud (aud: %s)", $claims->{aud});
}
my $current_time = time;
if (exists $claims->{iat} && $claims->{iat} > $current_time) {
croak sprintf("Invalid iat (iat: %s)", $claims->{iat});
}
if (exists $claims->{exp} && $claims->{exp} < $current_time) {
croak sprintf("Expired JWT (exp: %s)", $claims->{exp});
}
if ($header->{alg} eq "RS256") {
return $PUBLIC_KEY{$environment}
}
else {
croak sprintf("Unsupported alg (%s)", $header->{alg} || "");
}
}
);
};
if (my $e = $@) {
warn $e;
return;
}
return $jwt_claims;
}
署名形式が RS256 の場合の公開鍵
JWT Claims が妥当であり、JWT Header の alg フィールドが RS256 の場合は、この iss の値に応じて Public Key を選択し signature の検証を行います。
各環境における Public Key の値は、PKCS#1 形式、X509 形式別に記載します。
sandbox 環境の RS256 用 public key(PKCS#1 形式)
-----BEGIN RSA PUBLIC KEY-----
MIIBCgKCAQEAuDopA35ZLa1sgi2QTFbZjH63BrhXw4evehjDiLHrSc5s+jKMSqfd
6BLoQhN7jcOBnofQB/3rEoy6YXkW58lEtVmekQtYAHh11oB8TBBqzNZP1QxKXWjz
8Jely5bJZHztZEzfddDR7yVZF0VSEa0KjiHbqCdAqXKYuAzUMN4dFyS/q0JXvGAr
Jq/LXyVC3EptcZki02p3Nd6KDZHW7hcj+p0xgYNiGCHO7yLf3uHP+7pak5TW0dWf
MC9fl1/oYFILuasW7OV75+vJGs8d92joEC/Lx3S8+gi3z0CWMnCKrWiTtaAKAq8W
yp4Go8WczOQ1rP+bzDj7b/9M3xrjqY3F0wIDAQAB
-----END RSA PUBLIC KEY-----
sandbox 環境の RS256 用 public key(X509 形式)
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuDopA35ZLa1sgi2QTFbZ
jH63BrhXw4evehjDiLHrSc5s+jKMSqfd6BLoQhN7jcOBnofQB/3rEoy6YXkW58lE
tVmekQtYAHh11oB8TBBqzNZP1QxKXWjz8Jely5bJZHztZEzfddDR7yVZF0VSEa0K
jiHbqCdAqXKYuAzUMN4dFyS/q0JXvGArJq/LXyVC3EptcZki02p3Nd6KDZHW7hcj
+p0xgYNiGCHO7yLf3uHP+7pak5TW0dWfMC9fl1/oYFILuasW7OV75+vJGs8d92jo
EC/Lx3S8+gi3z0CWMnCKrWiTtaAKAq8Wyp4Go8WczOQ1rP+bzDj7b/9M3xrjqY3F
0wIDAQAB
-----END PUBLIC KEY-----
service 環境の RS256 用 public key(PKCS#1 形式)
-----BEGIN RSA PUBLIC KEY-----
MIIBCgKCAQEA2TrWbLVUDqZJcIGhCNarELkxvD/ckLw/MKrNP4bUZhGQcJ2uN2bQ
xKk3LhXUgv1MeUHJvm77zNfnWlY44z0oL1cnuPjJsSFYjSSjjWVLdxVw5qZrjrVO
bQ5uE0H+t8Od8aTFk09TCLuac/129uVkRXOr6gLppaFZAH+Hgl83igz+xwIz6w62
hngYOAp0IyCbyOsphHj3uf1d0NOloAtYPTXZQM1E/rnbeggjbTprTQri3jAheH2Y
+tjfsXrxzFgNS1+SW+LbRefBGyJYxcEZXdxgvw2BCVDGXEZJWPpN+vKu6OjWN/sU
c6nKq7mthZYA/KTBBswAaB6rZYoFPSU87QIDAQAB
-----END RSA PUBLIC KEY-----
service 環境の RS256 用 public key(X509 形式)
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2TrWbLVUDqZJcIGhCNar
ELkxvD/ckLw/MKrNP4bUZhGQcJ2uN2bQxKk3LhXUgv1MeUHJvm77zNfnWlY44z0o
L1cnuPjJsSFYjSSjjWVLdxVw5qZrjrVObQ5uE0H+t8Od8aTFk09TCLuac/129uVk
RXOr6gLppaFZAH+Hgl83igz+xwIz6w62hngYOAp0IyCbyOsphHj3uf1d0NOloAtY
PTXZQM1E/rnbeggjbTprTQri3jAheH2Y+tjfsXrxzFgNS1+SW+LbRefBGyJYxcEZ
Xdxgvw2BCVDGXEZJWPpN+vKu6OjWN/sUc6nKq7mthZYA/KTBBswAaB6rZYoFPSU8
7QIDAQAB
-----END PUBLIC KEY-----