使用 API 创建 SAML holder-of-key 令牌

SAML holder-of-key 令牌扩展 WebSphere® Application Server 中的安全性令牌公共接口,且可以用作保护令牌。WebSphere Application Server 为创建 SAML holder-of-key 令牌提供 SAML 库 API。

关于此任务

创建 SAML 令牌需要三个参数:
  • com.ibm.wsspi.wssecurity.saml.config.RequesterConfig
  • com.ibm.wsspi.wssecurity.saml.config.ProviderConfig
  • com.ibm.wsspi.wssecurity.saml.config.CredentialConfig
遵循步骤为每个参数创建实例,然后创建 SAML holder-of-key 令牌。作为 CredentialConfig 的替代项,您还可以使用 javax.security.auth.Subject。有关更多信息,请参阅 API 文档。

过程

  1. 将 SAML 令牌版本用作参数来创建 com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory 实例。受支持的 SAML 令牌版本为 http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1 和 http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0。 SAMLTokenFactory 实例是单一实例,因此是线程安全的。 根据令牌版本,使用以下代码行之一来创建实例。
    • 使用以下代码行为 v1.1 SAML 令牌创建 com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory 实例:
      SAMLTokenFactory samlFactory = SAMLTokenFactory.getInstance(SAMLTokenFactory.WssSamlV11Token11);
    • 使用以下代码行为 v2.0 SAML 令牌创建 com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory 实例:
      SAMLTokenFactory samlFactory = SAMLTokenFactory.getInstance(SAMLTokenFactory.WssSamlV11Token20);
  2. SAMLTokenFactory 实例用于创建 RequesterConfig 实例,这根据请求者的认证需求来确定如何生成令牌。 使用以下代码行之一来根据您希望该令牌使用密钥(对称密钥)还是公用密钥来创建 RequesterConfig 实例:
    • 使用以下代码行以利用包含在 SubjectConfirmation 中的密钥(对称密钥)为 SAML holder-of-key 令牌创建缺省 RequesterConfig:
      RequesterConfig reqData = samlFactory. newSymmetricHolderOfKeyTokenGenerateConfig ();
      您还必须为目标服务设置密钥别名,以便提供程序可以将服务的密钥加密:
      reqData.setKeyAliasForAppliesTo("SoapRecipient");
    • 使用以下代码行以利用包含在 SubjectConfirmation 中的公用密钥为 SAML holder-of-key 令牌创建缺省 RequesterConfig:
      RequesterConfig reqData = samlFactory. newAsymmetricHolderOfKeyTokenGenerateConfig ();
      您还必须为请求者设置密钥别名,以便提供程序可以从请求者抽取公用密钥,并将该密钥包含在 SubjectConfirmation 中:
      reqData.setKeyAliasForRequester(“SOAP Initiator”);
    缺省 RequestConfig 实例足以生成简单holder-of-key 令牌,但是其他声明可以通过定制 RequesterConfig 实例包含在 SAML 令牌中。例如,为了将密码认证信息包含在令牌中,请使用 setAuthenticationMethod:
    reqData.setAuthenticationMethod(“password”);
  3. 使用 SAMLTokenFactory 来创建 ProviderConfig 实例,这描述令牌签发者。ProviderConfig 实例指定 SAML 签发者名称,以及密钥库和信任库信息,这标识用于 SAML 加密和签名的密钥。 使用来自属性文件的属性值创建 ProviderConfig 实例。属性文件指定 ProviderConfig 对象的缺省值。在 Java™ 客户机环境中,该属性文件按 JVM 系统属性 com.ibm.webservices.wssecurity.platform.SAMLIssuerConfigDataPath 定义。
    WebSphere Application Server 运行时环境中,属性文件名是 SAMLIssuerConfig.properties。 该文件可以按该优先顺序位于服务器级别配置目录或单元级别目录下。 服务器级别路径的示例如下:
    app_server_root/profiles/$PROFILE/config/cells/$CELLNAME/nodes/$NODENAME/servers/$SERVERNAME/SAMLIssuerConfig.properties
    单元级别路径的示例如下:
    app_server_root/profiles/$PROFILE/config/cells/$CELLNAME/sts/SAMLIssuerConfig.properties

    如果在服务器运行时环境中定义了属性,那么将忽略 JVM 系统属性 com.ibm.webservices.wssecurity.platform.SAMLIssuerConfigDataPath。 有关所有属性的详细描述,请阅读关于令牌创建期间 SAML 令牌的配置的信息。

    使用以下代码行来创建缺省 ProviderConfig 实例:

    ProviderConfig samlIssuerCfg = samlFactory.newDefaultProviderConfig(“any issuer name”);
    签发者名称是可选的。如果指定了签发者名称,那么签发者名称显示在 SAML 声明中。如果没有指定签发者名称,那么将来自 SAMLIssuerConfig.properties 的缺省签发者名称属性用作签发者名称。
  4. 可选: 新建 SAML 令牌时,SAMLTokenFactory 使用 JAAS 主体集或 CredentialConfig 实例来填充新的 SAML 令牌。 要使用 JAAS 主体集来填充令牌,请使用 com.ibm.websphere.security.auth.WSSubject getCallerSubject() API 或 getRunAsSubject() API 来获取表示请求客户机或者执行线程的身份的 JAAS 主体集。

    您使用 JAAS 主体集来新建 SAML 令牌时,SAMLTokenFactory 在主体集 PrivateCredentials 列表中搜索 SAMLToken 对象。如果存在 SAMLToken 对象,将 NameId 或 NameIdentifier 复制到新 SAML 令牌。SAMLTokenFactory 还将 SAML 属性和 AuthenticationMethod 从现有 SAML 令牌复制新的 SAML 令牌。新的 SAML 令牌包括新签发者名称、新签署证书、确认方法、holder-of-key 确认方法的新密钥信息以及新的 NotBefore 和 NotOnAfter 条件。这些令牌设置由 ProviderConfig 和 RequesterConfig 对象中的配置参数确定。

    如果主体集中没有 SAMLToken 对象,仅将 WSPrincipal 主体名称从主体集复制到新的 SAML 令牌。没有将主体集中的其他属性复制到新的 SAML 令牌。类似,签发者名称、签名证书、确认方法、holder-of-key 的密钥信息以及 NotBefore 和 NotOnOrAfter 条件由 ProviderConfig 和 RequesterConfig 对象中的配置参数确定。

    或者,您可以在执行线程上使用 RunAsSubject 方法来创建 SAML 令牌。使用此方法时,请勿将 JAAS 主体集或 CredentialConfig 对象传递到 SAMLTokenFactory 来创建 SAML 令牌。相反,如先前所述,将现有 SAML 令牌的内容复制到新的 SAML 令牌。

    创建 SAML 令牌的另一方法是使用 CredentialConfig 对象以编程方式填充 SAML NameId 和属性。在以下情况下使用此方法:
    • 定制 SAML 属性必须包含在新 SAML 令牌中。
    • SAML 令牌是手动创建,而不是使用 SAMLTokenFactory 从 JAAS 主体集自动填充 SAML 令牌。
    • 主体集中没有现存的 SAML 令牌。
    • 没有可用的 JAAS 主体集。

    要在不使用 JAAS 主体集的情况下创建 CredentialConfig 对象,使用以下代码行:

    CredentialConfig cred = samlFactory.newCredentialConfig ();
    没有为此 CredentialConfig 对象提供的初始值,所以您必须使用 setter 方法来填充 CredentialConfig 对象。
    要填充 SAML NameIdentifier 或 NameID,使用以下代码行:
    cred.setRequesterNameID("any name");
    any name 变量的值用作 SAML 令牌中的主体名称。在 SAML V1.1 令牌中,该名称在声明中显示为 NameIdentifier,而在 SAML V2.0 令牌中,该名称显示为 NameId。 例如,如果 any name 的值是 Alice,那么在 SAML V1.1 令牌中生成以下声明:
    <saml:NameIdentifier>Alice</saml:NameIdentifier>
    在 SAML V2.0 令牌中生成以下声明:
    <saml2:NameID>Alice</saml2:NameID> 

    要将 SAML 属性包含在声明的 <AttributeStatement> 部分中,请使用该代码:

    SAMLAttribute samlAttribute = new SAMLAttribute("email" /* Name*/, new String[] {"joe@websphere"} 
    /*Attribute Values*/, null, "IBM WebSphere namespace" /* namespace*/, "email" /* format*/, "joe" /*friendly name */);
    ArrayList<SAMLAttribute> al = new ArrayList<SAMLAttribute>();
    al.add(samlAttribute)
    sattribute = new SAMLAttribute("Membership", new String[] {"Super users", "Gold membership"}, null, null /* format*/, null, null );
    al.add(samlAttribute );
    cred.setSAMLAttributes(al);
    此样本代码生成以下 <Attribute> 声明:
    <saml:Attribute AttributeName="email" NameFormat="email" AttributeNamespace="IBM WebSphere namespace">
    <saml:AttributeValue>joe@websphere</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute AttributeName="Membership">
    <saml:AttributeValue>Super users</saml:AttributeValue><saml:AttributeValue>Gold membership</saml:AttributeValue>
    </saml:Attribute>
  5. 使用此代码行来生成 SAML holder-of-key 令牌:
    SAMLToken samlToken = samlFactory.newSAMLToken(cred, reqData, samlIssuerCfg);
    该方法需要 Java 安全许可权 wssapi.SAMLTokenFactory.newSAMLToken。使用来自先前步骤的代码行的完整代码样本包含在“示例”部分中。

