SAML Issuer Config Properties

SAML Issuer Config Properties

When creating a new self-issued SAML token, we 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.

The SAML issuer config properties can be stored in a property file called SAMLIssuerConfig.properties. The SAMLIssuerConfig.properties file usage is deprecated in WAS version 8.

Starting with WAS version 8, we 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. We can also set the properties in the WS-Security policy bindings using the setSAMLIssuerConfigInBinding admin task. See Managing self-issue SAML token configuration using wsadmin commands.

In the WS-Security bindings, these properties can also be set on the SAML token consumer or SAML token consumer callback handler. The precedence, from high to low, is: callback handler, token consumer, general custom properties.

If the SAML token generator is used to self-issue a SAML token using the WS-Security bindings, there are two paths used to generate the token:

Generate the self-issued token from scratch.
Generate the self-issued token based on a token that is present in the runAs subject. If no token is present in the subject, the token will be built from scratch.

To ensure that the self-issued token is generated from scratch, the NameID custom property must be set on the SAML token generator callback handler. If the NameID property is not set on token generator callback handler and there was no SAML token in the runAs subject, then NameID in the Subject in the token will be set to UNAUTHENTICATED.
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

Provider configuration properties.

SAMLIssuerConfig.properties property name Policy bindings property name Sample property value Property description
com.ibm.wsspi.wssecurity.saml.config.issuer.oldEnvelopedSignature true Use only if we are setting the com.ibm.wsspi.wssecurity.dsig.enableEnvelopedSignatureProperty JVM custom property to true. See the topic JVM custom properties for a description of when we might want to use this JVM custom property.
IssuerFormat com.ibm.wsspi.wssecurity.saml.config.issuer.IssuerFormat urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName Value for the Format attribute of the Issuer element in the SAML token.
To add the Format attribute to the Issuer element, 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. 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 containing 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 containing the signing key.

We must modify this value from the default value to match the path location for our 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). See 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 com.ibm.wsspi.wssecurity.saml.config.issuer.TrustStoreRef name=myTrustStoreRef managementScope=(cell):myCell:(node):myNode A reference to a managed keystore in security.xml containing the encrypting certificate.
TrustStorePath com.ibm.wsspi.wssecurity.saml.config.issuer.TrustStorePath app_server_root/etc/ws-security/samples/dsig-receiver.ks The location of the store file containing the encrypting certificate.

We must modify this value from the default value to match the path location for our system.
TrustStoreType com.ibm.wsspi.wssecurity.saml.config.issuer.TrustStoreType JKS The store type of the store file containing the encrypting certificate.
TrustStorePassword com.ibm.wsspi.wssecurity.saml.config.issuer.TrustStorePassword password The password for the store file containing the encrypting certificate.
AttributeProvider com.ibm.wsspi.wssecurity.saml.config.issuer.AttributeProvider com.mycompany.SAML.AttributeProviderImpl Implementation class of attribute provider.

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.
For more information, please refer to Adding attributes to self-issued SAML tokens using the API.

EncryptingAlias com.ibm.wsspi.wssecurity.saml.config.issuer.EncryptingAlias soaprecipient The entry in the store file provided on the TrustStore property containing the public certificate that will be used to encrypt the SAML token. When generating a self-issued token with APIs, an alias set on the RequesterConfig using the setKeyAliasForAppliesTo method will take precedence over the value supplied for this property.
EncryptSAML com.ibm.wsspi.wssecurity.saml.config.issuer.EncryptSAML true Set to true to generate an encrypted SAML token. The default value for this property is false.
When generating a self-issued token with APIs, we can also indicate to encrypt the SAML token using the setEncryptSAML(true) method on the RequesterConfig object. The SAML token will be encrypted if either setEncryptSAML=true on the RequesterConfig object or the EncryptSAML custom property is set to true.

