WSS API を使用した自己発行 SAML bearer トークンの送信

bearer サブジェクト確認方式を使用する自己発行 SAML トークンを作成し、その後、 Java™ API for XML-Based Web Services (JAX-WS) プログラミング・モデルおよび Web Services Security API (WSS API) を使用して、それらのトークンを Web サービス要求メッセージで送信することができます。

始める前に

この作業では、JAX-WS プログラミング・モデル、WSS API インターフェース、SAML の概念、および Web サービスの設定を構成および管理するためのポリシー・セットの使用について、ユーザーが十分な知識を持っていることが前提になります。

このタスクについて

Web Services Security プログラミング・インターフェースを使用して bearer サブジェクト確認方式の SAML トークンを SOAP 要求メッセージ内で使用する ように、Web サービス・クライアントを作成できます。これらのプログラミング・インターフェースを Web サービス・クライアントで使用して、bearer サブジェクト確認方式の SAML トークンの使用を指定することは、ポリシー・セットおよびバインディング構成を使用することに代わる方法です。

自己発行 SAML トークンを作成し、その SAML トークンを、Web サービス・クライアントから Web サービス要求メッセージで送信することができます。このタスクで使用される Web サービス・アプリケーション・クライアントは、ダウンロードで入手可能な JaxWSServicesSamples サンプル・アプリケーションに含まれているクライアント・コードに変更を加えたバージョンです。 手順のセクションではサンプルから抜粋したコード・スニペットについて説明していますが、 すぐに使用できる完全な Web サービス・クライアントのサンプルがサンプルのセクションに記載されています。

