Using Folder Access Permissions

SOAPam Server allows permissions to be set on folders which protect their contents from unauthorized access. In order to access a SOAPam Web service, the caller must have "Execute" permission for the folder that contains the Service Definition File (.sdf) for the service. See Folder Permissions Management in the Administrator's Guide for information about folder permissions.

If the folder which contains the .sdf for your service does not specify (explicitly or inherited) Execute permission for the "Anonymous" user (or a group that contains that user), clients accessing the Web service will require authentication by the SOAPam Server. Authentication is the process through which the server verifies the identity of its client. During authentication, the client must supply an encoded user name and password in the HTTP message's header. Note, user names are not case sensitive; passwords are case sensitive. SOAPam Server supports two standards for user authentication: Basic Authentication and Digest Authentication.

HTTP authentication semantics dictate that, for a given session, clients first attempt to access resources anonymously (without an authentication header). If the anonymous access to the resource is not permitted, the server returns a status code 401 ("unauthorized") and information about the type of authentication it supports. This is a signal for the client to create an authentication header containing the user's name and password and to attempt to access the resource again.

These semantics imply that anonymous access must fail in order to for authentication to occur. Therefore, you must disable Execute permission for the Anonymous user on the folder the contains your .sdf if you want to require that the user be authenticated.

Fortunately, HTTP authentication is usually supported by the client library or tool kit and not a concern for the SOAP client application developer. The specifics of the HTTP protocol are beyond the scope of this document.

Basic Authentication

Basic Authentication is the simpler but less secure method. It merely requires that user's credentials be base-64 encoded. This encoding is easily reversible, so someone electronically eavesdropping on your TCP/IP session could discover your password. Therefore, it's recommended that Basic Authentication be used in conjunction with HTTPS, which provides additional security by using strong encryption over the entire session.

It is possible to authenticate "preemptively" using Basic Authentication, sending the authentication header with the foreknowledge that authentication is required. This eliminates a round-trip to the server since the "401" status and subsequent retry is not required. This technique does not work with Digest Authentication, however, since it is dependent on information returned in the 401 status response in order to be able to encode the user credentials.

Basic Authentication may be disabled by the SOAPam Administrator through the Control Panel, forcing client applications to use Digest Authentication.

Digest Authentication

In Digest Authentication, the user's credentials are more strongly encrypted than Basic authentication. Consider using digest authentication if your client library or tool kit supports it. However, since the encryption and decryption of the user credentials is complex, there may be a slight performance penalty.

Some client applications that only support Basic authentication can be confused by the presence of a Digest Authentication header in a 401 status HTTP response. Digest Authentication may be disabled by the SOAPam Server Administrator through the Control Panel, allowing these applications to function.