12 Oracle JSON Web Token

Oracle JSON Web Token APIは、JSON Web Token (JWT)を幅広くサポートする完全なJavaソリューションです。このAPIを使用して、Base64urlでエンコードされたトークンの構成、トークンのヘッダーとクレームのパラメータ値の設定、トークンの解析と検証、およびトークンの署名とシリアライズを行うことができます。

リリース11gで導入されたOracle JSON Web Tokenでは、JSON Web Token (JWT)規格のサポートを提供します。

12.1 Oracle JSON Web Tokenの機能と利点

JSON Web Token (JWT)は、二者の間で転送されるクレームを表します。JWTは、HTTP認可ヘッダーやURI問合せパラメータなど、領域が制限された環境向けのコンパクトなトークン・フォーマットです。このAPIを使用して、Base64urlでエンコードされたトークンの構成、トークンのヘッダーとクレームのパラメータ値の設定、トークンの解析と検証、およびトークンの署名とシリアライズを行うことができます。

この項では、JWTの概念およびOracle JSON Web Tokenの主要な機能について説明します。

12.1.1 JSON Web Tokenについて

JSON Web Token (JWT)は、二者の間で転送されるクレームを表します。JWTは、HTTP認可ヘッダーやURI問合せパラメータなど、領域が制限された環境向けのコンパクトなトークン・フォーマットです。JSONオブジェクトは、JSON Web Signature (JWS)を使用してデジタル署名され、オプションで、JSON Web Encryption (JWE)を使用して暗号化されます。

JWTにあるクレームは、base64urlでエンコードされていて0個以上の名前と値(名前は文字列で値は任意のJSON値)のペア(またはメンバー)で構成される、JSONオブジェクトとしてエンコードされます。各メンバーは、JWTによって表されるクレームです。

JWTは、次の3つのセグメントを連結したもので表されます。

JWTヘッダー・セグメントは、トークンに適用される暗号化操作を指定します。
JWTクレーム・セグメントは、JWTに含まれるクレームをエンコードします。
JWT暗号セグメントには、トークンのコンテンツを保護する暗号化マテリアルが含まれます。

各セグメントは、ピリオド('.')文字で区切られます。3つのすべてのセグメントは、常にBase64urlでエンコードされた値になります。

12.1.2 Oracle JSON Web Tokenの機能

このAPIを使用して、Base64urlでエンコードされたトークンの構成、トークンのヘッダーとクレームのパラメータ値の設定、トークンの解析と検証、およびトークンの署名とシリアライズを行うことができます。

Oracle JSON Web Tokenは、JWTトークンを幅広くサポートする完全なJavaソリューションです。APIを使用すると次のことが可能です。

Base64urlでエンコードされたトークンの構成、および、ユーザー定義のヘッダーなど、トークンのヘッダーとクレームのパラメータ値の設定
トークンの解析および検証
トークンの署名およびシリアライズ

oracle.security.jwt.JwtTokenクラスは、JSON Web Token (JWT)を表します。oracle.security.jwt.JwtTokenの代表的なメソッドは、次のとおりです。

setAlgorithm(String)、getAlgorithm()
signAndSerialize(PrivateKey)
serializeUnsigned()
setPrincipal(String)、getPrincipal()、getIssuer()などのクレーム・メソッド

詳細は、Javadocにある、ヘッダーとクレームのパラメータ名および対応するget/setメソッドの表を参照してください。

12.2 Oracle JSON Web Tokenの環境設定

Oracle JSON Web Tokenの環境を設定するには、Oracleセキュリティ開発ツールとJava Development Kit (JDK)をインストールし、必要なすべてのjarファイルおよびclassファイルへのCLASSPATH変数を設定します。

Oracleセキュリティ開発ツールは、Oracle WebLogic ServerとともにORACLE_HOMEにインストールされます。

Oracle JSON Web Tokenを使用するには、システムにJava Development Kit (JDK)バージョン1.6以上が必要です。

CLASSPATH環境変数には、必要なjarファイルおよびclassファイルすべてのフルパスとファイル名を指定してください。次の項目をCLASSPATHに指定します。

osdt_core.jarファイル
osdt_cert.jarファイル
jackson-core-1.1.1.jarファイル
jackson-mapper-1.1.1.jarファイル

たとえば、CLASSPATHは次のようになります。

setenv CLASSPATH $CLASSPATH:
$ORACLE_HOME/modules/oracle.osdt_11.1.1/osdt_core.jar:
$ORACLE_HOME/modules/oracle.osdt_11.1.1/osdt_cert.jar:
$Jackson.library.path/jackson-core-1.1.1.jar
$Jackson.library.path/jackson-mapper-1.1.1.jar

実行時に、次の場所でJackson jarが検索されます。

