Web Services: A Security Primer

This document is intended for anyone that needs to develop a client to access Clearspace 2.5.x web services.

It's for those who are:

• Unfamilar with WS-Security (Web Services Security protocol maintained by the OASIS-Open organization).
  
• Unfamiliar with Web Services Security (WSSE) Username Token Profile authentication and has:
• • Disallowed anonymous access to web services in their Clearspace instance.
  • Allowed anonymous access, but needs to access web service methods that cannot function without an authenticated account (including many write operations).

Also see:

• SOAP Services Dev Guide
• REST Web Services Reference

Web Services Authentication in Clearspace

Clearspace uses the Username Token Profile authentication specification with the PasswordText option to authenticate web service client requests into the server, as mentioned in the web services dev guide.

WS-Security

For the uninitiated WS-Security can be a complex maze of vague specifications and protocols. The following provide introductions to WS-Security:

• http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss
• http://en.wikipedia.org/wiki/WS-Security

WSSE Username Token Profile Specification

The purpose of the Username Token Profile specification is to authenticate requests for HTTP resources by verifying that the client making the request is who they say they are and is authorized to make a particular request. It was initially designed for SOAP, but can be extended for any type of HTTP service.

For example, it is used by many Atom and RESTful services where simpler authentication schemes aren't enough. Examples of these simpler authentication schemes include: HTTP basic authentication, HTTP basic authentication over SSL, HTTP Digest authentication, and hash-based authentication schemes.

How it works
A security header is sent with every client SOAP request to the service (or HTTP request to services that aren't SOAP). The header contains the username and some representation of a password. The header that is sent is an extension of the HTTP Authentication specification (IETF RFC 2617 is extensible beyond basic and digest authentication).

Username Token Profile Specification - PasswordText Option

How the PasswordText option works:

• The client sets a header in every request that contains a username and password.
• The password is sent in the header in plain text.

To be secure all HTTP requests and responses should be SSL encrypted.

Username Token Profile Specification - PasswordDigest Option (Unsupported)

PasswordDigest is a more secure authentication option provided by the Username Token Profile specification.

PasswordDigest isn't supported by Clearspace by default, but with some code it's possible to customize Clearspace to support it. Since Clearspace web services are developed using the Spring framework and Apache CXF integration, and since Apache CXF uses the WSS4J implementation of WS-Security, it is possible to customize Clearspace to support PasswordDigest. This would involve overriding or replacing the WSS4J interceptor in the Apache CXF Spring configuration used by Clearspace. See the Apache CXF project's WS-Security documentation for more information: http://cwiki.apache.org/CXF20DOC/ws-security.html.

How PasswordDigest works:

• A client begins with the two pieces of information: the username and password.
• The client creates a nonce, which is a cryptographically random string.
• The client creates a creation timestamp with the current time.
• The Password Digest is created by creating an SHA1 hash of the combination of the nonce, timestamp, and password with the result BASE 64 encoded.
• • PasswordDigest = Base64 \ (SHA1 (nonce + creation timestamp + password) - plagiarized from: http://www.xml.com/pub/a/2003/12/17/dive.html.
• The combination of the nonce and timestamp would prevent the header from being reused.
• The client sets a header in every request containing the username and digest.

For maximum security, all HTTP requests and responses should be SSL encrypted.

Unsupported WS-Security Authentication Specifications

In addition to the Username Token Profile Specification, WS-Security currently includes three other specifications that Clearspace doesn't support:

• • X.509 Token Profile (pdf doc)

  • SAML Token Profile (pdf doc)

  • Kerberos Token Profile (pdf doc)

The underlying use of the WSS4J library by Apache CXF does make it possible to implement support for the two additional specifications that WSS4J supports:

• • WSS4J supports the X.509 Token Profile specification and has partial support for the SAML Token Profile specification.

  • The Apache CXF WS-Security documentation discusses implementing X.509 Token Profile using the Apache CXF library