Web Services Security
Introduction and overview
Web Services Security (WSS) as specified by Oasis (http://www.oasis-open.org, based on Apache wss4j: http://ws.apache.org/wss4j) is a standard describing how user and credential information is embedded in the SOAP protocol header. The AuthStates in this chapter are used as pre-processing AuthStates to locate this information in the SOAP XML input from the calling proxy. After extracting identity data, a transition to an AuthState processing the authentication is required.
We support the following WSS standards:
- Web Services Security: UsernameToken Profile
- Web Services Security: X.509 Token Profile
- Web Services Security: SAML Token Profile
UsernameToken
This AuthState is used to extract the Username and Password elements from the SOAP/WSS security header and provide them as input to an AuthState supporting this authentication mechanism.
Description
The following table describes the characteristics of the AuthState.
| Topic | Description |
|---|---|
| Class | ch.nevis.esauth.auth.states.wss4j.UsernameToken |
| Logging | wss4j |
| Auditing | none |
| Properties | none |
| Methods | process (all events) |
| Input | soapheader (caller, required): the SOAP message (at least containing the SOAP header as a valid XML document) |
| isiwebuserid, isiwebpasswd derived from the username token in the SOAP header for processing by the next AuthState, supporting login-ID/password authentication. | |
| Transitions | ok: SOAP header was successfully verified and login-ID/password are extracted. |
| Output | see derived input |
| Errors | *1: invalid inputThe SOAP header was not found or did not contain the requiredUsernameandPassword elements. |
| Notes | none |
Example
<AuthState name="WSSAuth" class="ch.nevis.esauth.auth.states.wss4j.UsernameToken"
final="false">
<ResultCond name="ok" next="WSSLogin"/>
<Response value="AUTH_ERROR">
<Gui name="ErrorDialog" label="errordialog.label">
<GuiElem name="lasterror" type="error" label="${notes:lasterrorinfo}"
value="${notes:lasterror}"/>
</Gui>
</Response>
</AuthState>
<AuthState name="WSSLogin"
class="ch.nevis.esauth.auth.states.jndi.UseridPasswordAuthenticateState"
final="false">
...
</AuthState>
In case the authentication should also provide a SAML assertion "). For more details, in particular on the reverse proxy configuration, see the chapter on SOAP/HTTP(S) Proxying in the nevisProxy reference guide. |
You can use the WSSHeaderValidation AuthState to process any supported WSS header data.WSSHeaderValidation
This AuthState can be used to validate and extract tokens from messages sent according to the WSS SOAP Message Security specification. It implements the X.509 Certificate Token Profile, the SAML Token Profile and the UsernameToken Profile.
- The implementation of the X.509 Certificate Token Profile allows to extract the X.509 certificate from the SOAP message header for further processing by the X509 AuthState ").
- The implementation of the SAML Token Profile allows to verify and extract a SAML assertion for further processing, e.g., by the ServiceProviderState ").
- The implementation of the UsernameToken Profile allows to extract the Username and Password elements from a WSS security header for processing by other AuthStates (see chapter UsernameToken].
Description
The following table describes the characteristics of the AuthState.
| Topic | Description |
|---|---|
| Class | ch.nevis.esauth.auth.states.wss4.WSSHeaderValidation |
| Logging | wss4j |
| Auditing | none |
| Properties | cryptoimpl (class, org.apache.ws.security.components.crypto.Merlin)Implementation of the Apache interface org.apache.ws.security.components.crypto.Crypto to use. The property is intended to customize certificate handling and does not need to be changed. |
| callbackhandler (class, ch.nevis.esauth.auth.states.wss4j.WSSHeaderValidation)Class of the JAAS callback handler (javax.security.auth.callback.CallbackHandler) to use. The property is intended to customize user input handling and does not need to be changed. | |
| actors (string, "http://schemas.xmlsoap.org/soap/actor/next")Defines a space- or comma-separated list of actors that should be considered for WSS processing. The actor field is an attribute of the WSS element in the SOAP message header. If the client sends a non-empty actor, this attribute must be configured. | |
| timestampTtl (number, 300)Allows to configure a tolerance offset for the timestamp check: created-ttl < now < expired+ttl | |
| verifySignature (boolean,true)Allows to disable SignatureProcessing (disable XML signature check if a signature is present). This will only disable the signature verification of the WSS header. When the SAML Token Profile is used, the SAML token signature will still be verified. Disabling the verification of the SAML token signature is not possible at the moment. | |
| verifyTrust " for the configuration of a Java keystore for this purpose. | |
| bspCompliant (boolean, false)Sets the WS-I Basic Security Profile compliance mode. | |
| ignoreDataEncryption (boolean, false) ignoreKeyEncryption (boolean, false)Disables the encryption handlers for key and data reference processing in WSS4J in case we do not have a private key to decrypt XML-encrypted content. Problems with signature processing may occur in this case. | |
| issuerFilter (regexp, -)This filter can be used to select the correct certificate from the WSS header if multiple certificates are sent by the client. The regular expression is matched against the certificate's IssuerDN. | |
| extractX509SignerCertOnly (boolean, false)This attribute allows to enable tolerant data extraction from the WSS header without performing any security checks. This approach is necessary if nevisAuth does not have the private key to decrypt key material in the WSS header, which is required to verify the identity.This setup should only be used in production if the resulting authentication is verified by an additional XML firewall. | |
allowNamespaceQualifiedPasswordTypes (boolean, false)Enable this property to support password types qualified by namespaces. For example:<o:Password o:Type="**``<http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText>>" | |
| Methods | process (all events) |
| Input | soapheader (caller, required): the SOAP message (at least containing the SOAP header as a valid XML document) |
| derived: User certificate from the X509 token in the SOAP header for processing by the next AuthState supporting X509 authentication. | |
| Transitions | ok: SOAP header was successfully verified. |
| untoken: Same as "ok" but a more specific dispatching within the AuthEngine processing to an AuthState is possible that handles a userid/password authentication. | |
| bintoken: Same as "ok" but a more specific dispatching within the AuthEngine processing to an AuthState is possible that handles a X509 or other binary token authentication. | |
| samltoken: Same as "ok" but a more specific dispatching within the AuthEngine processing to an AuthState is possible that validates and consumes a SAML assertion. | |
| Output | see derived input (the topic "Input" in this table) |
| Errors | *51: Incomplete WSS/SOAP authentication request: missing WSS extension in the SOAP header* 51: Timestamp expired: WSS record not valid anymore |
| Notes | SAML Profile: saml.assertion: the SAML assertion transported in the WSS header |
Example
<AuthState name="WSSAuth" class="ch.nevis.esauth.auth.states.wss4j.WSSHeaderValidation"
final="false">
<ResultCond name="ok" next="WSSCert"/>
<Response value="AUTH_ERROR">
<Gui name="ErrorDialog" label="errordialog.label">
<GuiElem name="lasterror" type="error" label="${notes:lasterrorinfo}"
value="${notes:lasterror}"/>
</Gui>
</Response>
</AuthState>
<AuthState name="WSSCert" class="ch.nevis.esauth.auth.states.x509.X509Login"
final="false">
...
</AuthState>
In case the authentication should also provide a SAML assertion "). For more details, in particular on the reverse proxy configuration, see the chapter on SOAP/HTTP(S) Proxying in the nevisProxy reference guide. |