Web Services Security

Introduction and overview

Web Services Security (WSS) as specified by Oasis, based on Apache 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

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 (see chapter X509 authentication AuthState).
• The implementation of the SAML Token Profile allows to verify and extract a SAML assertion for further processing, e.g., by the ServiceProviderState (see chapter 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 (for example UseridPasswordAuthenticateState).

Description

The following table and chapters describe the characteristics of the AuthState.

Topic	Description
Class	ch.nevis.esauth.auth.states.wss4.WSSHeaderValidation
Logging	wss4j
Auditing	none
Marker	none
Methods	process (all events)

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 [sec], 300)

  Allows to configure a tolerance offset for the timestamp check: created-ttl < now < expired+ttl

• bspCompliant (boolean, false)

  Sets the WS-I Basic Security Profile compliance mode.

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

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.

Output

See derived input

Errors

• lasterror=1

  lasterrorinfo=

Notes

• saml.assertion

  The SAML assertion transported in the WSS header

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

UsernameToken Example

<AuthState name="WSSAuth" class="ch.nevis.esauth.auth.states.wss4j.WSSHeaderValidation"
 final="false">
  <ResultCond name="untoken" 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>

info

In case the authentication should also provide a SAML assertion (possibly replacing the X509 WSS token in the SOAP header), a post-processing AuthState may be used (see chapter SAML AuthStates). For more details, in particular on the reverse proxy configuration, see the chapter on SOAP/HTTP(S) Proxying in the nevisProxy reference guide.