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.

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.

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.

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 that can be 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.

Avoid trouble: If you want 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

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	com.ibm.wsspi.wssecurity.saml.config.issuer.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.
Audience	com.ibm.wsspi.wssecurity.saml.config.issuer.Audience	https://company.com/something/whatsit	The value for the Audience element. You must specify only one value.
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. 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	https://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	com.ibm.wsspi.wssecurity.saml.config.issuer.TrustStoreRef	`name=myTrustStoreRef managementScope=(cell):myCell:(node):myNode`	A reference to a managed keystore in security.xml that contains 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 that contains the encrypting certificate. Note: You must modify this value from the default value to match the path location for your system.
TrustStoreType	com.ibm.wsspi.wssecurity.saml.config.issuer.TrustStoreType	JKS	The store type of the store file that contains the encrypting certificate.
TrustStorePassword	com.ibm.wsspi.wssecurity.saml.config.issuer.TrustStorePassword	`password`	The password for the store file that contains the encrypting certificate.
AttributeProvider	com.ibm.wsspi.wssecurity.saml.config.issuer.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. 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 that contains 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 this property to true if you want to generate an encrypted SAML token. The default value for this property is false. When generating a self-issued token with APIs, you can also indicate that you want 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. 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. For more information, refer to Customizing the NameID for self-issued SAML tokens using the API.
UseSha2ForSignature	com.ibm.wsspi.wssecurity.saml.config.issuer.UseSha2ForSignature	true	Set this property to `true` to use the SHA-2 signature algorithm, https://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=https://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