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-----