NameIDProvider com.ibm.wsspi.wssecurity.saml.config.issuer.NameIDProvider com.mycompany.SAML.NameIDProviderImpl Implementation class of name ID provider.

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.
For more information, please refer to Customizing the NameID for self-issued SAML tokens using the API.

UseSha2ForSignature com.ibm.wsspi.wssecurity.saml.config.issuer.UseSha2ForSignature true Set to true to use the SHA-2 signature algorithm, http://www.w3.org/2001/04/xmldsig-more#rsa-sha256, when signing the SAML token.

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 
Propagate SAML tokens
Encoding passwords in files
Manage self-issue SAML token configuration using wsadmin commands
Add attributes to self-issued SAML tokens using the API
Customize the NameID for self-issued SAML tokens using the API
Web services security SAML token custom properties

SAMLIssuerConfig.properties property name	Policy bindings property name	Sample property value	Property description
com.ibm.wsspi.wssecurity.saml.config.issuer.oldEnvelopedSignature	true	Use only if we are setting the com.ibm.wsspi.wssecurity.dsig.enableEnvelopedSignatureProperty JVM custom property to true. See the topic JVM custom properties for a description of when we might want to use this JVM custom property.
IssuerFormat	com.ibm.wsspi.wssecurity.saml.config.issuer.IssuerFormat	urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName	Value for the Format attribute of the Issuer element in the SAML token. To add the Format attribute to the Issuer element, 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. 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 containing 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 containing the signing key. We must modify this value from the default value to match the path location for our 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). See 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	com.ibm.wsspi.wssecurity.saml.config.issuer.TrustStoreRef	name=myTrustStoreRef managementScope=(cell):myCell:(node):myNode	A reference to a managed keystore in security.xml containing the encrypting certificate.
TrustStorePath	com.ibm.wsspi.wssecurity.saml.config.issuer.TrustStorePath	app_server_root/etc/ws-security/samples/dsig-receiver.ks	The location of the store file containing the encrypting certificate. We must modify this value from the default value to match the path location for our system.
TrustStoreType	com.ibm.wsspi.wssecurity.saml.config.issuer.TrustStoreType	JKS	The store type of the store file containing the encrypting certificate.
TrustStorePassword	com.ibm.wsspi.wssecurity.saml.config.issuer.TrustStorePassword	password	The password for the store file containing the encrypting certificate.
AttributeProvider	com.ibm.wsspi.wssecurity.saml.config.issuer.AttributeProvider	com.mycompany.SAML.AttributeProviderImpl	Implementation class of attribute provider. 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. For more information, please refer to Adding attributes to self-issued SAML tokens using the API.
EncryptingAlias	com.ibm.wsspi.wssecurity.saml.config.issuer.EncryptingAlias	soaprecipient	The entry in the store file provided on the TrustStore property containing the public certificate that will be used to encrypt the SAML token. When generating a self-issued token with APIs, an alias set on the RequesterConfig using the setKeyAliasForAppliesTo method will take precedence over the value supplied for this property.
EncryptSAML	com.ibm.wsspi.wssecurity.saml.config.issuer.EncryptSAML	true	Set to true to generate an encrypted SAML token. The default value for this property is false. When generating a self-issued token with APIs, we can also indicate to encrypt the SAML token using the setEncryptSAML(true) method on the RequesterConfig object. The SAML token will be encrypted if either setEncryptSAML=true on the RequesterConfig object or the EncryptSAML custom property is set to true.
NameIDProvider	com.ibm.wsspi.wssecurity.saml.config.issuer.NameIDProvider	com.mycompany.SAML.NameIDProviderImpl	Implementation class of name ID provider. 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. For more information, please refer to Customizing the NameID for self-issued SAML tokens using the API.
UseSha2ForSignature	com.ibm.wsspi.wssecurity.saml.config.issuer.UseSha2ForSignature	true	Set to true to use the SHA-2 signature algorithm, http://www.w3.org/2001/04/xmldsig-more#rsa-sha256, when signing the SAML token.