Background to common security configuration
From Apache CXF 3.1.0, the WS-SecurityPolicy and the XML Security (JAX-RS) components in CXF share a common set of configuration tags. Previously, the configuration tags were all defined in the SecurityConstants class in the cxf-rt-ws-security module. The JAX-RS XML Security component then referenced these configuration tags directly, which meant that the XML Security component had to have a dependency on a SOAP module, which was not ideal.
From Apache CXF 3.1.0, the cxf-rt-security module is now shared between both the WS-Security and JAX-RS XML Security modules, and contains a SecurityConstants class that defines security constants used by both stacks. These configuration tags are exactly the same as a set of previous configuration tags found in the WS-Security SecurityConstants class in previous releases, except that the prefix is now "security" (was "ws-security"). Here are the new set of configuration tags:
User properties
security.username | The user's name. It is used differently by each of the Security functions, see here for more information. |
security.password | The user's password when "security.callback-handler" is not defined. It is currently only used for the case of adding a password to a UsernameToken. |
security.signature.username | The user's name for signature. It is used as the alias name in the keystore to get the user's cert and private key for signature. See here for more information. |
| security.signature.password CXF 3.3.2 | The user's password for signature when "security.callback-handler" is not defined. |
security.encryption.username | The user's name for encryption. It is used as the alias name in the keystore to get the user's public key for encryption. See here for more information. |
Callback Class and Crypto properties
security.callback-handler | The CallbackHandler implementation class used to obtain passwords. |
security.saml-callback-handler | The SAML CallbackHandler implementation class used to construct SAML Assertions. |
security.signature.properties | The Crypto property configuration to use for signature, if "security.signature.crypto" is not set instead. |
security.encryption.properties | The Crypto property configuration to use for encryption, if "security.encryption.crypto" is not set instead. |
security.signature.crypto | A Crypto object to be used for signature. If this is not defined then "security.signature.properties" is used instead. |
security.encryption.crypto | A Crypto object to be used for encryption. If this is not defined then "security.encryption.properties" is used instead. |
Note: for Symmetric bindings that specify a protection token, the security-encryption properties are used.
constant | default | definition |
security.enableRevocation | false | Whether to enable Certificate Revocation List (CRL) checking or not when verifying trust in a certificate. |
| security.enable.unsigned-saml-assertion.principal | false | Whether to allow unsigned saml assertions as SecurityContext Principals. The default is false. Note that "unsigned" refers to an internal signature. Even if the token is signed by an external signature (as per the "sender-vouches" requirement), this boolean must still be configured if you want to use the token to set up the security context. |
| security.validate.saml.subject.conf | true | Whether to validate the SubjectConfirmation requirements of a received SAML Token. |
| security.sc.jaas-subject | true | Set this to "false" if security context must not be created from JAAS Subject. |
| security.validate.audience-restriction | (varies) | If this is set to "true", then IF the SAML Token contains Audience Restriction URIs, one of them must match one of the values of the AUDIENCE_RESTRICTIONS property. The default is "true" for SOAP services in CXF 3.0.x, and "false" for 2.7.x. The default is "false" for REST services. |
Non-boolean Security Configuration parameters
security.saml-role-attributename | The attribute URI of the SAML AttributeStatement where the role information is stored. The default is "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/role". |
security.subject.cert.constraints | A String of regular expressions (separated by the value specified for "security.cert.constraints.separator") which will be applied to the subject DN of the certificate used for signature validation, after trust verification of the certificate chain associated with the certificate. These constraints are not used when the certificate is contained in the keystore (direct trust). |
| security.cert.constraints.separator CXF 3.3.3 / 3.2.10 | The separator that is used to parse certificate constraints configured via "security.subject.cert.constraints". By default it is a comma. |
| security.audience-restrictions CXF 3.1.13 | A comma separated String corresponding to a list of audience restriction URIs. The default value for this property contains the request URL and the Service QName. If the AUDIENCE_RESTRICTION_VALIDATION property is "true", and if a received SAML Token contains audience restriction URIs, then one of them must match one of the values specified in this property. |
Note: From CXF 3.1.3 onwards. Prior to CXF 3.1.3 these tags had a "ws-" prefix. The older tags will still work for backwards compatibility reasons.
security.sts.client | A reference to the STSClient class used to communicate with the STS. |
security.sts.applies-to | The "AppliesTo" address to send to the STS. The default is the endpoint address of the service provider. |
security.sts.token.usecert | If true, writes out an X509Certificate structure in UseKey/KeyInfo. If false (the default), writes out a KeyValue structure instead. |
security.sts.token.do.cancel | Whether to cancel a token when using SecureConversation after successful invocation. The default is "false". |
| security.issue.after.failed.renew | Whether to fall back to calling "issue" after failing to renew an expired token. The default is "true". |
security.cache.issued.token.in.endpoint | Set this to "false" to not cache a SecurityToken per proxy object in the IssuedTokenInterceptorProvider. This should be done if a token is being retrieved from an STS in an intermediary. The default value is "true". |
security.sts.disable-wsmex-call-using-epr-address | Whether to avoid STS client trying send WS-MetadataExchange call using STS EPR WSA address when the endpoint contract contains no WS-MetadataExchange info. The default value is "false". |
security.sts.token.crypto | A Crypto object to be used for the STS. See here for more information. |
security.sts.token.properties | The Crypto property configuration to use for the STS. See here for more information. |
security.sts.token.username | The alias name in the keystore to get the user's public key to send to the STS for the PublicKey KeyType case. |
security.sts.token.act-as | The token to be sent to the STS in an "ActAs" field. See here for more information. |
security.sts.token.on-behalf-of | The token to be sent to the STS in an "OnBehalfOf" field. See here for more information. |
| security.issue.after.failed.renew | Whether to call "Issue" if a token "Renew" fails. Some STSs do not support the renew binding. Defaults to "true". |
| security.sts.token.imminent-expiry-value | The value in seconds within which a token is considered to be expired by the client, i.e. it is considered to be expired if it will expire in a time less than the value specified by this tag. The default value is "10" for CXF 3.0.2+, and "0" for CXF 2.7.13+. |
| security.sts.token.cacher.impl CXF 3.1.11 | An implementation of the STSTokenCacher interface, if you want to plug in custom caching behaviour for STS clients. The default value is the DefaultSTSTokenCacher. |
| security.sts.check.for.recursive.call CXF 3.3.3/3.2.10 | Check that we are not invoking on the STS using its own IssuedToken policy - in which case wewill end up with a recursive loop. This check might be a problem in the unlikely scenario that the remote endpoint has the same service / port QName as the STS, so this configuration flag allows to disable this check for that scenario. The default is "true". |
Backwards compatibility
Users of Apache CXF prior to 3.1.0 do not need to make any adjustment to their code or spring files. The older "ws-" prefix associated with the configuration tags above will continue to be accepted.
