Authentication Info

The Tomcat 8 servlet container is configured to force client authentication in order to connect to the server, meaning that every request to the servlet must have a X.509 cert attached. This includes the "login" request to authenticate a user to the server.

Once you have associated a client cert with the requests to the servlet, the client will still be considered as unauthenticated with the application until you submit a login request. Before authenticating, any request to an endpoint other than the login endpoint will return an HTTP-401 error code. To "log in", send a POST request to https://${hostName}:8443/s2dr/login (no request body params are needed. The X.509 cert is used to authenticate). On the servlet, the logging in process is as follows:

• The servlet gets a gets the X.509 cert from the request, and builds a X509Token that contains the cert "subject", and the signature associated with the cert.
• The servlet then attempts to log in by seeing if there is a row in the s2dr.Users table where username corresponds to the subject's common name, and where signature corresponds to the signature.
• If there is a row in the database corresponding to the authenticating client, then that User is used as the session's "current user", and the subject is authenticated.
• If there is not a row corresponding to the authenticating client, then the servlet will automatically add a row for that particular client, and then try to authenticate again (which should be successful this time).
  • This "auto-registration" was done because of my interpretation of the project requirements.
  • The servlet only tries to add the new user and re-authenticate once. If the client is unable to authenticate after adding it as a new user, an HTTP-500 error will be returned. This should never happen...if it does then we've screwed something up.

The client will then have a "session" with the servlet and will be able to make requests until "logging out". To log out make a POST request to https://${hostName}:8443/s2dr/logout. The client will then need to re-authenticate/login before being able to make any other requests.