Server SDK (HTTP Module)

Foundations

The HTTP module implements the IHTTPModule that authenticated the request. If the request cannot be authenticated, the HTTP module intercepts the response and sends an unauthorised status code.

Allowed Authentication Methods

In order to be able operating the server only with the SAPIA authentication, all authentication methods except Anonymous Authentication must be disabled for the web site or web application.

Register the Module

The AuthenticationModule must be registered in the Web.Config, but there is a difference in the implementation details between the IIS versions and the Classic vs. Integrated pipeline application pool methods. Therefore, the example in the project runs on a .NET 4.0 application pool with Integrated pipeline mode settings. Make sure the module is registered correctly by running the application and making sure that the response from the server comes with code 401 (Unauthorised). The steps to register the module are:

1. Compile the SAPIA project.
2. Add to your web application's bin folder the SAPIA Server SDK.dll, IDataAccessObject.dll, DataAccessObject.dll and app.config files.
3. Add a reference to the SAPIA Server SDK.dll file.
4. Edit your Web.Config file to include the sections system.webServer and identity as described here.

Implementation Requirements

As mentioned before, the persistence layer is decoupled from the project implementation, and therefore, any persistence layer can be used with the SAPIA project. The SAPIA project comes with a mocked up database that implements the IDataAccessObject interface. The interface includes 2 methods enabling the SecretKey retrieval and the keys persistence.

string GetSecretKey(string sharedKey)

This method retrieves the secret key of the identity based on the shared key string.

bool StoreKeyPair(string secretKey, string sharedKey, object additionalIdentityData)

The method persists the key pair (secret and shared keys) for a given identity. The additionalIdentityData object can be anything that fits into the identity management process your application has in place. If the key pair succesfully persisted, the method returns true.

Important: In order to make it production ready, replace the DataAccessObject.dll file with your own implementation of the IDataAccessObject interface. use the example from here.

The SAPIA project comes with HMAC-256 authentication out of the box. If the algorithm is not satisfying the performance or other technical needs, there are two options to implement IMessageAuthenticationVerifyer - change to another HMAC factory in the provided HMACAuthenticator Class, or implement symmetric encryption class, where the secret key is the encryption key of the message. The implementation of the IMessageAuthenticationVerifyer consists of 1 method as follows.

SuccessfulResponse AuthenticateMessage(AuthenticationData authenticationData)

This method authenticates the message and returns any relevant data according to the business logic of the application, e.g. full identity, roles, claims etc. Tweak the SuccessfulResponse class as you need, while keeping in mind that it is going to be cached in the memory for future responses.