Web services security SAML token custom properties

When you configure a web services security SAML token, you can configure name-value pairs of data, where the name is a property key and the value is a string value that you can use to set internal system configuration properties. You can use these configuration properties, along with the options provided in the administrative console, to control how the SAML token is generated or consumed.

To configure these SAML custom properties, in the administrative console, either:

Expand Services.
Select Service provider or Service client
Click on the appropriate application in the Name column.
Click on the appropriate binding in the Binding column.
You must have previously attached a policy set and assigned a binding.

Expand Applications > Application Types and click WebSphere enterprise applications.
Select an application that contains Web services. The application must contain a service provider or a service client.
Under the Web Services Properties heading, click Service provider policy sets and bindings or Service client policy sets and bindings.
Select a binding. You must have previously attached a policy set and assigned an application-specific binding.

Then complete the following steps:

Click WS-Security in the Policies table.
Under the Main Message Security Policy Bindings heading, click Authentication and protection.
Under the Authentication tokens heading, click the name of the authentication token.
Supported configurations: You can use the token, which is processed by the generic security token login module, for authentication only. You cannot use the token as a protection token.
Under the Additional Bindings heading, click Callback handler.
Under the Custom Properties heading, enter the name and value pairs.

The following sections list the custom properties and indicate how each custom property is used.

SAML token generator custom properties

The following table lists the callback handler custom properties that can only be used to configure SAML token generator bindings.

