ACE authentication design

Communication paths

Before going in more detail on the design and configuration of the authentication layer in ACE, we first need to pinpoint all places were authentication needs to be applied. The following figure shows the main components in ACE and their communication paths, providing a global overview of where authentication is applicable to ACE.

Figure 1: Overview of components and communication paths.

In the above figure, several of the communication paths (denoted by the circled digits) that can be identified in ACE are represented:

1. the client communicates to the ACE server by means of both direct calls to its services as well as remote (HTTP¹) calls;
2. a management agent (representing the target) communicates to the ACE server through remote calls;
3. the REST API exposes the entire client and server APIs in a RESTful way. Communication to the client occurs by both direct and remote calls;
4. the Vaadin Web UI exposes the entire client API as web application. Similar as the REST API, it communicates both directly as remotely with the client.

As can be seen from the above figure, most of the communication paths are remoted. The reason for this is twofold:

1. It allows reuse of components; for example access to the OBR-servlet is used by the both the client-API as well the web UI to upload new artifacts;
2. it enables scalability by allowing components to be deployed on different machines; for example, one does not need to run the client on the same machine as the server. This could be useful for working on high-latency networks.

All direct (i.e., non remoted) communication paths do not need to be authenticated, as they require that both caller and callee run in the same virtual machine, making it impossible to be used outside the virtual machine². Hence, we only need to add an authentication layer to the remote endpoints. However, adding authentication to all remote endpoints poses us with the challenge to let the "internal" communication paths that use remote calls to authenticate themselves as well. Not doing so would prevent ACE from functioning correctly. A disadvantage of this approach is that it is an all-or-nothing approach, either all users of the remote endpoints use authentication, or none of them. However, the way users authenticate themselves can be different, meaning that one set of users can use basic authentication to identify themselves, while another set uses client certificates to identify themselves.

Design

The high-level design for security in ACE is explained in the remote interface design. From this design, we can derive several requirements for the design of ACE's authentication layer:

1. should be applicable and configurable for all remoted endpoints. If a new endpoint is added to ACE, it should be easy to add and configure authentication for it;
2. should be optional. If no authentication is desired, one should be able to remove its services from the ACE distribution;
3. should be pluggable. Various ways of authentication exist, and new ones can emerge. Making the authentication mechanism pluggable allows new ways of authentication to be used easily.

Based on these requirements, the design of the authentication layer is represented in the following figure:

Figure 2: Authentication layer class diagram.

The AuthenticationService is responsible for authenticating a user based on some piece of information. This piece of information can be an array containing a username/password combination, a HttpServletRequest containing authentication request headers, or any other type of information capable of uniquely identifying a user. The actual authentication itself is delegated to one or more AuthenticationProcessors, which know how to handle a given set of information (e.g., HttpServletRequest) and can map this information to a particular user. In more detail, the calling sequence of AuthenticationService#authenticate would be:

1. AuthenticationService#authenticate is called with a blob of data, for example a HttpServletRequest;
2. for each known AuthenticationProcessor:
   • AuthenticationProcessor#canHandle is called with that blob of data. In this method, an authentication processor can decide whether the given blob is something it can handle or not;
   • if it can be handled, the AuthenticationProcessor#authenticate is called with that blob of data, along with an instance of the UserAdmin service. The authentication processor is now responsible for converting the blob of data to an authenticated user, if possible.
3. if a User object is returned from the authentication service³, the authentication phase will be regarded as successful. If no User object is returned, the authentication phase will be regarded unsuccessful.

This is only half the story for authentication. As stated before, ACE internally also communicates through remote endpoints to access certain services. Without any changes, all those remote calls will fail due to missing credentials. If we would leave those means of communications as-is, we need to track down all places where remote calls are being made and inject the proper credentials at each of those places. However, doing this is not only very invasive and error prone but also not very developer friendly from a service-oriented perspective. Alternatively, we could try to include the credentials in the URL itself, making it self-contained. Not only would this approach limit our ability to use any kind of authentication mechanism (it only works for username/password combos), it also required us to supply the credentials manually each and every time we want to create a remote connection. Instead, we would like to refrain from passing around credentials, and leverage the service oriented aspects of OSGi to create remote connections for us. This service could then be responsible for adding the right credentials for us, leaving the calling party totally unaware about the fact authentication might be used (or not). Such a service is denoted in the following figure:

Figure 3: Connection Factory class diagram.

The ConnectionFactory is responsible for creating URLConnections, given a "plain" URL. So, instead of calling URL#openConnection() or URL#openStream(), we'll now have to call ConnectionFactory#createConnection(url) instead. But what advantage does this give us? In order to allow the connection factory to supply the credentials to URLConnections, it is also registered as ManagedServiceFactory that enables us to provide multiple configurations of which credentials should be supplied to what (sets of) URLs. The introduction of the connection factory thus allows us to abstract the creation of a connection and passing of credentials to it from the URL. Internally, the connection factory will match each URL given in createConnection with the URLs it is configured with. If a matching URL is found, it will use the credentials in that configuration to supply to the URLConnection.

