SAML Issuer Config Properties

When creating a new self-issued SAML token, you can specify configuration properties to control how the token is configured. The configuration properties are name/value pairs that describe provider-side information such as the issuer location, and the keystore and trust store file paths.

[Updated in April 2014]The SAML issuer config properties can be stored in a property file called SAMLIssuerConfig.properties. The SAMLIssuerConfig.properties file usage is deprecated in WebSphere Application Server version 8.[Updated in April 2014]

Starting with WebSphere Application Server version 8, you can also specify these properties in WS-Security policy bindings or in the Web Services Security (WSS) Application Programming interfaces (APIs) WSSGenerationContext.

In the administrative console, the properties are set in the WS-Security Outbound Custom Properties. An example path is Services > Policy sets > General client policy set bindings > Saml Bearer Client sample > WS-Security > Custom properties. You can also set the properties in the WS-Security policy bindings using the setSAMLIssuerConfigInBinding admin task. For more information see "Managing self-issue SAML token configuration using wsadmin commands."

If the SAML token generator is used to self-issue a SAML token using the WSSAPIs, the custom properties are added directly to the com.ibm.websphere.wssecurity.wssapi.WSSGenerationContext using a HashMap. See the javadoc for com.ibm.websphere.wssecurity.wssapi.WSSGenerationContext for more information.

If a self-issued SAML token will be created using the com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory WSSAPI, the SAMLTokenFactory.newDefaultProviderConfig() method returns a com.ibm.wsspi.wssecurity.saml.config.ProviderConfig object that has object values set to the properties specified in SAMLIssuerConfig.properties file. If no SAMLIssuerConfig.properties file is specified, which is the recommended programming style, a ProviderConfig object with empty contents will be returned. Use ProviderConfig setter methods to populate its contents. See the javadoc for com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory for more information.

SAMLIssuerConfig.properties File Location

A single configuration file, SAMLIssuerConfig.properties, containing the provider-side properties is created and stored on each server. On a WebSphere® server, the file is located in the server-level repository, or in the cell-level repository. In an environment that is not based on WebSphere, the file location is defined by a Java system property. The name of this property is com.ibm.webservices.wssecurity.platform.SAMLIssuerConfigDataPath.

For example, the location of the file at the server level on a WebSphere server is:app_server_root/profiles/$PROFILE/config/cells/$CELLNAME/nodes/$NODENAME/servers/$SERVERNAME/SAMLIssuerConfig.properties

The location of the file at the cell level on a WebSphere server is:app_server_root/profiles/$PROFILE/config/cells/$CELLNAME/sts/SAMLIssuerConfig.properties

SAML token properties