Table 1. SAML token callback handler custom properties for token generator bindings only . This table contains the custom property name, its values, and a short description.
Name	Values	Description
`appliesTo`	This custom property does not have a default value.	Specifies the AppliesTo to use for the requested SAML token when a WSS API is used.
`audienceRestriction`	Valid values are `true` and `false`. The default behavior is `true`, which includes AudienceRestrictionCondition in the SAML token.	This property applies only to self-issued SAML tokens. Use this custom property to specify whether the AudienceRestrictionCondition element is included in the SAML token.
`authenticationMethod`	This custom property does not have a default value.	This property applies only to self-issued SAML tokens. Use this custom property to specify the value for the AuthenticationMethod attribute on the AuthenticationStatement element in the SAML token. When this custom property is specified, the Subject will be contained in an AuthenticationStatement instead of an AttributeStatement.
`cacheCushion`	The default value is `5 minutes`.	The amount of time, in minutes, before the expiration time of a SAML token expires and a new token must be issued. For example, if the `cacheCushion` is set to `5` minutes and the SAML token will expire in `2` minutes, it will not be re-used; a new SAML token will be issued. When the runtime is in the process of caching a SAML token, a token that is beyond the cache cushion will not be cached.
`cacheToken`	Valid values are `true` and `false`. The default behavior is `true`, which allows SAML token caching for reuse.	Use this custom property to specify whether a SAML token can be cached for reuse.
`com.ibm.webservices.wssecurity.platform.SAMLIssuerConfigDataPath`	The default value is `${USER_INSTALL_ROOT}/config/cells/${WAS_CELL_NAME}/sts/SAMLIssuerConfig.propertie`s	The file path to the configuration data to use when generating a self-issued SAML token.
`com.ibm.wsspi.wssecurity.saml.client.SamlTokenCacheEntries`	The default value is `250`.	Use this JVM custom property to specify the maximum number of cache entries that can be maintained.
`com.ibm.wsspi.wssecurity.saml.client.SamlTokenCacheTimeout`	The default value is `60 minutes`.	This property is used only for SAML tokens for which the expiration time is unknown (tokens that are encrypted or an expiration is not included with the token in the response from the STS). For SAML tokens for which the expiration time is unknown, the `SamlTokenCacheTimeout` is used to substitute for the expiration time. For a new SAML token that will enter the cache under this criteria, its expiration time will be `(current_time)+SamlTokenCacheTimeout`. The conditions described for the `cacheCushion` property will still apply, so keep the `cacheCushion` value in mind when altering the value for the `SamlTokenCacheTimeout`.
`confirmationMethod`	Valid values include `bearer`, `holder-of-key`, and `sender-vouches`. The default value is `bearer`.	The SAML token subject ConfirmationMethod.
`com.ibm.wsspi.wssecurity.saml.get.SamlToken`	Valid values are `true` or `false`. The default value is `false`.	Use this custom property to get the SAML token to RequestContext.
`com.ibm.wsspi.wssecurity.saml.put.SamlToken`	Valid values are `true` or `false`. The default value is `false`.	Use this custom property to set the SAML token to RequestContext.
`failOverToTokenRequest`	Valid values are `true` or `false`. The default value is `true`, which means that the web services security runtime always issues a new SAML token if the input token is invalid.	Use this custom property to specify whether the web services security runtime should use the attached policy set to issue a new SAML token if the input SAML token in the RequestContext is invalid.
`recipientAlias`	This custom property does not have a default value.	The target service alias for a certificate.
`signToken`	Valid values are `true` or `false`. The default value is `false`.	Use this custom property to specify whether a SAML token should be signed with an application message.
`sslConfigAlias`	If a value is not specified for this property, the default SSL alias defined in your system's SSL configuration is used. This property is optional.	The alias to an SSL configuration that a WS-Trust client uses to request a SAML token.
`stsURI`	This custom property does not have a default value.	The SecurityTokenService (STS) address.
`keySize`	This custom property does not have a default value.	The KeySize when requesting a SecretKey from STS.
`tokenRequest`	Valid values include `issue`, `propagation`,`issueByWSCredential`, and `issueByWSPrincipal`. The default value is `issue`.	The SAMLToken request method. For more information about the values that can be specified for this property, see the topic Propagating SAML tokens
`tokenType`	This custom property does not have a default value.	Use this custom property to set the required token type to `SAMLGenerateCallback`
`usekeyType`	This custom property is optional. The valid values are `KeyValue`, `X509Certificate`, and `X509IssuerSerial`.	Use this custom property to specify the Usekey type, which tells the client to generate a specific type of key Information.
`WSSConsumingContext`	This custom property does not have a default value.	Use this custom property to specify the `WSSConsumingContext` object that the WS-Trust client uses to request a SAML token.
`WSSGenerationContext`	This custom property does not have a default value.	Use this custom property to specify the `WSSGenerationContext` object that the WS-Trust client uses to request a SAML token.
`NameID`	This custom property does not have a default value.	This property sets the `NameID` in the Subject of a self-issued SAML token. When the generator is configured to self-issue a token, if the `NameID` property is not specified, an attempt is made to generate a token from a SAML token in the runAs subject. If no SAML token is present on the runAs subject, the token is built from scratch and the `NameID` in the Subject will be set to UNAUTHENTICATED. For more information on generating self-issued SAML tokens using settings in the WS-Security bindings, see SAML Issuer Config Properties.

SAML token consumer custom properties

The following table lists the callback handler custom properties that can only be used to configure SAML token consumer bindings.