Remote services

In the section on the design of the authentication layer, we've mentioned that if a remote service wants to make use of authentication, it can make use of the AuthenticationService. However, one of the design requirements was that authentication should be optional as well. In order to enable or disable authentication, each remote service needs to do the following:

1. add a mandatory configuration property authentication.enabled = false|true to their configuration. Although any kind of name for this configuration property can be used, it is strongly advised to stick to the same name for all services;
2. when the configuration of a remote service is updated, it should add a service dependency to the AuthenticationService. By making this service required if authentication is enabled, and optional when authentication is disabled, we can adhere to the requirement of optionality for authentication;
3. in case authentication is enabled, each request the service obtains needs to be passed to the AuthenticationService first, and depending on its outcome, the request can continue or not.

To make this more concrete, we walk through an example of how the BundleServlet is to be configured. As this is a servlet (as almost all other remote endpoints in ACE), we can intercept all service requests by overriding the Servlet#service() method and perform our authentication check there. If this check is successful, we continue passing the service request, and return a "401 - Unauthorized" when the check is unsuccessful.

We've now closed the circle: we not only have defined how remote endpoints can apply authentication, but also how all calling parties can remain using these remote endpoints without having to be aware of authentication. The only thing left, is a summary of which remote endpoints currently exist in ACE. All remote services are configurable with respect to the endpoint they can be accessed. The following table shows an overview of the remote services, including the default endpoint they use:

More information on configuration authentication can be found in the using HTTP Basic authentication guide, using client certificates guide and user guide.

Implementing the authentication check

If you want to use the AuthenticationService in your own code, you first need to obtain a reference to this service. Using a dependency manager such as Felix DependencyManager makes this trivial:

private volatile AuthenticationService m_authService;

// ...

/**
 * Called by Dependency Manager upon initialization of this component.
 */
protected void init(Component comp) {
    comp.add(m_dm.createServiceDependency()
        .setService(AuthenticationService.class)
        .setRequired(true)
    );
}

To implement the actual authentication in your servlet, we simple intercept all incoming requests in our Servlet and verify whether it is valid (for example, whether we have valid credentials or a valid certificate):

@Override
protected void service(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
    if (!authenticate(req)) {
        // Authentication failed; don't proceed with the original request...
        m_log.log(LogService.LOG_INFO, "Authentication failure!");
        resp.sendError(SC_UNAUTHORIZED);
    } else {
        // Authentication successful, proceed with original request...
        super.service(req, resp);
    }
}

private boolean authenticate(HttpServletRequest request) {
    User user = m_authService.authenticate(request);
    return (user != null);
}

Note that this implementation does not tell how the authentication should occur, only that it must occur. How the authentication is performed, is determined internally by the AuthenticationService, with the help of the registered AuthenticationProcessors. Also note that the authenticate method itself uses the previously defined field (m_useAuth) to determine whether or not the authentication check should be performed. If it is not performed, we consider the request to be always authenticated, in order to obtain the same semantics as we would have without this check.

Troubleshooting

If after configuring the authentication of ACE things no longer work, it can be hard to find the exact cause of this. In this section, some pointers are given to help you to find the probably cause of the problem.

I've enabled authentication, but I can still use all services without passing any credentials!

If you've updated the configuration files of a running server or management agent, the configuration files are not automatically picked up by default. You need to stop the server/management agent, clean its felix-cache folder and start it again.

With authentication enabled, how can I test whether the endpoints accept my credentials?

In order to test the remote endpoints of ACE, you can use a tool like REST client. It allows you to enter credentials for any given URL.

After enabling authentication, I do not get any errors after starting the ACE server, but it doesn't function correctly!

Is the connection factory properly configured? Are all authentication.type options correctly set to basic and are the username/passwords correctly set? Are the configured base URLs not overlapping each other (e.g.: baseURL = http://localhost:8080/ and baseURL = http://localhost:8080/obr)?

After enabling authentication, the management agent(s) no longer functions/I do not see them added in the web UI.

Did you pass the auth=/path/to/config/file(s) option to the management agent to configure the connection factory? Are those files correctly stating the "authentication.type = basic", including the username and password for the desired URLs? Can you access the URLs mentioned in the configuration files with a tool like REST client?

I do not want basic HTTP authentication, I want to use (fill in the kind of authentication)!

Instead, you can also use two-way SSL using client certificates, but you can add your own authentication processor as well.

Notes