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.
About this task
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
- Create a SAMLTokenFactory instance using the SAML token
version as a parameter.
- Use the following line of code to import the method:
import com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory;
- Use one of these lines of code to create the instance,
depending on the token version.
- After you create 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);
- 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
WebSphere Application Server 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:
app_server_root/profiles/$PROFILE/config/cells/$CELLNAME/nodes/$NODENAME/servers/$SERVERNAME/SAMLIssuerConfig.properties
See
the following 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.
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.
- 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.
- 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
you must 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 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 Version 1.1 token, or
NameId in the SAML Version 2.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 Version 1.1 token: <saml:NameIdentifier>Alice</saml:NameIdentifier>
The following assertion is generated in a SAML Version
2.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>
- 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);