Table 2. SAML token callback handler custom properties for token consumer bindings only . This table contains the custom property name, its values, and a short description.
Name	Values	Description
`allowUnencKeyInHok`	Valid values are `true` or `false`. The default value is `true`, which means that unencrypted keys are allowed.	Use this property to direct the SAML token consumer to accept an unencrypted key in a SAML holder-of-key token.
`com.ibm.wsspi.wssecurity.saml.signature.SignatureCacheEntries`	An integer. The default value is `1000`.	The number of signature cache entries that can be maintained. for a SAML consumer token.
`com.ibm.wsspi.wssecurity.saml.signature.SignatureCacheTimeout`	An integer. The default value is `60 minutes`.	The number of minutes a SAML token is to be cached. A signature validation does not need to be repeated while the SAML token is cached.
`keyAlias`	This custom property does not have a default value.	The alias of the decrypting private key as defined in the keystore.
`keyName`	This custom property does not have a default value.	The name of the decrypting private key as defined in the keystore file. This name is for reference and is not evaluated by the runtime.
`keyPassword`	This custom property does not have a default value.	The password of the decrypting private key as defined in the keystore file. The password can be XOR encoded. For more information, read about encoding passwords in files.
`keyStorePassword`	This custom property does not have a default value.	The password of the keystore file (the password should be XOR encoded). For more information, read about encoding passwords in files.
`keyStorePath`	This custom property does not have a default value.	The file path of the keystore file that contains the decrypting key.
`keyStoreRef`	This custom property does not have a default value.	A reference to a managed keystore in security.xml that contains the decrypting key. Sample: `name=myKeyStoreRef managementScope=(cell):myCell:(node):myNode`
`keyStoreType`	This custom property does not have a default value.	The keystore type of the keystore file.
`signatureRequired`	The default value is `true`.	Use this custom property to specify whether a signature is required on a SAML assertion. If any trustedSubjectDN_n custom properties are defined when this property is set to false, you get a CWWSS7542E message when a SAML token is consumed.
`trustAnySigner`	The default value is `false`.	Use this custom property to specify whether a recipient can trust any certificate that signs a SAML assertion.
`trustedAlias`	This custom property does not have a default value.	The trusted STS certificate's alias for a SAML consumer token.
`trustedIssuer_`	The name is specified as `trustedIssuer_n` where `n` is an integer. This custom property does not have a default value.	The name of a trusted issuer. If `n` is the same number for a `trustedIssuer_n` entry and a `trustedSubjectDN_n` entry, the token must match both conditions to be trusted.
`trustedSubjectDN_`	The value specified must be in the format `trustedSubjectDN_n`, where `n` is an integer. This custom property does not have a default value.	The X509Certificate's SubjectDN name for the trusted issuer. If you set this property when `signatureRequired=false`, you get a CWWSS7542E message when a SAML token is consumed. If `n` is the same number for a `trustedIssuer_n` entry and a `trustedSubjectDN_n` entry, the token must match both conditions to be trusted.
`trustStorePassword`	This custom property does not have a default value.	The truststore password for a SAML consumer token.
`trustStorePath`	This custom property does not have a default value.	The truststore path for a SAML consumer token.
`trustStoreRef`	This custom property does not have a default value.	The truststore reference for a SAML consumer token. Sample: `name=myTrustStoreRef managementScope=(cell):myCell:(node):myNode`
`trustStoreType`	This custom property does not have a default value.	The keystore type for the truststore.
`validateAudienceRestriction`	Valid values are `true` or `false`. The default value is `false` which means that an AudienceRestriction assertion validation is not required.	Use this custom property specify whether an AudienceRestriction assertion must be validated.
`validateOneTimeUse`	Valid values are `true` or `false`. The default value is `true`, which means that OneTimeUse assertion validation is required.	Use this custom property to specify whether a OneTimeUse assertion in SAML 2.0, or a DoNotCacheCondition in SAML 1.1 must be validated.
`CRLPATH`	This custom property does not have a default value.	The file path to the list of revoked certificates for a SAML consumer token.
`X509PATH`	This custom property does not have a default value.	The intermediate X509 certificate file path for a SAML consumer token.
`CRLPATH_`	The value specified must be in the format `trustedSubjectDN_n`, where `n` is an integer. This custom property does not have a default value.	The file path to the list of revoked X509 certificates for a SAML consumer token.
`X509PATH_`	The value specified must be in the format `X509_path_n`, where `n` is an integer. This custom property does not have a default value.	The file path for the intermediate X509 certificate for a SAML consumer token.

SAML token custom properties for both token generator and token consumer

The following table lists the callback handler custom properties that can be used to configure both SAML token generator and SAML token consumer bindings.

