外部セキュリティー・トークン・サービス (STS) から、sender-vouches サブジェクト確認方式を使用して SAML トークンを要求することができます。SAML sender-vouches トークンを取得した後、Java™ API for XML-Based Web Services (JAX-WS) プログラミング・モデルおよび Web Services
Security API (WSS API) を使用して、それらのトークンをトランスポート・レベルで保護された Web サービス要求メッセージで送信することができます。
始める前に
この作業では、JAX-WS プログラミング・モデル、WSS API インターフェース、SAML の概念、SSL トランスポート保護、および Web サービスの設定を構成および管理するためのポリシー・セットの使用について、ユーザーが十分な知識を持っていることが前提になります。
このタスクについて
sender-vouches サブジェクト確認方式の SAML トークンを外部 STS に要求し、WSS API を使用して、
その SAML トークンをトランスポート・レベルで保護された Web サービス要求メッセージで Web サービス・クライアントから送信することができます。
このタスクで使用される Web サービス・クライアント・アプリケーションは、ダウンロードで使用可能な JaxWSServicesSamples サンプル・アプリケーションに含まれているクライアント・コードの変更版です。
サンプルのコード例については「手順」セクションで説明します。
すぐに使用できる完全な Web サービス・クライアント・サンプルが提供されています。
手順
- Web サービス・プロバイダーを呼び出すために使用する Web サービス・クライアントを特定し、取得します。
このクライアントを使用して、
プログラムで WSS API を使用することによって SAML トークンを SOAP 要求メッセージに
挿入します。
この手順で使用される Web サービス・クライアントは、JaxWSServicesSamples Web サービス・サンプル・アプリケーションに含まれるクライアント・コードの変更版です。
サンプル Web サービス・クライアントを取得し、
プログラムで Web Services Security API を使用して SOAP 要求メッセージに SAML sender-vouches トークンを渡すように変更するには、以下のステップを実行します。
- JaxWSServicesSamples サンプル・アプリケーションをダウンロードします。 JaxWSServicesSamples サンプルは、デフォルトではインストールされません。
- JaxWSServicesSamples クライアント・コードを取得します。
例を示すため、この手順では、JaxWSServicesSamples サンプルに含まれている Echo シン・クライアント・サンプル
の変更版を使用します。
Web サービス Echo シン・クライアント・サンプル・ファイル SampleClient.java は、src¥SampleClientSei¥src¥com¥ibm¥was¥wssample¥sei¥cli ディレクトリーにあります。
サンプル・クラス・ファイルは、WSSampleClientSei.jar ファイルに含まれています。
JaxWSServicesSamples.ear エンタープライズ・アプリケーションおよびそれをサポートする Java アーカイブ (JAR) ファイルは、JaxWSServicesSamples サンプル・アプリケーション内の installableApps ディレクトリーにあります。
- アプリケーション・サーバーに JaxWSServicesSamples.ear ファイルをデプロイします。 JaxWSServicesSamples.ear ファイルをデプロイしたら、サンプル Web サービス・クライアント・コードを、サンプル・アプリケーションに対してテストする準備ができたことになります。
Web サービス・クライアント・サンプルを使用する代わりに、
ご使用の Web サービス・クライアント・アプリケーションの WSS API を使用して、プログラムで SOAP 要求メッセージの SAML トークンを渡すためにコード・スニペットを追加することもできます。この手順中の例では JAX-WS Web サービス・シン・クライアント
が使用されていますが、管理対象クライアントを使用することもできます。
- SAML20 Bearer WSHTTPS default ポリシー・セット
または SAML11 Bearer WSHTTPS default ポリシー・セットのいずれかのコピーを作成します。
ポリシー・セットのコピーに名前を
付けます。例えば、SAML20 SenderVouches
WSHTTPS または SAML11 SenderVouches WSHTTPS のような名前を付けると、この新しいポリシー・セット
が sender-vouches 確認方式を使用することを識別しやすくなります。
サブジェクト確認方式はポリシー内ではなくバインディング構成に指定されるため、
この新しいポリシー・ファイルには何も変更を加える必要はありません。
この新しいポリシー・ファイル内で、ポリシー ID は SAMLToken20Bearer または SAMLToken11Bearer のいずれかになっています。名前そのものが説明になるように、SAMLToken20Bearer ポリシー ID を SAMLToken20SV に変更するか、
または SAMLToken11Bearer ポリシー ID を SAMLToken11SV に変更して
ください。ポリシーの ID を変更しても、適用されるポリシーの内容は何も変わりませんが、
適切な説明を表す ID を追加すると、これらのポリシー ID が sender-vouches 確認方式を使用することの識別に役立ちます。
これらのポリシーの設定を表示する場合は、
管理コンソールを使用して以下の操作を行います。
- をクリックします。
- 「ポリシー」テーブルで「WS-Security」ポリシーをクリックします。
- 「メイン・ポリシー」リンクまたは「ブートストラップ・ポリシー」リンクをクリックします。
- 「ポリシーの詳細 (Policy Details)」セクションの「要求トークン・ポリシー」をクリック
します。
- この新しい SAML20 SenderVouches WSHTTPS または SAML11 SenderVouches WSHTTPS ポリシー・セットを Web サービス・プロバイダー・アプリケーションに関連付けます。 このポリシー・セットを Web サービス・プロバイダー・アプリケーションに関連付ける方法について詳しくは、『SAML sender-vouches トークン用のクライアントおよびプロバイダーのバインディングの構成』を参照してください。
- SAML Bearer Provider sample default 汎用バインディングのコピーを作成します。
- このデフォルト・ポリシー・セットの新しいコピーに、例えば SAML Sender-vouches provider binding のような、sender-vouches を含む名前を付けます。
- SAML11 または SAML20 トークン・コンシューマーのコールバック・ハンドラーで、
該当する SAML トークン・バージョン用のトークン・コンシューマー構成の confirmationMethod プロパティーの値を sender-vouches に変更します。 カスタム・プロパティー trustStoreType、trustStorePassword、
trustStorePath が、STS 署名者証明書が含まれるトラストストアに対応していることを確認してください。
保証の要件を満たすように sender-vouches バインディングを変更する
方法について詳しくは、『SAML sender-vouches トークン用のクライアントおよびプロバイダーのバインディングの構成』を
参照してください。
- 新しいプロバイダー・バインディングを JaxWSServicesSamples プロバイダー・サンプルに
割り当てます。 SAML sender-vouches Provider sample, default 汎用バインディングを
Web サービス・プロバイダー・アプリケーションに割り当てる方法について詳しくは、
『SAML sender-vouches トークン用のクライアントおよびプロバイダーのバインディングの構成』を
参照してください。
- Web サービス・プロバイダー SSL 構成属性 clientAuthentication を使用可能にして、X.509 クライアント証明書認証を必要とするようにします。
clientAuthentication 属性は、SSL クライアント認証が必要かどうかを決定します。clientAuthentication 属性を
指定するには、管理コンソールを使用して以下の操作を行います。
- をクリックします。
- インバウンド・トポロジーにある「WC_defaulthost_secure」リンクをクリックします。
- 「関連項目」にある「SSL_configurations」リンクをクリックします。
- 「NodeDefaultSSLSettings」リソースを選択します。
- 「保護品質 (QoP) 設定」リンクをクリックします。
- メニューから「必要」を選択して、クライアント認証を指定します。
clientAuthentication 属性の構成について詳しくは、
『Secure Sockets Layer 構成の作成』を参照してください。
- SSL トランスポート・レベルのメッセージ保護を使用することを指定します。 以下の JVM プロパティーを使用して、STS に対する SAML トークン要求を SSL を使用して保護することを指定します。
-Dcom.ibm.SSL.ConfigURL=file:profile_root¥properties¥ssl.client.props
あるいは、次の例のように、サンプル・クライアント・コード内で Java システム・プロパティーを使用して、SSL 構成ファイルを定義できます。System.setProperty("com.ibm.SSL.ConfigURL", "file:profile_root/properties/ssl.client.props");
- Thin Client for JAX-WS JAR ファイルをクラスパスに追加します。 app_server_root/runtimes/com.ibm.jaxws.thinclient_8.5.0.jar ファイルをクラスパスに追加します。この JAR ファイルのクラスパスへの追加について詳しくは、『Web サービス対応クライアントのテスト』を参照してください。
- 外部 STS から SAML トークンを要求します。 以下のコード・スニペットは、SAML sender-vouches トークンを要求する方法を示しています。
この例では、外部 STS が、UsernameToken を受け取って検証した後で sender-vouches を使用して SAML 1.1トークンを発行するように構成されていることを前提としています。
//Request the SAML Token from external STS
WSSFactory factory = WSSFactory.getInstance();
String STS_URI = "https://externalstsserverurl:port/TrustServerWST13/services/RequestSecurityToken";
String ENDPOINT_URL = "http://localhost:9080/WSSampleSei/EchoService";
WSSGenerationContext gencont1 = factory.newWSSGenerationContext();
WSSConsumingContext concont1 = factory.newWSSConsumingContext();
HashMap<Object, Object> cbackMap1 = new HashMap<Object, Object>();
cbackMap1.put(SamlConstants.STS_ADDRESS, STS_URI);
cbackMap1.put(SamlConstants.SAML_APPLIES_TO, ENDPOINT_URL);
cbackMap1.put(SamlConstants.TRUST_CLIENT_WSTRUST_NAMESPACE, "http://docs.oasis-open.org/ws-sx/ws-trust/200512");
cbackMap1.put(SamlConstants.TRUST_CLIENT_COLLECTION_REQUEST, "false");
cbackMap1.put(SamlConstants.TOKEN_TYPE, WSSConstants.SAML.SAML11_VALUE_TYPE);
cbackMap1.put(SamlConstants.CONFIRMATION_METHOD, "sender-vouches");
SAMLGenerateCallbackHandler cbHandler1 = new SAMLGenerateCallbackHandler(cbackMap1);
// Add UNT to trust request
UNTGenerateCallbackHandler utCallbackHandler = new UNTGenerateCallbackHandler("testuser", "testuserpwd");
SecurityToken ut = factory.newSecurityToken(UsernameToken.class, utCallbackHandler);
gencont1.add(ut);
cbHandler1.setWSSConsumingContextForTrustClient(concont1);
cbHandler1.setWSSGenerationContextForTrustClient(gencont1);
SecurityToken samlToken = factory.newSecurityToken(SAMLToken.class, cbHandler1, "system.wss.generate.saml");
System.out.println("SAMLToken id = " + samlToken.getId());
- WSSFactory newSecurityToken メソッドを使用して、
外部 STS から SAML トークンを要求する方法を指定します。
SAML トークンを作成するため、以下のメソッドを
指定してください。
WSSFactory newSecurityToken(SAMLToken.class, callbackHandler, "system.wss.generate.saml")
SAML トークンの要求には、Java セキュリティー
権限 wssapi.SAMLTokenFactory.newSAMLToken が必要です。ポリシー・ツールを
使用して、以下のポリシー・ステートメントを Java セキュリティー・ポリシー・ファイルまたは
アプリケーション・クライアント was.policy ファイルに追加してください。
permission java.security.SecurityPermission "wssapi.SAMLTokenFactory.newSAMLToken"
SAMLToken.class パラメーター
は、作成するセキュリティー・トークンのタイプを指定します。
callbackHandler オブジェクトには、要求する SAMLToken の特性を定義するパラメーターと、
STS に到達し SAML トークンを取得するために必要なその他のパラメーターが含まれます。SAMLGenerateCallbackHandler オブジェクトは、次の表に示す構成パラメーターを指定します。
表 1. SAMLGenerateCallbackHandler プロパティー. この表は、
sender-vouches 確認方式を使用する SAMLGenerateCallbackHandler オブジェクトの
構成パラメーターを示します。プロパティー |
説明 |
必須 |
SamlConstants.CONFIRMATION_METHOD |
sender-vouches 確認方式の使用を指定します。 |
はい |
SamlConstants.TOKEN_TYPE |
トークン・タイプを指定します。 Web サービス・クライアントにポリシー・セットが関連付けられている場合、Web Services Security ランタイム環境はこのプロパティーを使用しません。
tokenGenerator バインディング構成の valueType 属性を使用して、
トークン・タイプの値を指定します。
この手順中の例では SAML 1.1 トークンが使用されていますが、WSSConstants.SAML.SAML20_VALUE_TYPE 値を使用することもできます。
|
はい |
SamlConstants.STS_ADDRESS |
セキュリティー・トークン・サービスのアドレスを指定します。
このタスク・トピックで使用されている例では、
このプロパティーの値は https に設定されており、
SSL を使用して SAML トークン要求を保護することを指定しています。
STS による SAML トークン要求
を SSL を使用して保護できるようにするためには、-Dcom.ibm.SSL.ConfigURL プロパティーを設定する必要があります。
|
はい |
SamlConstants.SAML_APPLIES_TO |
SAML トークンを使用するためのターゲット STS アドレスを指定します。 |
いいえ |
SamlConstants.TRUST_CLIENT_COLLECTION_REQUEST |
STS から要求するトークンが、
RequestSecurityToken (RST) エレメントに含まれる単一のトークンであるか、
または単一の RequestSecurityTokenCollection (RSTC) エレメントに含まれる RST エレメントの
コレクション内の複数のトークンであるかを指定します。 デフォルトの動作では、
RequestSecurityToken (RST) エレメントに含まれる単一のトークンを STS から要求します。
このプロパティーに値 true を指定すると、
単一の RequestSecurityTokenCollection (RSTC) エレメントに含まれる RST エレメントの
コレクション内の複数のトークンを STS から要求することを示します。
|
いいえ |
SamlConstants.TRUST_CLIENT_WSTRUST_NAMESPACE |
WS-Trust 要求に組み込まれる WS-Trust 名前空間を指定します。 デフォルト値は WSTrust 1.3 です。
|
いいえ |
WSSGenerationContext インスタンスおよび WSSConsumingContext インスタンス
も SAMLGenerateCallbackHandler オブジェクトに設定されています。WSSGenerationContext インスタンスには、STS に送信したい UsernameToken を作成するための情報が指定された UNTGenerateCallbackHandler オブジェクトが含まれている必要があります。
system.wss.generate.saml パラメーターは、SAML トークンの作成に使用される Java Authentication
and Authorization Service (JAAS) ログイン・モジュールを指定します。次の例のように、必要な JAAS ログイン構成を含んでいる JAAS 構成ファイルを定義するため、JVM プロパティー
を指定する必要があります。
-Djava.security.auth.login.config=profile_root/properties/wsjaas_client.conf
あるいは、次の例のように、
サンプル・クライアント・コード内で Java システム・プロパティー
を設定することによって、JAAS ログイン構成ファイルを指定できます。
System.setProperty("java.security.auth.login.config", "profile_root/properties/wsjaas_client.conf");
- 作成された SAML トークンのトークン ID を取得します。
以下のステートメントを、作成した SAML トークンの簡単なテストとして使用できます。
System.out.println("SAMLToken id = " + samlToken.getId())
タスクの結果
sender-vouches 確認方式の SAML トークンを外部 STS から要求しました。トークンの取得後に、JAX-WS プログラミング・モデルおよび WSS API を使用して、トランスポートが保護された Web サービス要求メッセージでトークンを送信しました。
例
以下のコード例は、外部 STS に SAML トークンを要求し、
その SAML トークンをトランスポート・レベルで保護された Web サービス要求メッセージで送信する方法を示す、
すぐに使用できる完全な Web サービス・クライアント・アプリケーションです。このサンプル・コードは、上記手順の各ステップを示したものです。
/**
* The following source code is sample code created by IBM Corporation.
* This sample code is provided to you solely for the purpose of assisting you in the
* use of the technology. The code is provided 'AS IS', without warranty or condition of
* any kind. IBM shall not be liable for any damages arising out of your use of the
* sample code, even if IBM has been advised of the possibility of such damages.
*/
package com.ibm.was.wssample.sei.cli;
import com.ibm.was.wssample.sei.echo.EchoService12PortProxy;
import com.ibm.was.wssample.sei.echo.EchoStringInput;
import com.ibm.websphere.wssecurity.wssapi.WSSFactory;
import com.ibm.websphere.wssecurity.wssapi.WSSGenerationContext;
import com.ibm.websphere.wssecurity.wssapi.WSSConsumingContext;
import com.ibm.websphere.wssecurity.wssapi.WSSTimestamp;
import com.ibm.websphere.wssecurity.callbackhandler.SAMLGenerateCallbackHandler;
import com.ibm.websphere.wssecurity.callbackhandler.UNTGenerateCallbackHandler;
import com.ibm.websphere.wssecurity.wssapi.token.UsernameToken;
import com.ibm.websphere.wssecurity.wssapi.token.SAMLToken;
import com.ibm.websphere.wssecurity.wssapi.token.SecurityToken;
import com.ibm.wsspi.wssecurity.core.token.config.WSSConstants;
import com.ibm.wsspi.wssecurity.saml.config.SamlConstants;
import java.util.Map;
import java.util.HashMap;
import javax.xml.ws.BindingProvider;
public class SampleSamlSVClient {
private String urlHost = "localhost";
private String urlPort = "9443";
private static final String CONTEXT_BASE = "/WSSampleSei/";
private static final String ECHO_CONTEXT12 = CONTEXT_BASE+"EchoService12";
private String message = "HELLO";
private String uriString = "https://" + urlHost + ":" + urlPort;
private String endpointURL = uriString + ECHO_CONTEXT12;
private String input = message;
/**
* main()
*
* see printusage() for command-line arguments
*
* @param args
*/
public static void main(String[] args) {
SampleSamlSVClient sample = new SampleSamlSVClient();
sample.CallService();
}
/**
* CallService Parms were already read. Now call the service proxy classes.
*
*/
void CallService() {
String response = "ERROR!:";
try {
System.setProperty("com.ibm.SSL.ConfigURL", "profile_root//properties/ssl.client.props");
System.setProperty("java.security.auth.login.config", "profile_root/properties/wsjaas_client.conf ");
//Request the SAML Token from external STS
WSSFactory factory = WSSFactory.getInstance();
String STS_URI = "https://externalstsserverurl:port/TrustServerWST13/services/RequestSecurityToken";
String ENDPOINT_URL = "http://localhost:9080/WSSampleSei/EchoService";
WSSGenerationContext gencont1 = factory.newWSSGenerationContext();
WSSConsumingContext concont1 = factory.newWSSConsumingContext();
HashMap<Object, Object> cbackMap1 = new HashMap<Object, Object>();
cbackMap1.put(SamlConstants.STS_ADDRESS, STS_URI);
cbackMap1.put(SamlConstants.SAML_APPLIES_TO, ENDPOINT_URL);
cbackMap1.put(SamlConstants.TRUST_CLIENT_WSTRUST_NAMESPACE, "http://docs.oasis-open.org/ws-sx/ws-trust/200512");
cbackMap1.put(SamlConstants.TRUST_CLIENT_COLLECTION_REQUEST, "false");
cbackMap1.put(SamlConstants.TOKEN_TYPE, WSSConstants.SAML.SAML11_VALUE_TYPE);
cbackMap1.put(SamlConstants.CONFIRMATION_METHOD, "sender-vouches");
SAMLGenerateCallbackHandler cbHandler1 = new SAMLGenerateCallbackHandler(cbackMap1);
// Add UNT to trust request
UNTGenerateCallbackHandler utCallbackHandler = new UNTGenerateCallbackHandler("testuser", "testuserpwd");
SecurityToken ut = factory.newSecurityToken(UsernameToken.class, utCallbackHandler);
gencont1.add(ut);
cbHandler1.setWSSConsumingContextForTrustClient(concont1);
cbHandler1.setWSSGenerationContextForTrustClient(gencont1);
SecurityToken samlToken = factory.newSecurityToken(SAMLToken.class, cbHandler1, "system.wss.generate.saml");
System.out.println("SAMLToken id = " + samlToken.getId());
// Initialize web services client
EchoService12PortProxy echo = new EchoService12PortProxy();
echo._getDescriptor().setEndpoint(endpointURL);
// Configure SOAPAction properties
BindingProvider bp = (BindingProvider) (echo._getDescriptor().getProxy());
Map<String, Object> requestContext = bp.getRequestContext();
requestContext.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, endpointURL);
requestContext.put(BindingProvider.SOAPACTION_USE_PROPERTY, Boolean.TRUE);
requestContext.put(BindingProvider.SOAPACTION_URI_PROPERTY, "echoOperation");
// Initialize WSSGenerationContext
WSSGenerationContext gencont = factory.newWSSGenerationContext();
gencont.add(samlToken);
// Add timestamp
WSSTimestamp timestamp = factory.newWSSTimestamp();
gencont.add(timestamp);
gencont.process(requestContext);
// Build the input object
EchoStringInput echoParm =
new com.ibm.was.wssample.sei.echo.ObjectFactory().createEchoStringInput();
echoParm.setEchoInput(input);
System.out.println(">> CLIENT: SEI Echo to " + endpointURL);
// Prepare to consume timestamp in response message
WSSConsumingContext concont = factory.newWSSConsumingContext();
concont.add(WSSConsumingContext.TIMESTAMP);
concont.process(requestContext);
// Call the service
response = echo.echoOperation(echoParm).getEchoResponse();
System.out.println(">> CLIENT: SEI Echo invocation complete.");
System.out.println(">> CLIENT: SEI Echo response is: " + response);
} catch (Exception e) {
System.out.println(">> CLIENT: ERROR: SEI Echo EXCEPTION.");
e.printStackTrace();
}
}
}
この Web サービス・クライアント・アプリケーション・サンプルが正しく実行された場合、次のようなメッセージを受け取ります。
SAMLToken id = _6CDDF0DBF91C044D211271166233407
Retrieving document at 'file:profile_root/.../wsdl/'.
>> CLIENT: SEI Echo to http://localhost:9443/WSSampleSei/EchoService12
>> CLIENT: SEI Echo invocation complete.
>> CLIENT: SEI Echo response is: SOAP12==>>HELLO