手順

  1. Web サービス・プロバイダーを呼び出すために使用する Web サービス・クライアントを特定し、取得します。

    このクライアントを使用して、 プログラムで WSS API を使用することによって SAML トークンを SOAP 要求メッセージに 挿入します。

    この手順で使用される Web サービス・クライアントは、JaxWSServicesSamples Web サービス・サンプル・アプリケーションに含まれるクライアント・コードの変更版です。

    サンプル Web サービス・クライアントを取得し、変更することによって、プログラムで WSS API を使用して SOAP 要求メッセージで SAML トークンを渡すための Web Services Security API を追加するには、以下のステップを実行します。

    1. JaxWSServicesSamples サンプル・アプリケーションをダウンロードします。 JaxWSServicesSamples サンプルは、デフォルトではインストールされません。
    2. JaxWSServicesSamples クライアント・コードを取得します。

      例を示すため、この手順では、JaxWSServicesSamples サンプルに含まれている Echo シン・クライアント・サンプル の変更版を使用します。 Web サービス Echo シン・クライアント・サンプル・ファイル SampleClient.java は、src¥SampleClientSei¥src¥com¥ibm¥was¥wssample¥sei¥cli ディレクトリーにあります。 サンプル・クラス・ファイルは、WSSampleClientSei.jar ファイルに含まれています。

      JaxWSServicesSamples.ear エンタープライズ・アプリケーションおよびそれをサポートする Java アーカイブ (JAR) ファイルは、JaxWSServicesSamples サンプル・アプリケーション内の installableApps ディレクトリーにあります。

    3. アプリケーション・サーバーに JaxWSServicesSamples.ear ファイルをデプロイします。 JaxWSServicesSamples.ear ファイルをデプロイしたら、サンプル Web サービス・クライアント・コードを、サンプル・アプリケーションに対してテストする準備ができたことになります。

    Web サービス・クライアント・サンプルを使用する代わりに、 ご使用の Web サービス・クライアント・アプリケーションの WSS API を使用して、プログラムで SOAP 要求メッセージの SAML トークンを渡すためにコード・スニペットを追加することもできます。この手順中の例では JAX-WS Web サービス・シン・クライアント が使用されていますが、管理対象クライアントを使用することもできます。

  2. SAML20 Bearer WSHTTPS default ポリシー・セットを Web サービス・プロバイダーに関連付けます。 このポリシー・セットは、 HTTPS トランスポートを使用してメッセージを保護するために使用されます。SAML20 Bearer WSHTTPS default ポリシー・セット を Web サービス・プロバイダーに関連付ける方法について詳しくは、 『SAML bearer トークン用のクライアントおよびプロバイダーのバインディングの構成』を 参照してください。この手順中の例は、自己発行された SAML トークンを 使用します。プロバイダー・バインディングを構成する際、トラストストア 構成と証明書は、自己発行トークンの署名鍵と一致しなければ なりません。
  3. SAML Bearer Provider sample default 汎用バインディングをサンプル Web サービス・プロバイダーに割り当てます。 SAML Bearer Provider sample default 汎用バインディングを Web サービス・アプリケーションに割り当てる方法について詳しくは、『SAML bearer トークン用のクライアントおよびプロバイダーのバインディングの構成』を参照してください。
  4. 自己発行 SAML トークンを作成します。 以下のコード・スニペットは、 SAML トークンの作成を示します。
    // Create the SAML token.
    			HashMap<Object, Object> map = new HashMap<Object, Object>();
    			map.put(SamlConstants.CONFIRMATION_METHOD, "Bearer");
    			map.put(SamlConstants.TOKEN_TYPE, WSSConstants.SAML.SAML20_VALUE_TYPE);
    			map.put(SamlConstants.SAML_NAME_IDENTIFIER, "Alice");
    			map.put(SamlConstants.SIGNATURE_REQUIRED, "true");			
    			SAMLGenerateCallbackHandler callbackHandler = new SAMLGenerateCallbackHandler(map);				            
    callbackHandler.setWSSGenerationContextForTrustClient(gencont);
    SecurityToken samlToken = factory.newSecurityToken(SAMLToken.class, callbackHandler, "system.wss.generate.saml");
    
    System.out.println("SAMLToken id = " + samlToken.getId());
    1. CallService() メソッドを使用することにより、自己発行 SAML トークンを使用してターゲット Web サービス・プロバイダーを呼び出すために必要な Web Services Security 構成パラメーターを指定します。

      CallService() メソッドにより、Web Services Security ランタイム環境が com.ibm.websphere.wssecurity.wssapi.WSSGenerationContext カスタム・プロパティーを通じて自己発行 SAMLToken を生成するために必要とされる構成パラメーターが設定されます。

      トークンがどのように構成されるのかを制御する構成プロパティー の指定方法について詳しくは、『トークン作成中の SAML トークンの構成』を 参照してください。

    2. Thin Client for JAX-WS JAR ファイルをクラスパスに追加します。 app_server_root/runtimes/com.ibm.jaxws.thinclient_8.5.0.jar ファイルをクラスパスに追加します。この JAR ファイルのクラスパスへの追加について詳しくは、『Web サービス対応クライアントのテスト』を参照してください。
    3. WSSFactory newSecurityToken メソッドを使用して、 SAML トークンの作成方法を指定します。
      SAML トークンを作成するため、以下のメソッドを 指定してください。
      WSSFactory  newSecurityToken(SAMLToken.class, callbackHandler, "system.wss.generate.saml")
      SAML トークンの作成には、Java セキュリティー 権限 wssapi.SAMLTokenFactory.newSAMLToken が必要です。PolicyTool を 使用して、以下のポリシー・ステートメントを Java セキュリティー・ポリシー・ファイルまたは アプリケーション・クライアント was.policy ファイルに追加してください。
      permission java.security.SecurityPermission "wssapi.SAMLTokenFactory.newSAMLToken

      SAMLToken.class パラメーター は、作成するセキュリティー・トークンのタイプを指定します。

      callbackHandler オブジェクト は、作成する SAMLToken の特性を定義するパラメーターを 含みます。このオブジェクトがポイントする SAMLGenerateCallbackHandler オブジェクト は、次の表に示す構成パラメーターを指定します。
      表 1. SAMLGenerateCallbackHandler プロパティー. この表は、 bearer サブジェクト確認方式を使用する SAMLGenerateCallbackHandler オブジェクトの 構成パラメーターを示します。
      プロパティー 説明 必須
      SamlConstants.CONFIRMATION_METHOD Bearer 確認方式の使用を指定します。 はい
      SamlConstants.TOKEN_TYPE

      定数値 WSSConstants.SAML.SAML20_VALUE_TYPE を使用して、SAML 2.0 トークン・タイプを指定します。

      Web サービス・クライアントにポリシー・セットが関連付けられている場合、Web Services Security ランタイム環境はこのプロパティーを使用しません。このシナリオの場合は、tokenGenerator バインディング構成 の valueType 属性でトークン・タイプの値を指定します。

      この手順中の例では SAML 2.0 トークン が使用されていますが、WSSConstants.SAML.SAML11_VALUE_TYPE 値を使用することもできます。

      はい
      SamlConstants.SAML_NAME_IDENTIFIER

      SAML トークン内の NameID 値としてユーザー ID (例えば、myname) を指定します。

      Thin Client for JAX-WS を 使用しているときにこのパラメーターを定義しないと、NameID 値に有効な情報が含まれません。

      Web サービス要求呼び出しを作成する Java Platform, Enterprise Edition (Java EE) アプリケーションなどの Web サービス管理対象クライアントを使用している場合、Web Services Security ランタイム環境は、ユーザー・セキュリティー情報をセキュリティー・コンテキストから抽出しようとします。同じように、管理対象 Web サービス・クライアントに対してこのパラメーターを定義しない場合、NameID 値は、UNAUTHENTICATED 名前 ID を含みます。

      Web サービス・クライアントにポリシー・セットが関連付けられている場合は、このプロパティーは使用されません。SAML トークンの ID および属性の送信について詳しくは、SAML トークンの送信に関するセクションを参照してください。

      いいえ
      SamlConstants.SIGNATURE_REQUIRED

      発行者が SAML トークンにデジタルに署名する 必要があるかどうかを指定します。

      true 値 は、発行者が SAML トークンにデジタルに署名する必要があることを指定します。 この値がデフォルトです。

      いいえ
      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 ");
    4. 作成された SAML トークンのトークン ID を取得します。
      以下のステートメントを、作成した SAML トークンの簡単なテストとして使用できます。
      System.out.println("SAMLToken id = " + samlToken.getId())
  5. SAML トークンを、Web サービス要求メッセージの SOAP セキュリティー・ヘッダーに 追加します。
    1. Web サービス・クライアントを初期化し、SOAPAction プロパティーを構成します。 以下のコード・スニペットは、これらのアクションを示しています。
      // 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");
      			
    2. WSSGenerationContext を初期化します。 以下のコードは、WSSGenerationContext インターフェースを使用して、生成コンテキストを初期化し、SAMLToken を Web サービス要求メッセージに挿入できるようにする方法を示します。
      // Initialize WSSGenerationContext
      WSSGenerationContext gencont = factory.newWSSGenerationContext();
      gencont.add(samlToken);	
      具体的には、gencont.add(samlToken) メソッド呼び出し が、SAML トークンを要求メッセージに入れることを指定しています。PolicyTool を 使用して、以下のポリシー・ステートメントを Java セキュリティー・ポリシー・ファイルまたは アプリケーション・クライアント was.policy ファイルに追加してください。
       “permission javax.security.auth.AuthPermission "modifyPrivateCredentials"
    3. SOAP メッセージ・セキュリティー・ヘッダーにタイム・スタンプ・エレメントを 追加します。 SAML20 Bearer WSHTTPS default ポリシー・セットは、Web サービス要求メッセージおよび応答メッセージが SOAP メッセージのセキュリティー・ヘッダー内にタイム・スタンプ・エレメントを含んでいることを必要とします。以下のコード・スニペットでは、factory.newWSSTimestamp() メソッド呼び出し がタイム・スタンプを生成し、gencont.add(timestamp) メソッド呼び出し がタイム・スタンプを要求メッセージに入れることを指定しています。
      // Add a timestamp to the request message. 
      WSSTimestamp timestamp = factory.newWSSTimestamp();
      gencont.add(timestamp);
      	        
      gencont.process(requestContext);
    4. WSSGenerationContext オブジェクトを Web サービス RequestContext オブジェクトに関連付けます。 これで、WSSGenerationContext オブジェクト は、要求メッセージをフォーマットするのに必要なすべてのセキュリティー情報 を含んでいる状態になります。次の例のように、gencont.process(requestContext) メソッド呼び出しは WSSGenerationContext オブジェクトを Web サービス RequestContext オブジェクトに関連付けて、必要な SOAP セキュリティー・ヘッダーを Web Services Security ランタイム環境がフォーマットできるようにします。
      // Attaches WSSGenerationContext object to the Web services RequestContext object.
      gencont.process(requestContext);
    5. JVM プロパティーを使用して SSL トランスポート・レベル・メッセージ保護を指定します。
      SAML20 Bearer WSHTTPS default ポリシー・セットは、SSL を使用するトランスポート・レベル・メッセージ保護を必要とします。次の JVM プロパティーを使用して 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");

