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
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.
An example of the server level path follows:
app_server_root/profiles/$PROFILE/config/cells/$CELLNAME/nodes/$NODENAME/servers/$SERVERNAME/SAMLIssuerConfig.properties
An
example of the cell level path follows:
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 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
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
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 Version 1.1 token, or NameId in the SAML Version 2.0 token.
For example, if the value of
any name 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>