Skip to main content
Version: 7.2405.x.x LTS

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>
ElementAttributeDescription
WebServiceDefines 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 requiredFully qualified class name of the WebService class.
name requiredThe name of the WebService, for informative purposes.
uri requiredThe URI of the WebService. This URI must start with /nevisauth/services/.
SSODomain requiredThe authentication domain from which incoming requests shall be dispatched.
MappingMappings 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 requiredAn 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 requiredA variable name that will contain the incoming value.
scope optional, default: inargsThe scope of the variable. May be one of {inargs, inctx, sess}.
filter optionalThe filter that should be applied to the from value before being propagated to the to variable.
MethodThe 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 requiredThe method used to process an incoming request. Must be one of {authenticate,stepup,unlock,logout}.
if optionalA variable expression that must evaluate to a value for this method to be selected.
PropertyThe WebService implementation may be configured using property elements. The values of the elements may contain variable expressions.
nameThe name of a configuration property for the WebService implementation.
valueThe 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.