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 bearer token using the API

Use the SAML library API to create a SAML bearer token.

This library allows you to create a SAML bearer token. We can use the SAML library API to create required SAML configuration objects, then use those configuration objects to generate a bearer SAML 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 bearer token:

   RequesterConfig reqData = samlFactory.newBearerTokenGenerateConfig();
   

   The default RequestConfig instance is sufficient to generate a simple bearer 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 setAuthenticationMethod:

   reqData.setAuthenticationMethod(“password”);
   

   To disable signing in a SAML assertion, use the setAssertionSignatureRequired method, for example:

   reqData.setAssertionSignatureRequired(false);
   

   For more information, read about the SAML bearer assertion.

3. Use the SAMLTokenFactory 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. An example of the server level path follows:

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

   An example of the cell level path follows:

   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 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 searches for a SAMLToken object in the subject PrivateCredentials list. If a SAMLToken object exists, the NameId or NameIdentifier are copied to the new SAML token. The SAMLTokenFactory also copies the SAML attributes and AuthenticationMethod 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.

   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.

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

   cred.setRequesterNameID("any name");
   

   The value of the any name variable 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 any name 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 v2.0 token:

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

   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 bearer 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 bearer token from the subject:

SAMLTokenFactory samlFactory = SAMLTokenFactory.getInstance(SAMLTokenFactory.WssSamlV11Token11)

RequesterConfig reqData = samlFactory.newBearerTokenGenerateConfig();

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 bearer token without using the subject:

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

RequesterConfig reqData = samlFactory.newBearerTokenGenerateConfig();
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 bearer token

Related

SAMLIssuerConfig.properties file

+

Search Tips   |   Advanced Search