Network Deployment (Distributed operating systems), v8.0 > Develop and deploying applications > Develop web services - Security (WS-Security) > Develop applications that use Web Services Security > Develop message-level security for JAX-WS web services > Develop SAML applications

Create a SAML sender-vouches token using the API

Use the SAML library API to create a SAML sender-vouches token, which includes the sender-vouches confirmation method. The sender-vouches confirmation method is used when a server needs to propagate the client identity or behavior of the client.

When SAML function is installed on a WebSphere server, a SAML library API is provided. Use the library to create a SAML sender-vouches token. You can use the SAML library API to create required SAML configuration objects. Then, use those configuration objects to generate a SAML sender-vouches token.

Procedure

1. Create a SAMLTokenFactory instance using the SAML token version as a parameter.

   1. Use the following line of code to import the method:

      import com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory;
      

   2. Use one of these lines of code to create the instance, depending on the token version.

      • Add the following line of code to create a SAMLTokenFactory instance for a version 1.1 SAML token:

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

      • Add the following line of code to create a SAMLTokenFactory instance for a version 2.0 SAML token:

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

2. After creation of the instance, the SAMLTokenFactory is used to create a RequesterConfig instance, which determines how the token will be generated, according the authentication requirements of the requester. Use this line of code to create the RequesterConfig instance for the sender-vouches token:

   RequesterConfig reqData = samlFactory.newSenderVouchesTokenGenerateConfig();
   

   The default RequestConfig instance is sufficient to generate a simple sender-vouches token, but additional assertions can be included in the SAML token by customizing the RequesterConfig instance. For example, to include password authentication information in the token, use the method, setAuthenticationMethod:

   reqData.setAuthenticationMethod(“password”);
   

   The trust validation for a sender-vouches assertion is the responsibility of the sender, not the issuer, so the Enveloped-Signature element is not required in the assertion.

   To remove the Enveloped-Signature element from the SAML assertion, use the setAssertionSignatureRequired method; for example:

   reqData.setAssertionSignatureRequired(false);
   

3. Use the SAMLTokenFactory API to create a ProviderConfig instance, which describes the token issuer. The ProviderConfig instance specifies the SAML issuer name, as well as keystore and truststore information, which identifies the key for SAML encryption and signing. The ProviderConfig instance is created using property values from a property file. The property file specifies the default value of the ProviderConfig object. In a Java client environment, this property file is defined by a JVM system property, com.ibm.webservices.wssecurity.platform.SAMLIssuerConfigDataPath.

   In the WAS runtime environment, the property file name is SAMLIssuerConfig.properties. The file can be located either under the server level configuration directory, or the cell level directory, in that order of precedence. See the following example of the server-level path:

   WAS_HOME/profiles/$PROFILE/config/cells/$CELLNAME/nodes/$NODENAME/servers/$SERVERNAME/SAMLIssuerConfig.properties
   

   See the following example of the cell-level path:

   WAS_HOME/profiles/$PROFILE/config/cells/$CELLNAME/sts/SAMLIssuerConfig.properties
   

   The JVM system property, com.ibm.webservices.wssecurity.platform.SAMLIssuerConfigDataPath, is ignored if the property is defined in server runtime environment. For a detailed description of all the properties, read about configuration of a SAML token during token creation.

   Use the following line of code to create a default ProviderConfig instance:

   ProviderConfig samlIssuerCfg = samlFactory.newDefaultProviderConfig(“any issuer name”);
   

   The issuer name is optional. If the issuer name is specified, the Issuer name appears in the SAML assertion. If the issuer name is not specified, a default issuer name property from the SAMLIssuerConfig.properties is used as the issuer name.