Table 3. SAML token callback handler custom properties for token generator and token consumer bindings . This table contains the custom property name, its values, and a short description.
Name	Values	Description
`clockSkew`	The default value is `3 minutes`.	The time, in minutes, an adjustment to the times in the self-issued SAML token that the SAMLGenerateLoginModule creates. The clockSkew custom property is set on the Callback handler of the SAML token generator that uses the SAMLGenerateLoginModule class. The value specified for this custom property must be numeric and is specified in minutes. When a value is specified for this custom property, the following time adjustments are made in the self-issued SAML token that the SAMLGenerateLoginModule creates: The new NotBefore time setting equals the initial NotBefore time setting, minus the amount of time specified for the clockSkew custom property. The new NotAfter time setting equals the initial NotAfter time setting, plus the amount of time specified for the clockSkew custom property.
`clientLabel`	This custom property does not have a default value.	The client label, in bytes, to use for the derived keys whenever a WSS API is used with the requested SAML token.
`serviceLabel`	This custom property does not have a default value.	The service label, in bytes, to use for the derived keys whenever a WSS API is used with the requested SAML token.
`keylength`	This custom property does not have a default value.	The derived key length, in bytes, to use for the derived keys whenever a WSS API is used with the requested SAML token.
`nonceLength`	The default value is `128`.	The derived nonce length, in bytes, to use for the derived keys whenever a WSS API is used with the requested SAML token.
`requireDKT`	The default value is `false`.	Use this custom property to specify an option for the derived keys whenever a WSS API is used with the requested SAML token.
`useImpliedDKT`	The default value is `false`.	Use this custom property to specify an option that is used with Implied derived keys whenever a WSS API is used with the requested SAML token.

SAML token generator properties for self-issued tokens

The following table lists the callback handler custom properties that can only be used to configure SAML token generator bindings for self-issued SAML tokens.

Table 4. SAML token callback handler custom properties for generating self-issued SAML tokens. . This table contains the custom property name, its values, and a short description.
Policy bindings property name	Sample property value	Property description
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.
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.
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.
com.ibm.wsspi.wssecurity.saml.config.issuer.IssuerURI	https://www.websphere.ibm.com/SAML/SelfIssuer	The URI of the issuer.
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).
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.
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.
com.ibm.wsspi.wssecurity.saml.config.issuer.KeyStoreType	JKS	The keystore type.
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.
com.ibm.wsspi.wssecurity.saml.config.issuer.KeyAlias	`soapprovider`	The alias of the signing private key as defined in the keystore.
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.
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).
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.
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.
com.ibm.wsspi.wssecurity.saml.config.issuer.TrustStoreType	JKS	The store type of the store file that contains the encrypting certificate.
com.ibm.wsspi.wssecurity.saml.config.issuer.TrustStorePassword	`password`	The password for the store file that contains the encrypting certificate.
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.
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.
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.
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, please refer to Customizing the NameID for self-issued SAML tokens using the API.
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.

Trust client custom properties

The trust client is an API. The custom properties for the trust client are defined in the trust client interface: https://www.ibm.com/docs/en/SSAW57_8.5.5/com.ibm.websphere.javadoc.doc/web/spidocs/com/ibm/wsspi/wssecurity/core/token/config/package-summary.html

When the trust client is used with a SAML token generator, the trust client properties that are listed in the trust client interface can be configured in the SAML token generator callback handler. You must configure the string to which the constant listed in the interface resolves, not the constant itself. For instance, use the value of wstrustClientIssuerAddress, not the ISSUER_ADDRESS constant.

The following table lists the custom properties that can be used to configure trust client. When used with a SAML token generator, these custom properties are added to the SAML token generator callback handler.