存在する場合、jarはシステム・クラス・パスからロードされます。
jarがシステム・クラス・パスに存在しない場合、システム・プロパティJackson.library.pathを調べます。存在する場合、jarはJava SEクライアントとJava EEクライアントの両方の場所からロードされます。
システム・プロパティJackson.library.pathが設定されていないか、Jackson jarがそこに見つからない場合、事前定義済の場所$ORACLE_HOME/modules (Java EE環境の場合)および現在のディレクトリ(Java SEクライアントの場合)から取得されます。

12.3 コア・クラスとインタフェースの使用方法

Oracle JSON Web Tokenは、oracle.security.restsec.jwt.JwtTokenクラスで構成されます。このクラスの主な機能として、JWTトークンの構成、JWTトークンのパラメータ値の設定、トークンの署名、トークンの検証、トークンのシリアライズなどがあります。

「Oracle JSON Web Tokenの使用例」に、Oracle JSON Web Tokenの使用方法を示します。

12.4 Oracle JSON Web Tokenの使用例

Oracle JSON Web Tokenの使用方法については、JWTトークンの構成、トークンの署名、トークンの検証および署名なしのトークンのシリアライズの例を参照してください。

この項では、Oracle JSON Web Tokenの使用例を説明します。

注意:

これらは、Oracle JSON Web Tokenの使用方法を示す具体例です。ここで説明したメソッドの使用の詳細およびその他のオプションについては、JWT javadoc (「Oracle JSON Web Token Java APIのリファレンス」)を参照してください。

12.4.1 JWTトークンの作成

JWTトークンの作成には、オブジェクトそのものの作成と、必要に応じてヘッダーおよびクレームのパラメータの設定が含まれます。

手順は次のとおりです。

JWTトークンを作成するには、コンストラクタ・メソッドJwtToken()を使用して、JwtTokenオブジェクトの作成を開始します。
```
JwtToken jwtToken = new JwtToken(); 
```
様々なsetterメソッドを使用して、JWTトークンのパラメータ値を設定できます。
ヘッダー・パラメータを設定するには、ヘッダー・パラメータalgを最初に設定する必要があります。setAlgorithm(String)メソッドを使用してこのパラメータを設定し、getAlgorithm()メソッドを使用してこのパラメータを取得します。デフォルトでは、algパラメータはnoneに設定されており、これはトークンに署名しないことを意味します。
setHeaderParameter(String, Object)メソッドを使用して、JWTヘッダー・セグメント内のユーザー定義のヘッダー・パラメータを設定します。
Oracle JSON Web Tokenでは、クレーム・パラメータexp、iat、iss、aud、prnを設定するためのメソッドが用意されています。すべてのクレーム・パラメータはオプションです。
setClaimParameter(String, Object)メソッドを使用して、JWTクレーム・セグメント内のユーザー定義のクレーム・パラメータを設定します。

12.4.2 JWTトークンの署名

トークンの署名には、トークン・インスタンスの作成、トークン・パラメータの設定、最後にトークンの署名といったアクションが含まれます。

手順は次のとおりです。

まず、JwtTokenクラスのインスタンスを作成することで、JWTトークンの作成および署名を行います。
```
JwtToken jwtToken = new JwtToken(String); 
```

次に、アルゴリズム、発行者、有効期限、その他のクレームなどのパラメータを次のように設定します。

jwtToken.setAlgorithm(JwtToken.SIGN_ALGORITHM.HS256.toString());
jwtToken.setType(JwtToken.JWT);
jwtToken.setIssuer("my.company.com");
jwtToken.setPrincipal("john.doe");

最後に、次のように、秘密鍵を取得して、秘密鍵を使用したトークンに署名します。
```
PrivateKey privateKey ;
String jwtString = jwtToken.signAndSerialize(privateKey);
```

12.4.3 JWTトークンの検証

トークンの検証には、HTTPヘッダーからのトークンの読取り、トークンの発行者の確認などのアクションが含まれます。

次のコード例では、有効期限およびトークンの発行者を検証しています。

// Read the JWT token as a String from HTTP header
String jwtStr = "eyJ.eyJp.dB";
JwtToken token = new JwtToken(jwtStr);
 
// Validate the issued and expiry time stamp.
if (token.getExpiryTime().after(new Date())) {
...
...
}
 
// Get the issuer from the token
String issuer = token.getIssuer();

12.4.4 署名なしのJWTトークンのシリアライズ

JWTトークンにデジタル署名する必要がない場合は、署名なしでトークンをシリアライズできます。

次に例を示します。

JwtToken jwtToken = new JwtToken();
jwtToken.setType(JwtToken.JWT);
jwtToken.setIssuer("my.example.com");
jwtToken.setPrincipal("john.doe");
String jwtString = jwtToken.serializeUnsigned();

12.5 Oracle JSON Web Token Java APIのリファレンス

Oracle JSON Web Token APIで利用可能なクラスとメソッドについては、『Oracle Fusion Middleware Oracle Security Developer Tools Java APIリファレンス』を参照してください。

このガイドには、次のリンクからアクセスできます。

Oracle Fusion Middleware Oracle Security Developer Tools Java APIリファレンス