示例

使用此样本代码,利用来自主体集的密钥(对称密钥)创建 SAML v1.1 holder-of-key 令牌。
import com.ibm.wsspi.wssecurity.saml.config.RequesterConfig;
import com.ibm.wsspi.wssecurity.saml.config.ProviderConfig;
import com.ibm.wsspi.wssecurity.saml.config.CredentialConfoig ; 
import com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory 

SAMLTokenFactory samlFactory =  SAMLTokenFactory.getInstance(SAMLTokenFactory.WssSamlV11Token11);

RequesterConfig reqData  =  samlFactory.newSymmetricHolderOfKeyTokenGenerateConfig();

//Map "AppliesTo" to key alias, so library knows how to encrypt the Symmetric Key
reqData.setKeyAliasForAppliesTo("SOAPRecipient"); 

ProviderConfig samlIssuerCfg = samlFactory.newDefaultProviderConfig(IsserUri);

Subject subject =  com.ibm.websphere.security.auth.WSSubject.getRunAsSubject(); 

SAMLToken samlToken = samlFactory.newSAMLToken(subject, reqData, samlIssuerCfg);
使用此样本代码,利用来自主体集的公用密钥创建 SAML v2.0 holder-of-key 令牌:
//User expression on how SAML should be created, default provided
RequesterConfig reqData =  samlFactory.newAsymmetricHolderOfKeyTokenGenerateConfig();