Table 5. Custom properties for the trust client. . This table contains the custom property name, its values, and a short description.
Name	Values	Description
`com.ibm.wsspi.wssecurity.trust.client.TrustServiceCacheEntries`	The default value is `1000`.	The maximum number of STS service instance cache entries that can be maintained.
`com.ibm.wsspi.wssecurity.trust.client.TrustServiceCacheTimeout`	The default value is `60 minutes`.	The length of time, in minutes, an STS service instance can be kept in a client side cache.
`keyType`	The following keyTypes can be specified for WS-Trust 1.2: http://schemas.xmlsoap.org/ws/2005/02/trust/PublicKey http://schemas.xmlsoap.org/ws/2005/02/trust/SymmetricKey The following keyTypes can be specified for WS-Trust 1.3: http://docs.oasis-open.org/ws-sx/ws-trust/200512/PublicKey ttp://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKey http://docs.oasis-open.org/ws-sx/ws-trust/200512/Bearer	The keyType to use when making a WS-Trust request to STS.
`wstrustActAsRequired`	Valid values are `true` and `false`.The default value is `false`.	Set this property to true when a SAML token is to be inserted into an STS request in the ActAs element. The SAML token must exist on the current runAs Subject or on the JAAS login shared state object. A token in the JAAS login shared state takes precedence over one in the runAs subject. If both onBehalfOfRequired and actAsRequired are set to true, only the OnBehalfOf element will be inserted into the STS request. For more information, see Generating and consuming SAML tokens using stacked JAAS login modules.
`wstrustActAsTokenType`	Valid values are `http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1` and `http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0`. The default value is the type of the token being generated with the SAML generator callback handler.	Set this property to the token type of the SAML token to insert into the message in the ActAs element in the STS request.
`wstrustActAsReIssue`	Valid values are `true` and `false`.The default value is `false`.	Set this property to `true` to insert a SAML token into the ActAsReIssue element in the STS request a SAML token from the runAs subject that is re-issued with signature and encryption settings in the SAML generator callback handler. A SAML token obtained from the JAAS login shared state object cannot be re-issued.
`wstrustClientBinding`	This custom property does not have a default value.	A binding name for the WS-trust client.
`wstrustClientBindingScope`	This custom property does not have a default value.	The binding scope for the policy set that is attached to the WS-Trust client.
`wstrustClientCollectionRequest`	Valid values are `true` or `false`. The default value is `false` which means that a RequestSecurityToken is used instead of a RequestSecurityTokenCollection.	Use this custom property to specify whether a RequestSecurityTokenCollection is required in a WS-Trust request.
`wstrustClientPolicy`	This custom property does not have a default value.	The policy set name for a WS-Trust client.
`wstrustClientSoapVersion`	Valid values are `1.1` and `1.2`. If no value is specified, the SOAP version defaults to SOAP version that the application client is using.	The SOAP version in a WS-Trust request.
`wstrustClientWSTNamespace`	The default value is `trust13`. Valid values are `trust12` and `trust13`.	The WS-Trust namespace for a WS-Trust request.
`wstrustOnBehalfOfRequired`	Valid values are `true` and `false`. The default value is `false`.	Set this property to `true` when a SAML token is to be inserted into an STS request in the OnBehalfOf element. The SAML token must exist on the current runAs Subject or on the JAAS login shared state object. A token in the JAAS login shared state takes precedence over one in the runAs subject. For more information, see Generating and consuming SAML tokens using stacked JAAS login modules.
`wstrustOnBehalfOfTokenType`	Valid values are `http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1` and `http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0`. The default value is the type of the token being generated with the SAML generator callback handler.	Set this property to the token type of the SAML token to insert into the message in the OnBehalfOf element in the STS request.
`wstrustOnBehalfOfReIssue`	Valid values are `true` and `false`.The default value is `false`.	Set this property to `true` to insert a SAML token into the OnBehalfOf element in the STS request a SAML token from the runAs subject that is re-issued with signature and encryption settings in the SAML generator callback handler. A SAML token obtained from the JAAS login shared state object cannot be re-issued.