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 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.
- 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.
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
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