REST service API

As of version 4.15.0.0, nevisAuth supports the configuration of REST web services. REST, which is the acronym for Representational State Transfer, is an architectural style that is usually implemented on top of the HTTP protocol. To be RESTful, there are some requirements that need to be fulfilled:

• Every resource or web service must be identified and addressable through a URI.
• There should be no client context stored on the server. Each request must contain all the information that is needed for processing.
• To be able to create, retrieve, update or delete resources, a defined set of operations must be used. When using HTTP, those are PUT, GET, POST and DELETE.
• The resource should be decoupled from the presentation. A REST web service can present the same resource in different formats, for example in JSON or XML.

In nevisAuth, a REST web service differs from the SOAP or RADIUS facades described in SOAP web services in that it does not wrap the AuthStates in a new interface. Instead, it is a new framework to develop services that can be used by clients to make use of application-specific nevisAuth functionality, besides user authentication.

An example for such a service is the TAN service, parts of which are depicted below:

@Path("/tan")
public class TANService {
 @XmlRootElement(name = "tan-result")
 public static class Response {
 public String status;
 public String challenge;
 }

 public TANService(@Context ResourceContext resourceCtx)
 throws BadConfigurationException {
 this.resourceCtx =resourceCtx;
 Properties cfg = resourceCtx.getConfiguration();
 ...
 }

 @GET @Path("/generate")
 @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
 public Response generateChallenge(@QueryParam("sender") String sender,
 @QueryParam("recipient") String recipient,
 @QueryParam("message") String message,
 @QueryParam("lang") String lang
 ) throws WebApplicationException
 {
 ...
 }

 @POST @Path("/generate")
 @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
 public Response generateChallengePost(@FormParam("sender") String sender,
 @FormParam("recipient") String recipient,
 @FormParam("message") String message,
 @FormParam("lang") String lang
 ) throws WebApplicationException
 {
 ...
 }
}

The default path of the TAN service is /tan, under which two operations can be accessed:

GET /tan/generate, and
POST /tan/generate.

The operations do exactly the same, except for accepting different request methods. They both receive four parameters: sender, recipient, message and lang. The response is based on the request, either in XML or JSON format.

A REST service may also receive configuration properties. An example on how the service can be configured in the esauth4.xml file is this:

<RESTService name="tanService" class="ch.nevis.esauth.rest.service.TANService" path=" /tan">
 <property name="rolesAllowed" value="nevisAuth.tanUser"/>
 <property name="channel" value="HTTP"/>
 <property name="httpUrl" value="http://www.smsbooster.com/send.asp"/>
 <property name="httpHeader.Referer" value="https://intranet.nevis.com/sms_service/index.htm"/>
 <property name="httpSuccessStatus" value="200-399" />
 <property name="httpParam.SMSTelefon" value="${notes:tan.http.receivers}"/>
 <property name="httpParam.smsMessage" value="${notes:tan.http.message}"/>
 <property name="httpParam.USERID" value="<yourID>" />
 <property name="httpProxyHost" value="proxy.nevis.com"/>
 <property name="httpProxyPort" value="3128"/>
</RESTService>

The XML element RESTService is a child of the root XML element esauth-server. Place the RESTService XML element as the last child of the esauth-server element.

The configuration of the path allows the same service class to be instantiated with different configuration properties on different paths. The configuration properties can be used in the constructor of the service, by extracting them from the injected ResourceContext like this:

public TANService(@Context ResourceContext resourceCtx) throws BadConfigurationException
{
 this.resourceCtx =resourceCtx;
 Properties cfg = resourceCtx.getConfiguration();
}