WAS v8.5 > Develop 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, which 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. We can use the SAML library API to create required SAML configuration objects. Then, use those configuration objects to generate a SAML sender-vouches token.

  1. Create a SAMLTokenFactory instance.

    1. Import the method:

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

    2. Create the instance:

      • v1.1 SAML token:

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

      • v2.0 SAML token:

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

  2. Create a RequesterConfig instance, which determines how the token will be generated, according the authentication requirements of the requester.

      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. Example of the server-level path:

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

    Example of the cell-level path:

      app_server_root/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.

    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 either...

      com.ibm.websphere.security.auth.WSSubject getCallerSubject() com.ibm.websphere.security.auth.WSSubject getRunAsSubject()

    ...to obtain a JAAS subject that represents the requesting client, or the identity of the execution thread.

    • When we 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:

      • issuer name
      • signing certificate
      • method
      • KeyInfo for the holder-of-key confirmation method
      • 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, we 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 v2.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:

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


Related


SAML sender-vouches token


Reference:

SAMLIssuerConfig.properties file


+

Search Tips   |   Advanced Search