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.
or
- Expand WebSphere enterprise applications. and click
- 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.
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.properties | 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.
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 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.
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:
|
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.
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.
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:
The following keyTypes can be specified for WS-Trust 1.3:
|
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. |