将 WSS API 与 SSL 传输保护一起用于发送自签发 SAML sender-vouches 令牌

您可以创建具有 sender-vouches 主体集确认方法的自签发 SAML 令牌,随后使用 Java™ API for XML-Based Web Services (JAX-WS) 编程模型和 Web Service 安全 API (WSS API) 将这些令牌在传输保护下随 Web service 请求消息一起发送。

开始之前

本任务假设您熟悉 JAX-WS 编程模型、WSS API 接口、SAML 概念、SSL 传输保护以及策略集的使用以配置和管理 Web service 设置。

关于此任务

您可以使用 Web service 安全编程接口构建 web service 客户机在 SOAP 请求消息中使用具有 sender-vouches 主体集确认方法的 SAML 令牌。使用 Web service 客户机中的编程接口来指定使用具有 sender-vouches 主体集确认方法(使用传输级别消息保护)的 SAML 令牌是使用策略集和绑定配置的备选方法。

您可以创建自签发 SAML 令牌,然后从 Web service 客户机在 Web service 请求消息中发送 SAML 令牌。在此任务中使用的 Web service 客户机应用程序是可供下载的 JaxWSServicesSamples 样本应用程序中包含的客户机代码的已修改版本。在过程部分中描述了来自样本的代码示例,且在示例部分中提供完整的准备使用的 Web service 客户机样本。