タスクの結果

bearer サブジェクト確認方式を使用して自己発行 SAML トークンを作成してから、JAX-WS プログラミング・モデルおよび WSS API を使用して、Web サービス要求メッセージでそのトークンを送信しました。

以下のコード例は、自己発行 SAML トークンを作成し、 その SAML トークンを Web サービス要求メッセージに入れて送信する方法を示すための Web サービス・クライアント・アプリケーションです。SAML トークンは必要だが、アプリケーションが Web サービス・メッセージを使用して SAML トークンを渡す必要はないという使用シナリオの場合は、以下のサンプル・コードの前半部分のみ (// Initialize Web services client セクションまで) を使用すればすみます。

/**
 * 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.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;

/**
 * SampleClient
 * main entry point for thin client JAR sample
 * and worker class to communicate with the services
 */
public class SampleClient {

  	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) {
    		SampleClient sample = new SampleClient();
    		sample.CallService();
  }

  /**
   	 * CallService Parms were already read. Now call the service proxy classes
   * 
   */
  	void CallService() {
    		String response = "ERROR!:";
    try {
      System.setProperty("java.security.auth.login.config", "profile_root/properties/wsjaas_client.conf ");
      System.setProperty("com.ibm.SSL.ConfigURL", "file:profile_root/properties/ssl.client.props");
      			// Initialize WSSFactory object
      WSSFactory factory = WSSFactory.getInstance();
      // Initialize WSSGenerationContext
      WSSGenerationContext gencont = factory.newWSSGenerationContext();
      // Initialize SAML issuer configuration via custom properties	
      HashMap<Object, Object> customProps = new HashMap<Object,Object>();

      customProps.put(SamlConstants.ISSUER_URI_PROP, "example.com");
      customProps.put(SamlConstants.TTL_PROP, "3600000");
      customProps.put(SamlConstants.KS_PATH_PROP, "keystores/saml-provider.jceks");
      customProps.put(SamlConstants.KS_TYPE_PROP, "JCEKS");
      customProps.put(SamlConstants.KS_PW_PROP, "{xor}LCswLTovPiws");
      customProps.put(SamlConstants.KEY_ALIAS_PROP, "samlissuer");
      customProps.put(SamlConstants.KEY_NAME_PROP, "CN=SAMLIssuer, O=EXAMPLE");
      customProps.put(SamlConstants.KEY_PW_PROP, "{xor}NDomLz4sLA==");
      customProps.put(SamlConstants.TS_PATH_PROP, "keystores/saml-provider.jceks");
      customProps.put(SamlConstants.TS_TYPE_PROP, "JCEKS");
      customProps.put(SamlConstants.TS_PW_PROP, "{xor}LCswLTovPiws");
      gencont.add(customProps); //Add custom properties

      			// Create SAMLToken
      			HashMap<Object, Object> map = new HashMap<Object, Object>();
      			map.put(SamlConstants.CONFIRMATION_METHOD, "Bearer");
      			map.put(SamlConstants.TOKEN_TYPE, WSSConstants.SAML.SAML20_VALUE_TYPE);
      			map.put(SamlConstants.SAML_NAME_IDENTIFIER, "Alice");
      			map.put(SamlConstants.SIGNATURE_REQUIRED, "true");			
      			SAMLGenerateCallbackHandler callbackHandler = new SAMLGenerateCallbackHandler(map);				

      SecurityToken samlToken = factory.newSecurityToken(SAMLToken.class, callbackHandler, "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");

      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 = _191EBC44865015D9AB1270745072344
Retrieving document at 'file:profile_root/.../wsdl/'.
>> CLIENT: SEI Echo to https://localhost:9443/WSSampleSei/EchoService12
>> CLIENT: SEI Echo invocation complete.
>> CLIENT: SEI Echo response is: SOAP12==>>HELLO

トピックのタイプを示すアイコン タスク・トピック



タイム・スタンプ・アイコン 最終更新: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_configsamlbearer_usingwssapi
ファイル名:twbs_configsamlbearer_usingwssapi.html