Introduction to Security

Overview

Net4Care is securely accessed via HTTPS requests. Each request must be authenticated using HTTP Basic Authentication (i.e., with a username and a password). Furthermore, Net4Care has a simple role model that include the roles of

  • Users (healthcare professionals and patients)
  • System administrators

Each servlet in Net4Care is configured to be accessible only by allowed roles.

Note that in the default configuration, HTTP without security is enabled. To disable HTTP, set

 <org.apache.felix.http.enable>

to false in n4c_receiver/pom.xml.

The user manager

The Net4Care security module implements a user manager. For each HTTPS request, a Net4Care user manager service checks authentication and authorization for users. This user manager is part of the servlet's context.

Users and roles

A user is defined by the following attributes:

  • Username. The name the user has in the system, necessary for sending secure requests.
  • User ID. The user's identifier in the system. This may be a CPR number.
  • Password. The password chosen by the user, necessary for sending secure requests.
  • Role. The role of the user

For more information about the users and what they are allowed to do, please check Table 6.2 in the architectural description.

Authentication

To determine whether a request is executed or not, it has to undergo two steps: authentication and authorization. The request will be executed if both steps are successful.

The authentication is carried out using HTTP basic authentication. The request contains the user's credentials, and these are processed in the servlet's context by the user manager. The username and password are queried to the user database, and if they match, the authentication is successful. The "UserManager" interface defines this method for performing user authentication:

  public boolean isAuthenticated(String username, String password);

Authorization

The authorization step checks whether the user has the rights to execute the request; that is, the user's role matches the access role defined in the servlet's context. For example, a servlet containing the following line in its activate method

  http.registerServlet(path, this, null, new BasicAuthHttpContext(new StandardUserManager(), Roles.ADMIN_ROLE));

will only allow administrator users to perform the operations defined in the servlet for HTTPS connections.

The UserManager interface defines this method for checking authorization of users:

  public boolean isAuthorized(String username, int neededRole);

The parameter neededRole corresponds to the role specified when registering the servlet. These two roles must have the same privileges for the request to be authorized.

The user database

All Net4Care users are stored in an SQLite database located in (root)/n4c_osgi/n4c_receiver/resources/auth.db. Feel free to open it with any SQLite client to see its contents.

When a servlet is created, a user manager is also created as a part of its context. The first time the user manager is instantiated, it checks whether a connection to the user database can be established, and if not, assumes there exists no database and creates it. This check is done every time a servlet is launched, meaning that if the connection to the database fails for any reason, it will be re-created.

This database contains one table, called users. The structure of this table, and the type of its columns is described below:

  • username varchar(50). Represents the name the user has in the system.
  • userid varchar(50). Represents the user's identifier in the system.
  • role integer. Represents the role of the user in the system. The different roles can be found in the class Roles in the security package.
  • hash BLOB. Represents the hash of the password concatenated with a salt (see below)
  • salt BLOB. The salt used for encrypting the user's password. It is used to protect the passwords against attacks using rainbow tables.

Adding support for secure requests to servlets

In general, servlets are configured to with a user manager when they are registered to OSGi:

 http.registerServlet(path, this, null, 
        new BasicAuthHttpContext(new StandardUserManager(), Roles.ADMIN_ROLE));

Servlets can also be configured to receive secure and non-secure requests. This can be done for each request method individually. In their definitions, all request methods receive an HttpServletRequest object representing the request from the client, as in the example below:

  doGet(HttpServletRequest req, HttpServletResponse resp)

If, for instance, we wanted a particular servlet to accept both HTTP and HTTPS GET requests, we would simply process the request directly:

  @Override
  protected void doGet(HttpServletRequest req, HttpServletResponse resp)
    throws ServletException, IOException {
    // Process request
    // ...
  }

However, if we wanted our servlet to accept secure GET requests only, then we need to rule out HTTP requests:

  @Override
  protected void doGet(HttpServletRequest req, HttpServletResponse resp)
    throws ServletException, IOException {
    if (req.isSecure()) {
      // Process the request
      // ...
    } else {
      // Do nothing. This servlet accepts secure GET requests only!!!
    }
  }

User management operations

In addition to authentication and authorization, the user manager allows two other operations defined in its interface:

  public int updateUser(User user);
  public int deleteUser(User user);

These two operations are performed on the user management servlet (/usermanagement) through HTTPS requests, and allows only system administrators to create, update, or delete users from the user database.

Below you can find examples for user management operations. We will be using curl for sending requests to the servlet. You can find a tutorial and information about the command here

Create and update users

The updateUser method allows both to create (if the user does not exist) and to update a user in the user database.

This operation is done via a POST request:

  curl -k -X POST https://localhost:8443/usermanagement/ -u net4care:N3t4C@re
    -d '{"username":"testuser3","userid":"11","role":1,"password":"pass"}'

Here, the request is sent to "https://localhost:8443/usermanagement/" (note the protocol is HTTPS and the port is 8443). The request contains the user's credentials, where net4care is the username and N3t4C@re is the password; this username is the default administrator user that is created when the user database is created for the first time. Finally, the payload is the JSON representation of a user:

  '{"username":"testuser",
    "userid":"11",
    "role":1,
    "password":"pass"}'

The user's username is testuser, its ID is 1, its role is 1 (a normal user; an Administrator would be 2, cf., the Roles lass), and its password is pass. If everything went well, the server should return something like

  {"operationStatus":10}

where the status code 10 means "create user successful". The status codes can be checked in the class Constants located in the security bundle.

Next, we will try to add a new user authenticating as the user, testuser, we have created above:

  curl -k -X POST https://localhost:8443/usermanagement/ -u testuser:pass
    -d '{"username":"testuser2","userid":"22","role":1,"password":"pass2"}'

As mentioned earlier, the user management servlet only allows system administrators to perform user management operations, so the system will reject the request, and the output should be something like:

  <html>
  <head>
  <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/>
  <title>Error 403 FORBIDDEN</title>
  </head>
  <body><h2>HTTP ERROR 403</h2>
  <p>Problem accessing /usermanagement/. Reason:
  <pre>    FORBIDDEN</pre></p><hr /><i><small>Powered by Jetty://</small></i><br/>

Now, let us change the role of the user we have added, from 1 (user) to 2 (admin):

  curl -k -X POST https://localhost:8443/usermanagement/ -u net4care:N3t4C@re
    -d '{"username":"testuser","userid":"11","role":2,"password":"pass"}'

If everything went fine, you should see something like

  {"operationStatus":20}

where the status code 20 means "update user successful". Now we can crete, update, and delete users with this recently created user.

Delete users

The payload does not have to be a complete representation of a user with all its fields as in the case of creating/updating a user. It is sufficient with writing the username:

  curl -k -X DELETE https://localhost:8443/usermanagement/ -u net4care:N3t4C@re
    -d '{"username":"testuser"}'

If everything went fine, you will see

  {"operationStatus":30}

where the status code 30 means "delete user successful".

Feel free to send different requests to the user management servlet, using different roles, and trying to perform different operations to gain fluency in user management operations.

Summary

  • The security module acts every time a servlet receives an HTTPS request.
  • Allowing only HTTPS requests or HTTP requests can be done individually for each request method for each servlet.
  • A request will be allowed if the user who sent is authenticated and authorized.
  • Users are stored in the user database, which can be found in (root)/n4c_osgi/n4c_receiver/.
  • User management requests will only be processed if the user who executes them has administrator rights.
  • To create/update users, the payload must contain a full representation of a user.
  • To delete users is enough to specify the username in the message.