Web 高速ログオンのプラグインの作成
HATS の Web 高速ログオン機能では、ネットワーク・セキュリティー信任状を受け入れ、これらを使用してホスト信任状を生成し、使用します。これによりユーザーは、ホスト・ログオン画面のナビゲート要件を意識する必要がなくなります。Web 高速ログオンでは、この処理を実行するために、次の 2 種類のプラグインを使用します。
- ネットワーク・セキュリティー・プラグイン は、ネットワーク・セキュリティー・アプリケーションからユーザーの信任状を検索します。
- 信任状マッパー・プラグイン は、ネットワーク・セキュリティー・プラグインから戻された信任状を使用してホスト・ユーザー ID を検索し、ホスト・アクセス信任状を獲得します。
HATS には、ネットワーク・セキュリティー・プラグインおよび信任状マッパー・プラグインがいくつか用意されています。HATS の提供するプラグインがユーザーの要求に合わない場合は、独自のプラグインを作成して、それを Web 高速ログオンに組み込むことができます。例えば、信任状が保管されるさまざまなタイプのデータベースにアクセスする必要がある場合は、独自のプラグインを作成できます。
Web 高速ログオンのカスタム・プラグインの作成
Web 高速ログオンでは、ネットワーク・ユーザー ID およびホスト・アクセス信任状を提供する処理をプラグインに依存しています。Web 高速ログオンは次のセクションで説明する Java™ インターフェースを通じてこれらのプラグインと対話します。
Web 高速ログオン は、HATS Web プロジェクトでは、エンタープライズ・アーカイブ (.ear) ファイルのレベルで実装され、HATS ポートレット・プロジェクトでは、Web アーカイブ (.war) ファイルのレベルで実装されます。各エンタープライズ・アーカイブ・ファイルまたは Web アーカイブ・ファイルにプラグインを適宜入れる必要があります。独自のプラグインを作成するには、以下の手順を実行します。
- Rational® SDP で、プラグインを保持する Java プロジェクトを作成します。この Java プロジェクトのクラスパスには、HATS ファイルが次の順序で設定されていることを確認してください。
- hatscommon.jar
- hodwel.jar
これらのファイルは、HATS Toolkit の共通プラグイン (キャッシュ) ディレクトリー (common
plug-ins directory/plugins/com.ibm.hats.core_x.x.x.yearxxxxxxxx/lib。ここで、x.x.x はバージョン・レベル、yearxxxxxxxx は HATS のビルド・レベル) および HATS エンタープライズ・アーカイブ・ファイルのルート・ディレクトリーにあります。
- この章で説明する API を使用して、プラグインをコード化します。
- Java プロジェクトから Java Archive (.jar) ファイルを作成します。HATS Web プロジェクトの場合は、この .jar ファイルを使用する各 .ear ファイルのファイル・システムに、.jar ファイルをエクスポートします。HATS ポートレット・プロジェクトの場合は、この .jar ファイルを使用する HATS ポートレット・プロジェクトの Web Content/WEB-INF/lib ディレクトリーに、.jar ファイルをエクスポートします。
- Java Archive を Web-Content/META-INF に配置された MANIFEST.MF に追加します。
- Web 高速ログオンを使用するように接続を構成し、カスタム・プラグインを使用するように Web 高速ログオンを構成します。Web 高速ログオンの計画および構成については、「HATS ユーザーと管理者のガイド」を参照してください。
Web 高速ログオンのプラグイン・インターフェース
すべてのプラグインには、以下の Java インターフェースを実装する必要があります。
com.ibm.eNetwork.security.sso.cms.CMInterface
CMInterface インターフェースには、以下のメソッドが含まれます。
- public int Init(Properties p, String
id)
- このメソッドは、プラグインの初期化に使用されます。プラグインの初期化に必要な構成パラメーターは、プロパティー・オブジェクト・パラメーターによって受け渡されます。構成パラメーターは HATS Toolkit で構成され、Web 高速ログオン構成ファイル hatswelcfg.xml に保管されます。id パラメーターは、HATS が生成するプラグインのシンボル名です。この値は、プラグインの複数インスタンスが実行中の場合に、プラグインのインスタンスを修飾するのに使用されます。このメソッドは、表 6 にリストされた SSOConstants 値のいずれかを戻します。
- public void Destroy()
- このメソッドは、HATS のシャットダウン時に呼び出されます。
- public CMResponse CMSGetUserCredentials(CMRequest
req)
- HATS は、要求に応答するプラグインを選択したときに、このメソッドを呼び出します。プラグインがネットワーク・セキュリティー・タイプの場合は、そのプラグインがユーザーのネットワーク・ユーザー ID を戻すと予想されます。プラグインがホスト・ユーザー信任状タイプの場合は、このメソッドがユーザーのホスト信任状を戻す必要があります。このメソッドで使用する CMResponse オブジェクトおよび CMRequest オブジェクトについては、この後で説明します。
以下のメソッドは、プラグインの識別および選択に必要となります。
- public String getName();
- このメソッドは、プラグインを識別するストリングを戻します。
- public String getDescription();
- このメソッドは、プラグインの目的と機能についての情報を含むストリングを戻します。
- public String getAuthor();
- このメソッドは、プラグインを作成した会社または担当者を識別する場合に必要になります。
- public String[] getParameters();
- このメソッドは、このプラグインの構成に使用されるパラメーター名を含むストリング配列を戻します。これらのトークンは、HATS Toolkit の Web 高速ログオン・エディターのパラメーター・セクションで指定される鍵です。パラメーターが Init() メソッドに渡されるときは、HATS によって生成されたプラグインのシンボル名 (id) が各パラメーター名の前に付加されます。構成でパラメーターを必要としない場合、このメソッドはヌルを戻します。
- public Properties getParameterInfo(String
strParm);
- パラメーター・トークンが指定されると、このメソッドは、指定されたパラメーターのプロパティーのリストを持つプロパティー・オブジェクトを戻します。使用可能なプロパティーは以下のとおりです。
- cmiDefaultValue。このプロパティーには、指定されたパラメーターのデフォルト値が含まれます。このプロパティーはオプションです。このプロパティーが指定されない場合、そのパラメーターにはデフォルト値はありません。
- cmiEncrypted。このプロパティーは、パラメーターを暗号化するかどうかを決定します。有効な値は、ストリング true および false です。このパラメーターを true に設定した場合は、Web 高速ログオンで提供される暗号化および暗号化解除メソッドを使用する必要があります。これらのメソッドについては、プラグイン・パラメーター・ストリングの暗号化および暗号化解除を参照してください。
- cmiRequired。このプロパティーは、プラグインの初期化にパラメーターが必要かどうかを示します。有効な値は、ストリング true および false です。
com.ibm.eNetwork.security.sso.CMRequest
HATS は、要求情報をこのオブジェクトで渡すことにより、信任状を要求します。メンバーおよびメソッドは以下のとおりです。
メンバー:
- ID (ホスト ID またはネットワーク ID)
- ホスト・アプリケーション ID
- ホスト宛先アドレス
- 認証タイプ
- HTTP サーブレット要求オブジェクト
メソッド:
- public CMRequest()
-
- public CMRequest(String id, String applID,
String hostAddr, int authType, HttpServletRequest httpRequest)
-
- public String getID()
-
- public void setID(String id)
-
- public String getHostApplID()
-
- public void setHostApplID(String applID)
-
- public String getHostDestination()
-
- public void setHostDestination(String
hostAddr)
-
- public int getAuthType()
- authtype に使用可能な値は以下のとおりです。
public static final int SSO_AUTHTYPE_ALL = 0xFFFF;
public static final int SSO_AUTHTYPE_3270HOST = 0x0001;
public static final int SSO_AUTHTYPE_5250HOST = 0x0002;
public static final int SSO_AUTHTYPE_VTHOST = 0x0004;
上記の値は、com.ibm.eNetwork.security.sso.SSOConstants クラスに定義されています。これらの値を使用する場合は、このクラスをインポートする必要があります。
- public void setAuthType(int authType)
- authtype に使用可能な値は以下のとおりです。
public static final int SSO_AUTHTYPE_ALL = 0xFFFF;
public static final int SSO_AUTHTYPE_3270HOST = 0x0001;
public static final int SSO_AUTHTYPE_5250HOST = 0x0002;
public static final int SSO_AUTHTYPE_VTHOST = 0x0004;
上記の値は、com.ibm.eNetwork.security.sso.SSOConstants クラスに定義されています。これらの値を使用する場合は、このクラスをインポートする必要があります。
- public HttpServletRequest getHttpRequestObject()
-
- public void setHttpRequestObject(HttpServletRequest
httpRequest)
-
com.ibm.eNetwork.security.sso.CMResponse
プラグインは、応答をこのオブジェクトに組み込んで、HATS に戻します。メンバーおよびメソッドは以下のとおりです。
メンバー:
- 状況コード
- ID (ホスト ID またはネットワーク ID)
- ユーザー信任状 (パスワードまたはパスチケット)
メソッド:
- public CMResponse()
-
- public CMResponse(Object id, Object
password, int status)
-
- public int getStatus()
-
- public void setStatus(int status)
-
信任状マッパー・プラグインは、status エレメントを使用して、戻り値の状況を提供します。プラグイン照会がなんらかの理由で失敗すると、このフィールドはその失敗を Web 高速ログオンに報告します。失敗コードは、com.ibm.eNetwork.security.sso.SSOConstants クラスに定義されています。表 6に、状況コードの数値、定数ストリング、および定義を示します。
表 6. 状況コード定義
| 状況コード |
定数値 |
説明 |
| 0 |
SSO_CMR_SUCCESS |
成功 |
| 1 |
SSO_CMR_UNKNOWN_STATUS_CODE |
不明な状況コード |
| 2 |
SSO_CMR_CREDENTIAL_MAPPER _NOT_FOUND |
信任状マッパーが見つからない |
| 3 |
SSO_CMR_INVALID_WEB_ID |
無効な Web ID |
| 4 |
SSO_CMR_INVALID_APPL_ID |
無効なアプリケーション ID |
| 5 |
SSO_CMR_INVALID_SERVER_ADDR |
無効なサーバー・アドレス |
| 6 |
SSO_CMR_DATABASE_CONNECTION_ ERROR |
データベース接続エラー |
| 7 |
SSO_CMR_USER_ID_NOT_FOUND_ IN_DB |
データベースにユーザー ID が見つからない |
| 8 |
SSO_CMR_EXCEPTION |
例外 |
| 9 |
SSO_CMR_INVALID_USER_IDU |
無効なユーザー ID |
| 10 |
SSO_CMR_PASSTICKET_ERROR |
パスチケット・エラー |
| 11 |
SSO_CMR_TIMEOUT |
タイムアウト |
| 12 |
SSO_CMR_UNEXPECTED_DCAS_RC |
予期しない DCAS 戻りコード |
| 13 |
SSO_CMR_API_NOT_SUPPORTED |
API はサポートされない |
| 14 |
SSO_CMR_BAD_URL |
無効な URL |
| 15 |
SSO_CMR_UNABLE_TO_PARSE_ RESPONSE |
応答を構文解析できない |
| 16 |
SSO_CMR_LOCAL_USERID_NOT_ AVAILABLE |
ローカル・ユーザー ID は使用できない |
| 17 |
SSO_CMR_DUPLICATE_XML_TAGS |
XML タグの重複 |
| 18 |
SSO_CMR_CLIENT_EXCEPTION |
信任状要求の処理中に例外が発生 |
| 19 |
SSO_CMR_NO_NETWORK_SECURITY_ PLUGIN |
ネットワーク・セキュリティー・プラグインが Web 高速ログオンに定義されていない |
- public Object getID()
-
- public String getIDasString()
-
- public void setID(Object id)
- CMSGetUserCredentials() メソッドでこのメソッドを使用すれば、ネットワーク・セキュリティー・プラグインからネットワーク・ユーザー ID を戻すか、あるいは信任状マッパー・プラグインからホスト・ユーザー ID を戻すことができます。
- public Object getPassword()
-
- public String getPasswordasString()
-
- public void setPassword(Object password)
-
ネットワーク・セキュリティー・プラグインの作成
HATS には、Tivoli® Access Manager と WebSphere® Portal のそれぞれにネットワーク・セキュリティー・プラグインがあります。これらのプラグインを使用しない場合は、独自のプラグインを作成できます。
ネットワーク・セキュリティー・プラグインの機能は、ユーザーのネットワーク ID を獲得することです。この ID は、着信 HTTP 要求オブジェクトにある HTTP ヘッダーから収集できます。ネットワーク ID の獲得方法は、使用するネットワーク・セキュリティー・アプリケーションによって異なります。詳細は、使用するネットワーク・セキュリティー・アプリケーションの資料を参照してください。
信任状マッパー・プラグインの作成
HATS には、いくつかの信任状マッパー・プラグインがあります。これらを使用しない場合は、独自のプラグインを作成できます。
信任状マッパー・プラグインの機能は、ユーザーのネットワーク ID (および必要に応じてアプリケーション ID) を取得し、適切なホスト信任状を取得することです。Web 高速ログオンの実装では、この処理中に Java Database Connectivity (JDBC) によるアクセスが可能なデータベースを経由してユーザーのネットワーク ID をホスト ID にマップします。ただし、この処理を他の方法 (LDAP など) で行いたい場合があります。そのような理由により、独自の信任状マッパー・プラグインを作成したい場合があります。
DCAS/JDBC プラグインでは、HATS は z/OS® ログインを自動化します。この自動化のためにユーザーのネットワーク ID をホスト ID に関連付けて、アプリケーション ID とともにホスト ID を取得し、RACF 生成のパスチケットを z/OS のコンポーネントである Digital Certificate Access Server (DCAS) から取得する処理が行われます。このパスチケットは、ユーザーがホストにサインオンするときに使用されます。使用環境によっては、提供されるプラグインの JDBC 関連アスペクトを使用したくない場合があります。このため、HATS には DCAS API が用意されています。この API を使用すれば、RACF 生成のパスチケットにアクセスできます。
サンプル Web 高速ログオン・プラグイン
Web 高速ログオン・プラグインのサンプルを含み、ネットワーク・セキュリティー・プラグインまたは信任状マッパー・プラグインのいずれかをコード化する方法を示す、付録B. Web 高速ログオン・プラグインのサンプルを参照してください。
プラグイン・パラメーター・ストリングの暗号化および暗号化解除
Web 高速ログオンには、プラグイン・パラメーター・ストリングを暗号化および暗号化解除する com.ibm.eNetwork.security.sso.PasswordCipher というオブジェクトがあります。このオブジェクトには、以下の 2 つのメソッドが含まれます。
- public static String encrypt (String plainText)
- このメソッドは、パラメーターとして受け渡されたストリングを暗号化して戻します。
- public static String decrypt (String cipherText)
- このメソッドは、ストリングを暗号化解除して戻すことにより、暗号化とは逆のプロセスを行います。cipherText が encrypt メソッドを使用して暗号化されたものでない場合は、元の入力ストリングを戻します。
DCAS API オブジェクト
Digital Certificate Access
Server (DCAS) API オブジェクト (DCASClient) は、パスチケット要求をカプセル化します。メンバーおよびメソッドは以下のとおりです。
メンバー:
- ポート番号
- 鍵ストアのファイル名
- 鍵ストアのパスワード
- WellKnownTrustedCAs 使用
- サーバー認証
- トレース・レベル
HATS V7.0 よりも前に、DCAS クライアントのオブジェクトを使用して独自のプラグインを作成している場合は、動作し続けるようにご使用のコードを変更する必要はありません。ただし、HATS V7.0 から新規 API が使用可能になるため、新規プラグインを開発する場合はこれらの API を使用してください。推奨の API は、以下で 推奨 の記号のフラグを立てています。
メソッド:
- Public DCASClient()
- オブジェクト作成時にデフォルトのトレース・レベルとログ・ファイル名を使用する場合は、このコンストラクターを使用します。
- Public DCASClient(int traceLevel, String logFile)
- オブジェクト作成時にトレース・レベルとログ・ファイル名を指定する場合は、このコンストラクターを使用します。
- traceLevel - トレース・レベル (0= なし、1= 最小、2= 通常、3= 最大)
- logFile - トレース・ログ・ファイル名。このパラメーターは HATS では使用しません。トレースは、HATS トレース・ファイルに記録されます。Web 高速ログオンのトレースは、ランタイム・トレース・フラグ trace.RUNTIME で制御します。
- public int Init (String hostAddress, int hostPort, String trustStoreName, String trustStorePassword,
String trustStoreType)
- 推奨
- Public int Init(String dcasAddr, int dcasPort, String keystoreFileName, String keystorePassword)
- このメソッドは、DCASClient オブジェクトの作成後に呼び出されます。これらのパラメーターはオブジェクトに保管され、オブジェクトが存続する間は変更されません。keystoreFileName には、絶対パス名が入ります。
鍵ストア・データベースには、DCAS クライアント証明書と DCAS サーバー証明書が格納されている必要があります。
WellKnownTrustedCAs.p12 またはデフォルトのトラストストアがこれらの証明書に使用されている場合は、keystoreFileName と keystorePassword をヌルに設定します。鍵ストアのパスワードは、パスワードの暗号化ツールを使用して暗号化される必要があります。このパスワードは、オブジェクト内に格納される前に暗号化解除されます。有効な戻りコードについては、SSOConstants オブジェクト内で説明されています。
p12 以外のタイプの鍵ストアが使用されている場合は、代わりに Init(hostAddress, hostPort, trustStoreName, trustStorePassword, trustStoreType) メソッドを使用してください。
鍵ストア・パスワードは、PasswordCipher.encrypt() メソッドを使用して暗号化されている必要があります。暗号化されたパラメーターによってこのパスワードが提供されている (つまり、パラメーターが cmiEncrypted="true" と設定されている) 場合、パスワードは暗号の形式でプラグインに提供されます。暗号化されたパラメーターが提供されない場合は、以下のコードを使用すれば暗号化できます。
import com.ibm.eNetwork.HOD.common.PasswordCipher;
keystorePW = PasswordCipher.encrypt(keystorePW);
有効な戻りコードを、表 6 に示します。
- public void setUseDefaultTrustStore(boolean def)
-
- public void setNoFIPS(boolean nof)
-
- Public void setWellKnownTrustedCAs(boolean
wellKnownCAs)
-
- Public void setServerAuthentication(boolean
serverAuth)
-
- Public CMResponse getPassticket(String hostUserID, String hostApplID, String hostAddr, long timeout)
- このメソッドは、DCASClient オブジェクトの作成および初期化後に、DCAS サーバーからパスチケットを取得するために呼び出されます。パスチケットおよびユーザー ID は、CMResponse オブジェクトに戻されます。呼び出し元は、CMResponse オブジェクトの状況フィールドを検査して、呼び出しが正常に実行されたかどうかを確認する必要があります。呼び出しが正常に実行されると、状況フィールドには SSO_CMR_SUCCESS が設定されます。状況フィールドの有効な値を、表 6 に示します。DCAS との間で SSL クライアント認証接続が確立し、以降のすべてのパスチケット要求に再利用されます。
- hostUserID - パスチケットが要求されているユーザー ID。
- hostApplID - パスチケットが要求されているアプリケーション ID。
- hostAddr - DCAS アドレス。
- timeout - DCAS プロトコルがパスチケットを戻すまでの有効時間でミリ秒で指定。
- Public void Destroy()
- このメソッドは、DCAS 接続をクローズします。