//Choose a public key to be included in SAML
reqData.setKeyAliasForRequester("SOAPInitiator"); 

//Get issuer key store so can sign or encrypt assertion, issuer name
ProviderConfig samlIssuerCfg = samlFactory.newDefaultProviderConfig("any_issuer");

//Get JAAS Subject so the factory can populate principal and attributes to SAML
Subject subject =  com.ibm.websphere.security.auth.WSSubject.getRunAsSubject(); 

SAMLToken samlToken = samlFactory.newSAMLToken(subject, reqData, samlIssuerCfg);
使用此样本代码,利用密钥(对称密钥)创建 SAML v2.0 holder-of-key 令牌:
SAMLTokenFactory samlFactory =  SAMLTokenFactory.getInstance (SAMLTokenFactory.WssSamlV20Token11);

RequesterConfig reqData = samlFactory. newSymmetricHolderOfKeyTokenGenerateConfig ();
//Map "AppliesTo" to key alias so library knows how to encrypt the Symmetric Key
reqData.setKeyAliasForAppliesTo("SOAPRecipient"); 

ProviderConfig samlIssuerCfg = samlFactory.newDefaultProviderConfig(null);

CredentialConfig cred = samlFactory.newCredentialConfig ();
cred.setRequesterNameID("any_name"); 

SAMLToken samlToken =  samlFactory.newSAMLToken(subject, reqData, samlIssuerCfg);

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



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