SOAP web services

nevisAuth provides SOAP web services that can be configured to listen on customized URL paths. The following chapters describe the SOAP web services currently provided by nevisAuth.

caution

The definition of custom SOAP web services is outside the scope of this documentation. Writing custom SOAP web services in nevisAuth is discouraged.

The generic configuration syntax of a WebService is as follows:

<WebService class="my.ClassName" name="myServiceName"
      uri="/nevisauth/services/myService" SSODomain="SERVICE_DOMAIN">
   <Mapping from="xpath://OnBehalfOf/UsernameToken/Username/text()"
      to="usrName" scope="inargs" />
   <Mapping...

   <Method name="authenticate" if="${inargs:usrName}">
      <Mapping...
   </Method>
   <Method...
 
   <property name="thisProp" value="true" />
   <property...
</WebService>

Element	Attribute	Description
WebService	Defines an instance of a WebService that accepts incoming requests, maps them to nevisAuth requests and forwards them to the AuthEngine. AuthResponses are translated to responses of the WebService and returned to the client.
	class required	Fully qualified class name of the WebService class.
	name required	The name of the WebService, for informative purposes.
	uri required	The URI of the WebService. This URI must start with /nevisauth/services/.
	SSODomain required	The authentication domain from which incoming requests shall be dispatched.
Mapping	Mappings define how a request of the WebService is translated to an AuthRequest for the AuthEngine. This element may be defined with the WebService element or within Method constructs for translations that only apply under certain circumstances.
	from required	An expression that identifies a value from the incoming request. This value may be an XPath expression (starting with "xpath:...") or a key defined by the service implementation.
	to required	A variable name that will contain the incoming value.
	scope optional, default: inargs	The scope of the variable. May be one of {inargs, inctx, sess}.
	filter optional	The filter that should be applied to the from value before being propagated to the to variable.
Method	The Method element defines the authentication operation used to process an incoming request. Conditions may be specified to decide between several options and a Method may contain additional, specific Mapping elements.
	name required	The method used to process an incoming request. Must be one of {authenticate,stepup,unlock,logout}.
	if optional	A variable expression that must evaluate to a value for this method to be selected.
Property	The WebService implementation may be configured using property elements. The values of the elements may contain variable expressions.
	name	The name of a configuration property for the WebService implementation.
	value	The value of the property. This may be a variable expression.

SAML artifact resolution service

The SAML Artifact Resolution Service is a SOAP WebService which allows to retrieve a SAML message in exchange for a SAML artifact. It can be used on the identity provider and the service provider side and therefore to transmit SAML AuthnRequests or SAML assertions.

The pre-requisite for using the SAML ArtifactResolutionService is that the IdentityProvider- or ServiceProviderState is set up correctly to support artifact binding, which is described in Common aspects of SAML 2.0 AuthStates. This will ensure that the IdentityProviderState or ServiceProviderState files the SAML message with the OutOfContextDataService.

To set up the ArtifactResolutionService endpoint, which accepts requests with SAML artifacts and in turn responds with SAML messages , we need to configure the WebService in the nevisAuth configuration as follows.

<WebService class="ch.nevis.esauth.auth.adapter.saml.ArtifactResolutionService" name="ArtifactResolutionService" uri="/nevisauth/services/artifactresolution" SSODomain="SSO">
   <property name="issuer" value="identity-provider"/>
   <property name="out.keystoreref" value="SAMLKeyStore"/>
   <property name="out.keyobjectref" value="IDPSigner"/>
</WebService>

The WebService does not require any mappings and invokes the SAML Processor, which unmarshalls the provided SAML artifact, retrieves the SAML message from the out of context data service, wraps it around a SAML artifact response and and signs it before marshalling it and sending it back.

WS-Trust 1.4 SecurityTokenService

The WS-Trust 1.4 SecurityTokenService is a WebService that allows to authenticate a user and issue a security token after successful authentication. It is an implementation of the generic WebService facade. Details about how to configure and set up the WS-Trust SecurityTokenService are described in WS-Trust 1.4 SecurityTokenService facade.