The following table describes the provider configuration properties.
Table 1. Properties to configure provider information for a new SAML token. Use these properties to control how the token is created. This table shows the properties that are used in the SAMLIssuerConfig.properties file and the WS-Security policy bindings.
SAMLIssuerConfig.properties property name Policy bindings property name Sample property value Property description
com.ibm.wsspi.wssecurity.dsig.oldEnvelopedSignature   true Use only if you are setting the com.ibm.wsspi.wssecurity.dsig.enableEnvelopedSignatureProperty JVM custom property to true. See the topic Java Virtual Machine (JVM) custom properties for a description of when you might want to use this JVM custom property.
IssuerFormat   urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName Value for the Format attribute of the Issuer element in the SAML token.
Note: If you want to add the Format attribute to the Issuer element, you must specify this property.
IssuerURI com.ibm.wsspi.wssecurity.saml.config.issuer.IssuerURI http://www.websphere.ibm.com/SAML/SelfIssuer The URI of the issuer.
TimeToLiveMilliseconds com.ibm.wsspi.wssecurity.saml.config.issuer.TimeToLiveMilliseconds 3600000 Amount of time before expiration of the token. This property is used to set the NotOnOrAfter attributes in the token. NotOnOrAfter is set to (currentTime)+TimeToLive+(currentClockSkew).
KeyStoreRef com.ibm.wsspi.wssecurity.saml.config.issuer.KeyStoreRef name=myKeyStoreRef managementScope=(cell):myCell:(node):myNode A reference to a managed keystore in security.xml that contains the signing key.
KeyStorePath com.ibm.wsspi.wssecurity.saml.config.issuer.KeyStorePath app_server_root/etc/ws-security/samples/dsig-receiver.ks The location of the keystore file that contains the signing key.
Note: You must modify this value from the default value to match the path location for your system.
KeyStoreType com.ibm.wsspi.wssecurity.saml.config.issuer.KeyStoreType JKS The keystore type.
KeyStorePassword com.ibm.wsspi.wssecurity.saml.config.issuer.KeyStorePassword password The password of the keystore file (the password must be XOR encoded). For more information, read about encoding passwords in files.
KeyAlias com.ibm.wsspi.wssecurity.saml.config.issuer.KeyAlias soapprovider The alias of the signing private key as defined in the keystore.
KeyName com.ibm.wsspi.wssecurity.saml.config.issuer.KeyName CN=SOAPProvider, OU=TRL, O=IBM, ST=Kanagawa, C=JP The name of the signing private key as defined in the keystore file. This name is for reference and is not evaluated by the runtime.
KeyPassword com.ibm.wsspi.wssecurity.saml.config.issuer.KeyPassword password The password of the private key as defined in the keystore file (the password must be XOR encoded).
TrustStoreRef   name=myTrustStoreRef managementScope=(cell):myCell:(node):myNode A reference to a managed keystore in security.xml that contains the encrypting certificate.
TrustStorePath   app_server_root/etc/ws-security/samples/dsig-receiver.ks The location of the store file that contains the encrypting certificate.
Note: You must modify this value from the default value to match the path location for your system.
TrustStoreType   JKS The store type of the store file that contains the encrypting certificate.
TrustStorePassword   password The password for the store file that contains the encrypting certificate.
AttributeProvider   com.mycompany.SAML.AttributeProviderImpl Implementation class of attribute provider.
Note: The class must implement javax.security.auth.callback.CallbackHandler. The class should receive the com.ibm.websphere.wssecurity.callbackhandler.Saml11AttributeCallback or com.ibm.websphere.wssecurity.callbackhandler.Saml20AttributeCallback callback object, then update the SAMLAttribute list received from the getSAMLAttributes method invoked from that object.

[Updated in August 2013]For more information, please refer to "Adding attributes to self-issued SAML tokens using the API."[Updated in August 2013]

NameIDProvider   com.mycompany.SAML.NameIDProviderImpl Implementation class of name ID provider.
Note: The class must implement javax.security.auth.callback.CallbackHandler. The class should receive the com.ibm.websphere.wssecurity.callbackhandler.NameIDCallback callback object, then call the setSAMLNameID method on that object to update the NameID.

[Updated in August 2013]For more information, please refer to "Customizing the NameID for self-issued SAML tokens using the API."[Updated in August 2013]

Example

See the following example of a SAML token configuration properties file:
IssuerURI=http://www.websphere.ibm.com/SAML/SelfIssuer
TimeToLiveMilliseconds=3600000
KeyStorePath=${USER_INSTALL_ROOT}/etc/ws-security/samples/dsig-receiver.ks
KeyStoreType=JKS
KeyStorePassword={xor}LDotKTot
KeyAlias=soapprovider
KeyName=CN=SOAPProvider, OU=TRL, O=IBM, ST=Kanagawa, C=JP
KeyPassword={xor}LDotKTot
TrustStorePath=${USER_INSTALL_ROOT}/etc/ws-security/samples/dsig-receiver.ks
TrustStoreType=JKS
TrustStorePassword={xor}LDotKTot 
Reference topic    

Terms and conditions for information centers | Feedback

Last updated: April 20, 2014 08:46 PM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=rwbs_samltokenproperties
File name: rwbs_samltokenproperties.html