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でエンコードされた値になります。
関連項目:
JSON Web Token IETFのドラフト・ドキュメントは、http://tools.ietf.org/html/draft-jones-json-web-token-05
にあります。
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 Security Developer ToolsとJava Development Kit (JDK)をインストールし、必要なすべてのjarファイルおよびclassファイルへのCLASSPATH変数を設定します。
Oracle Security Developer Toolsは、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.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.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リファレンス