过程

  1. 识别并包含您要用于调用 Web service 提供程序的 Web service 客户机。

    使用此客户机来利用 WSS API 将 SAML 令牌以编程方式插入 SOAP 请求消息。

    在此过程中使用的 Web service 客户机是 JaxWSServicesSamples Web service 样本应用程序中包含的客户机代码的已修改版本。

    要获取并修改样本 Web service 客户机以使用 Web Service 安全 API 来利用 WSS API 以编程方式传递 SOAP 请求消息中的 SAML sender-vouches 令牌,请完成以下步骤:

    1. 下载 JaxWSServicesSamples 样本应用程序。 缺省情况下,未安装 JaxWSServicesSamples 样本。
    2. 获取 JaxWSServicesSamples 客户机代码。

      为了举例,此过程使用 JaxWSServicesSamples 样本中包含的 Echo 瘦客户机样本的修改版本。 Web service 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 service 客户机代码。

    您可以选择添加代码片段以利用自己的 Web service 客户机应用程序中的 WSS API 用编程方式传递 SOAP 请求消息中的 SAML 令牌,而不是使用 Web service 客户机样本。此过程中的示例使用 JAX-WS web service 瘦客户机;但是,您还可以使用受管客户机。

  2. 创建 SAML20 Bearer WSHTTPS default 策略集或 SAML11 Bearer WSHTTPS default 策略集的副本。

    提供策略集副本的名称;例如 SAML20 SenderVouches WSHTTPS 或 SAML11 SenderVouches WSHTTPS 来帮助您标识此新策略集使用 sender-vouches 确认方法。

    无需对新策略文件进行其他更改,因为在绑定配置中(不是在策略中)指定了主体集确认方法。

    新策略文件包含 SAMLToken20Bearer 或 SAMLToken11Bearer 作为策略标识。将 SAMLToken20Bearer 策略的标识更改为 SAMLToken20SV 或者将 SAMLToken11Bearer 策略的标识更改为 SAMLToken11SV 以指定更有描述性的名称。更改策略标识不会以任何方式更改策略实施;但是,添加描述性标识可帮助您识别:这些策略标识使用 sender-vouches 确认方法。

    如果您要查看这些策略的设置,请使用管理控制台来完成以下操作:
    1. 单击服务 > 策略集 > 应用程序策略集 > policy_set_name
    2. 单击“策略”表中的 WS-Security 策略。
    3. 单击主策略链接或引导策略链接。
    4. 从“策略详细信息”部分单击请求令牌策略
  3. 将新的 SAML20 SenderVouches WSHTTPS 或 SAML11 SenderVouches WSHTTPS 策略集附加到 Web service 提供程序应用程序。 阅读关于为 SAML sender-vouches 令牌配置客户机和提供程序绑定的信息,以了解关于将此策略集附加到 Web service 提供程序应用程序的详细信息。
  4. 创建 SAML Bearer 提供程序样本缺省常规绑定的副本。
    1. 对于缺省策略集的新副本,请提供包括 sender-vouches 的名称,例如 SAML Sender-vouches provider binding
    2. 将 confirmationMethod 属性的值更改为意图的 SAML 令牌版本的令牌使用者配置中的 sender-vouches 阅读关于为 SAML sender-vouches 令牌配置客户机和提供程序绑定的信息,以了解关于修改 sender-vouches 绑定以满足担保需求的详细信息。
  5. 将新的提供程序绑定分配到 JaxWSServicesSamples 提供程序样本。 阅读关于配置 SAML sender-vouches 的客户机和提供程序绑定的信息,以了解关于将 SAML sender-vouches 提供程序样本、缺省常规绑定分配到 Web service 提供程序应用程序的详细信息。
  6. 支持 Web Service 提供程序 SSL 配置属性 clientAuthentication 来要求 X.509 客户机证书认证。
    clientAuthentication 属性确定是否需要 SSL 客户机认证。要指定 clientAuthentication 属性,请使用管理控制台来完成以下操作:
    1. 单击安全 > SSL 证书和密钥管理 > 管理端点安全配置 > {入站 | 出站} > SSL_configuration
    2. 单击 WC_defaulthost_secure 链接。
    3. 在“相关项”下,单击 SSL_configurations 链接。
    4. 选择 NodeDefaultSSLSettings 资源。
    5. 单击保护质量 (QoP) 设置链接。
    6. 从菜单选择必需以指定客户机认证。

    阅读关于创建安全套接字层配置的信息以了解关于配置 clientAuthentication 属性的更多信息。

  7. 在 web service 客户机代码中,使用 CallService() 方法来指定属性文件,其中包含生成自签发 SAML 令牌所需的配置参数。

    CallService() 方法指定 Web service 安全运行时环境生成自签发 SAML 令牌所需的配置参数。

    以下代码片段说明如何使用 CallService() 方法来指定 Web service 安全配置参数:
    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("java.security.auth.login.config", "profile_root/properties/wsjaas_client.conf ");
        // 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

    阅读关于创建令牌期间配置 SAML 令牌的信息以了解关于如何指定配置属性来控制如何配置令牌的更多信息。

  8. 将 JAX-WS JAR 文件的瘦客户机添加到类路径。app_server_root/runtimes/com.ibm.jaxws.thinclient_8.5.0.jar 文件添加到类路径。请参阅测试支持 Web Service 的客户机信息以了解关于将此 JAR 文件添加到类路径的更多信息。
  9. 创建自签发 SAML 令牌。 以下代码片段说明 SAML sender-vouches 令牌创建过程:
    // Create SAMLToken
    HashMap<Object, Object> map = new HashMap<Object, Object>();
    map.put(SamlConstants.CONFIRMATION_METHOD, "sender-vouches");
    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());
    1. 使用 WSSFactory newSecurityToken 方法来指定如何创建 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 对象包含的参数定义所创建的 SAML 令牌的特征。该对象指向 SAMLGenerateCallbackHandler 对象,该对象指定在下表中描述的配置参数:
      表 1. SAMLGenerateCallbackHandler 属性. 该表描述使用 sender-vouches 确认方法的 SAMLGenerateCallbackHandler 对象的配置参数。
      属性 描述 必需
      SamlConstants.CONFIRMATION_METHOD 指定来使用 sender-vouches 确认方法。
      SamlConstants.TOKEN_TYPE

      使用常量值 WSSConstants.SAML.SAML20_VALUE_TYPE 来指定 SAML 2.0 令牌类型。

      Web Service 客户机具有策略集附件时,Web Service 安全运行时环境未使用该属性。在此场景中,按 tokenGenerator 绑定配置的 valueType 属性指定令牌值类型。

      该过程中的示例使用 SAML 2.0 令牌;但是,您还可以使用 WSSConstants.SAML.SAML11_VALUE_TYPE 值。

      SamlConstants.SAML_NAME_IDENTIFIER

      将某个用户身份(例如 myname)指定为 SAML 令牌中的 NameID 值。

      如果您没有在使用 JAX-WS 的瘦客户机时定义此参数,那么 NameID 值没有包含有用的信息。

      如果您在使用 Web service 受管客户机,让 Java Platform, Enterprise Edition (Java EE) 应用程序进行 Web service 请求调用,那么 Web service 安全运行时环境尝试从安全上下文抽取用户安全信息。类似地,如果您没有为受管 Web service 客户机定义该参数,那么 NameID 值包含未经认证的名称标识。

      如果您的 Web service 客户机具有策略集附件,那么没有使用该属性。阅读关于发送 SAML 令牌的信息以了解关于发送 SAML 令牌身份和属性的更多信息。

      SamlConstants.SIGNATURE_REQUIRED

      指定是否需要签发者以数字方式签署 SAML 令牌。

      true 值指定需要签发者来以数字方式签署 SAML 令牌。 此值是缺省值。

      system.wss.generate.saml 参数指定用于创建 SAML 令牌的 Java 认证和授权服务 (JAAS) 登录模块。您必须指定 JVM 属性以定义 JAAS 配置文件,其包含所需的 JAAS 登录配置;例如:
      -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 ");
    2. 获取创建的 SAML 令牌的令牌标识。
      将以下语句用作对所创建的 SAML 令牌的简单测试:
      System.out.println("SAMLToken id = " + samlToken.getId())

结果

您创建具有 sender-vouches 确认方法(具有传输保护)的自签发 SAML 令牌,然后使用 JAX-WS 编程模型和 WSS API 将此令牌随 Web service 请求消息一起发送。

示例

以下代码示例是一个准备好使用的完整 Web service 客户机应用程序,其演示如何创建自签发 SAML sender-vouches 令牌以及在 Web service 请求消息中发送该 SAML 令牌。该样本代码说明先前描述的过程步骤。

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

public class SampleSamlSVClient {
  private String urlHost = "localhost";
  private String urlPort = "9081";
  private static final String CONTEXT_BASE = "/WSSampleSei/";
  private static final String ECHO_CONTEXT12 = CONTEXT_BASE+"EchoService12";	
  private String message = "HELLO";
  private String uriString = "http://" + 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("java.security.auth.login.config", "profile_root/properties/wsjaas_client.conf ");

      // 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, "sender-vouches");
      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 service 客户机应用程序样本正确运行时,您收到如下的消息:
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

指示主题类型的图标 任务主题



时间戳记图标 最近一次更新时间: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_configsamlsendervouches_transportlevel_usingwssapi
文件名:twbs_configsamlsendervouches_transportlevel_usingwssapi.html