As a web services rookie, authentication is a challenging assignment. First question: whether to use HTTP auth at the transport level, or WS-Security at the message level. Decision: use HTTP auth. It is simpler, mature and widely supported, and meets our current needs well.
Given the four types of HTTP auth:
- HTTP Basic
- HTTP Digest
- HTTPS Client
which should we use?
We're using HTTP/SSL as the transport since sipXconfig data is the customer's private information and should be protected on the wire. So HTTP Digest auth offers no advantages over HTTP Basic. HTTPS Client auth, a.k.a. "client certificate authentication" has the extra security afforded by PKI integration, as well as extra complexity. Form-Based auth is interactive and therefore not suitable for web services.
Decision: start with HTTP Basic and support HTTPS Client later.
Implementing HTTP Basic authentication with Jetty
Jetty, the web container used by sipXconfig, is a great open source product, but the documentation is a bit scanty.
Step 1: Add security-related deployment descriptors to
<web-resource-name>SipXconfig Web Services</web-resource-name>
<!-- Use HTTP Basic authentication. -->
BEA has a good explanation of what goes in web.xml. Briefly,
security-constraintabove protects all the URLs associated with web services, declaring that only clients with the admin role have access.
login-configelement declares that HTTP Basic authentication will be used.
security-roleelement declares the admin security role.
Step 2: Now how do we change the sipXconfig Java code to make the web application support this properly? Turns out that this is completely web container-dependent, sad to say, and the Jetty documentation offers little advice. By talking to my friend Damian, grepping around the Jetty distribution, and looking at the sipXconfig 2.8 code, I figured it out.
Here JettyUserRealm is that class. If you now run sipXconfig in test mode and browse to the web services URL, http://localhost:9999/sipxconfig/services, the browser will prompt you to log in. Of course, this is just for testing, real use of the web services API is from a client application, not a user through a browser. The
JettyUserRealm test class is just a dummy implementation, real authentication via the password tokens stored in the database is the next step in our plan.