4. Optional: When creating a new SAML token, the SAMLTokenFactory uses either a Java Authentication and Authorization Service (JAAS) subject or a CredentialConfig instance to populate the new SAML token. To use a JAAS subject to populate the token, use the com.ibm.websphere.security.auth.WSSubject getCallerSubject() API or the getRunAsSubject() API to obtain a JAAS subject that represents the requesting client, or the identity of the execution thread.

   • When you use the JAAS subject to create a new SAML token, the SAMLTokenFactory API searches for a SAMLToken object in the subject PrivateCredentials list. If a SAMLToken object exists, the NameId or NameIdentifier objects are copied to the new SAML token. The SAMLTokenFactory also copies the SAML attributes and AuthenticationMethod method from the existing SAML token to the new SAML token. The new SAML token includes a new issuer name, new signing certificate, confirmation method, new KeyInfo for the holder-of-key confirmation method, and new NotBefore and NotOnAfter conditions. These token settings are determined by the configuration parameters in the ProviderConfig and RequesterConfig objects.

     If there is no SAMLToken object in the subject, only the WSPrincipal principal name is copied from the subject to the new SAML token. No other attributes in the subject are copied into the new SAML token. Similarly, the issuer name, signing certificate, confirmation method, KeyInfo for the holder-of-key, and NotBefore and NotOnOrAfter conditions are determined by configuration parameters in ProviderConfig and RequesterConfig objects.

     Alternately, you can use the RunAsSubject method on the execution thread to create the SAML token. When using this method, do not pass the JAAS subject or the CredentialConfig object to the SAMLTokenFactory to create the SAML token. Instead, the content of the existing SAML token is copied to the new SAML token, as described previously.

   • Another method of creating a SAML token is to use a CredentialConfig object to populate the SAML NameId and Attributes programmatically. Use this method in the following circumstances:
     • Custom SAML attributes must be included in the new SAML token.
     • The SAML token is created manually instead of using the SAMLTokenFactory to populate the SAML token from a JAAS subject automatically.
     • There is no existing SAML token in the subject.
     • There is no JAAS subject available.

   1. To create a CredentialConfig object without using the JAAS subject, use this line of code:

      CredentialConfig cred = samlFactory.newCredentialConfig ();
      

      There is no initial value provided for this CredentialConfig object, so use setter methods to populate the CredentialConfig object.

   2. To populate the SAML NameIdentifier or NameID, use the following line of code:

      cred.setRequesterNameID("any name");
      

      The value of the parameter passed to the setRequesterNameID() method is used as the principal name in the SAML token. The name appears in the assertion as the NameIdentifier in a SAML v1.1 token, or NameId in the SAML v2.0 token. For example, if the value of the parameter passed to the setRequesterNameID() method is Alice, the following assertion is generated in a SAML v1.1 token:

      <saml:NameIdentifier>Alice
      </saml:NameIdentifier> 

      The following assertion is generated in a SAML Version 2.0 token:

      <saml2:NameID>Alice
      </saml2:NameID>
      

   3. To include SAML attributes in the <AttributeStatement> portion of an assertion, use this code:

      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);
      
      

      This sample code generates the following <Attribute> assertions:

      <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. Generate a SAML sender-vouches token using this line of code:

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

   This method requires the Java security permission wssapi.SAMLTokenFactory.newSAMLToken.

   Complete code samples using lines of code from the previous steps are included in the Example section.

Example

Use this sample code to create a SAML version 1.1 sender-vouches token from the subject:

SAMLTokenFactory samlFactory = SAMLTokenFactory.getInstance(SAMLTokenFactory.WssSamlV11Token11)

RequesterConfig reqData = samlFactory.newSenderVouchesTokenGenerateConfig();

ProviderConfig samlIssuerCfg = samlFactory.newDefaultProviderConfig(“WebSphere Server”);

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

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

Use this sample code to create a SAML version 1.1 sender-vouches token without using the subject:

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

RequesterConfig reqData = samlFactory.newSenderVouchesTokenGenerateConfig();
reqData.setAuthenticationMethod("Password"); //Authentication method for Assertion

ProviderConfig samlIssuerCfg = samlFactory.newDefaultProviderConfig(Self issuer);

CredentialConfig cred = samlFactory.newCredentialConfig ();
cred.setRequesterNameID("Alice");   // SAML NameIdentifier
//SAML attributes:
SAMLAttribute attribute = new SAMLAttribute
   ("email" /* Name*/, new String[] {"joe@websphere"}
   /*Attribute Values in String*/,null
   /*Attribute Values in XML */, "WebSphere" /* Namespace*/, "email" /* format*/, "joe" /*Friendly_name */);
ArrayList
<SAMLAttribute> al = new ArrayList
<SAMLAttribute>();
al.add(attribute);
attribute = new SAMLAttribute("Membership", new String[] {"Super users", "My team"}, null, null, null, null  );
al.add(attribute);
cred.setSAMLAttributes(al);

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

Configure client and provider bindings for the SAML sender-vouches token

Related

SAMLIssuerConfig.properties file

+

Search Tips   |   Advanced Search