When provisioning software (partly) to targets, one has to rely upon the trustworthiness -of both the network and the target. Even if everything is under your control and -governance, one cannot entirely be sure that unwanted access takes place. A first step in -order to prevent unwanted access is authentication, which gives you the ability to -verify the identity of someone. Once the identity is known, one can apply authorization -in order to determine what actions are allowed and which are not. In this article, the -recently added authentication layer of ACE is explained in more depth and how to configure -authentication to your situation.

More details on the design of the authentication mechanism in ACE can be found in the -design documentation.

Table of contents
Introduction
Configuring authentication
- Remote services
- The connection factory
- Troubleshooting

Introduction

When provisioning software (partly) to targets, one has to rely upon the trustworthiness +of both the network and the target. Even if everything is under your control and +governance, one cannot entirely be sure that unwanted access takes place. A first step in +order to prevent unwanted access is authentication, which gives you the ability to +verify the identity of someone. Once the identity is known, one can apply authorization +in order to determine what actions are allowed and which are not. In this article, the +recently added authentication layer of ACE is explained in more depth and how to configure +authentication to your situation.

More details on the design of the authentication mechanism in ACE can be found in the +design documentation.

Configuring authentication

By default, ACE has no form of authentication enabled. While this is sufficient for demonstration purposes, you might want to change this prior to putting ACE into Modified: websites/staging/ace/trunk/content/docs/using-client-certificates.html ============================================================================== --- websites/staging/ace/trunk/content/docs/using-client-certificates.html (original) +++ websites/staging/ace/trunk/content/docs/using-client-certificates.html Tue Nov 25 11:18:13 2014 @@ -101,9 +101,7 @@

Home » Docs

Using client certificate authentication

Using two-way SSL as authentication mechanism in ACE

Revision 1.0, last updated: May 2nd, 2012.

Introduction
Outline

FAQ

References

Notes

Introduction

One-way SSL authentication is used to let a client verify the identity of the server it is communicating with. The server itself does not verify the identity of the client. In two-way SSL authentication, a client first verifies the identity of the server after which the server identifies the client. This way, the identity of both the client and server can be established allowing a trust relation to be created.
-This article describes how to configure the ACE server and the management agent(s) in such way that they use two-way SSL authentication. The remainder of this article assumes the reader has basic knowledge of the principles behind ACE, and has basic knowledge about creating and using certificates.Â For this article, the latest code of ACE (0.8.1-SNAPSHOT, rev.1332609) was used.

One-way SSL authentication is used to let a client verify the identity of the server it is +communicating with. The server itself does not verify the identity of the client. In +two-way SSL authentication, a client first verifies the identity of the server after which +the server identifies the client. This way, the identity of both the client and server can +be established allowing a trust relation to be created.

This article describes how to configure the ACE server and the management agent(s) in such +way that they use two-way SSL authentication. The remainder of this article assumes the +reader has basic knowledge of the principles behind ACE, and has basic knowledge about +creating and using certificates.

Outline

As described in detail in [1], there are multiple communication paths that can (and need) to be secured. For two-way SSL authentication, several scenarios can be identified:

As described in detail in the authentication design +documentation, there are multiple communication +paths that can (and need) to be secured. For two-way SSL authentication, several scenarios +can be identified:

only the communication between management agent and ACE server is secured by means of two-way SSL. This implies that there is only a trust relation between management agent and ACE server, but the other clients that make use of the ACE server have no trust relation (i.e., they still communicate by means of one-way SSL or might not even use SSL at all);
all the communication paths for the ACE server are secured by means of two-way SSL. This means that not only a trust relation exists between management agent and ACE server, but also between, for example, the web-UI and the ACE server or the REST-API and the ACE server¹.
only the communication between management agent and ACE server is secured by means of + two-way SSL. This implies that there is only a trust relation between management agent + and ACE server, but the other clients that make use of the ACE server have no trust + relation (i.e., they still communicate by means of one-way SSL or might not even use + SSL at all);
all the communication paths for the ACE server are secured by means of two-way SSL. + This means that not only a trust relation exists between management agent and ACE + server, but also between, for example, the web-UI and the ACE server or the REST-API + and the ACE server¹.

In conclusion, we need to configure the trust relation between management agent and the ACE server, and, optionally, the trust relation between ACE server and other components.

In conclusion, we need to configure the trust relation between management agent and the +ACE server, and, optionally, the trust relation between ACE server and other components.

Configuring two-way SSL authentication

For two-way SSL authentication, you need two (or more) certificates. These can be issued either by an official external certificate authority (CA), or by means of a self-signed CA².
-The details on how to create a self-signed CA and certificates is well documented on many places on the Internet, and therefore goes beyond this article. Let's assume we've got the following:

For two-way SSL authentication, you need two (or more) certificates. These can be issued +either by an official external certificate authority (CA), or by means of a self-signed +CA².

The details on how to create a self-signed CA and certificates is well documented on many +places on the Internet, and therefore goes beyond this article. Let's assume we've got the +following:

a self-signed CA whose certificate is added to a Java keystore file, called truststore. This file will be used as truststore for both the management agent and the ACE server³;
a certificate (signed by our self-signed CA) for the management agent, available in a Java keystore file, called keystore-ma;
a certificate (signed by our self-signed CA) for the ACE server, available in a Java keystore file, called keystore-server.
a self-signed CA whose certificate is added to a Java keystore file, called + truststore. This file will be used as truststore for both the management + agent and the ACE server³;
a certificate (signed by our self-signed CA) for the management agent, available in a + Java keystore file, called keystore-ma;
a certificate (signed by our self-signed CA) for the ACE server, available in a Java + keystore file, called keystore-server.

For the management agent, we need to add some system properties in order to let Java find and use the correct truststore and keystore (see also [2]):

For the management agent, we need to add some system properties in order to let Java find +and use the correct truststore and keystore (see also the JSSE Reference Guide for JDK +6)⁴:

[localhost:/]$ java \
-  -Djavax.net.ssl.trustStore=/path/to/truststore \
-  -Djavax.net.ssl.trustStorePassword=secret \
-  -Djavax.net.ssl.keyStore=/path/to/keystore-ma \
-  -Djavax.net.ssl.keyStorePassword=secret \
-  -jar org.apache.ace.launcher-0.8.1-SNAPSHOT.jar \
-  discovery=https://10.0.1.16:8443 \
-  identification=MyTarget
+  -Dagent.identification.agentid=MyTarget \
+  -Dagent.discovery.serverurls=https://10.0.1.16:8443 \
+  -Dagent.connection.authtype=CLIENTCERT \
+  -Dagent.connection.sslProtocol=TLS \
+  -Dagent.connection.keyfile=/path/to/keystore \
+  -Dagent.connection.keypass=secret \
+  -Dagent.connection.trustfile=/path/to/truststore \
+  -Dagent.connection.trustpass=secret \
+  -jar target.jar

Note to double check the paths to both files, as there will not be printed any error in case one of them points to an incorrect file!

For the ACE server, the configuration is provided by means of a property-file called platform.properties. Similar to the management agent, we should add some additional properties to it:

Note to double check the paths to both files, as there will not be printed any error in +case one of them points to an incorrect file!

For the ACE server, the configuration is provided by means of a property-file called +platform.properties. Similar to the management agent, we should add some +additional properties to it:

-Dorg.osgi.service.http.port.secure=8443
 -Dorg.apache.felix.https.enable=true
 -Dorg.apache.felix.https.truststore=/path/to/truststore
@@ -158,8 +187,13 @@ The details on how to create a self-sign

This will not only ensure that the Jetty container inside ACE will obtain the correct keystore and truststore and start a listener on port 8443, but also mandates that all clients must provide a certificate upon connecting (as denoted by the last property). Without this, clients that do not offer a certificate will simply be accepted as well, hence resulting in only one-way SSL authentication.

In order to secure all internal communication paths as well, we need to specify some additional properties in platform.properties:

This will not only ensure that the Jetty container inside ACE will obtain the correct +keystore and truststore and start a listener on port 8443, but also mandates that +all clients must provide a certificate upon connecting (as denoted by the last +property). Without this, clients that do not offer a certificate will simply be accepted +as well, hence resulting in only one-way SSL authentication.

In order to secure all internal communication paths as well, we need to specify some +additional properties in platform.properties:

-Djavax.net.ssl.keyStore=/path/to/keystore-server
 -Djavax.net.ssl.keyStorePassword=secret
 -Djavax.net.ssl.trustStore=/path/to/truststore
@@ -167,8 +201,10 @@ The details on how to create a self-sign

This will ensure that all created HTTPS connections will use the mentioned keystore and truststore.
-Note that in order to let all communication to use HTTPS, you need to modify the configuration files of ACE (as found in the conf directory) to mention this, for example, the org.apache.ace.webui.vaadin.cfg file would look like:

This will ensure that all created HTTPS connections will use the mentioned keystore and +truststore. Note that in order to let all communication to use HTTPS, you need to +modify the configuration files of ACE (as found in the conf directory) to mention +this, for example, the org.apache.ace.webui.vaadin.cfg file would look like:

# The endpoint of the Vaadin UI
 org.apache.ace.server.servlet.endpoint = /ace
 # Vaadin UI settings
@@ -182,9 +218,18 @@ Note that in order to let all

-
Alternatively, one could also provide a keystore with a different certificate for securing the internal communication as well. The only thing needed is to change the javax.net.ssl.keyStore property to let it point to another keystore file.
+
Alternatively, one could also provide a keystore with a different certificate for +securing the internal communication as well. The only thing needed is to change the +javax.net.ssl.keyStore property to let it point to another keystore file.

Using multiple different keystores
-
So far, we only used the "standard" Java functionality to secure the communication paths with two-way SSL authentication. While this works for most use cases, one can think of more sophisticated scenario's in which multiple trust relations between different hosts have to be created. For example, when the OBR of ACE runs on a different host, secured with its own certificate. In order to support this use case, we can leverage the authentication framework of ACE by providing it configurations for all URLs that need their own keystore and/or truststore. In our OBR example, we could supply the following configuration to the ConnectionFactory:
+
So far, we only used the "standard" Java functionality to secure the communication paths +with two-way SSL authentication. While this works for most use cases, one can think of +more sophisticated scenario's in which multiple trust relations between different hosts +have to be created. For example, when the OBR of ACE runs on a different host, secured +with its own certificate. In order to support this use case, we can leverage the +authentication framework of ACE by providing it configurations for all URLs that need +their own keystore and/or truststore. In our OBR example, we could supply the following +configuration to the ConnectionFactory:

authentication.baseURL = https://10.0.1.17:8443/obr/ authentication.type = client_cert # optional: use a specific keystore for this URL @@ -196,36 +241,54 @@ Note that in order to let all
-
Different configurations can be supplied for different URLs, allowing many different trust relations to be established.
-
Be sure that in order to let ACE correctly map certificates to users, you need to install the ClientCertAuthenticationProcessor as additional authentication processor!
+
Different configurations can be supplied for different URLs, allowing many different trust +relations to be established.
+
Be sure that in order to let ACE correctly map certificates to users, you need to install +the ClientCertAuthenticationProcessor as additional authentication processor!

FAQ

How should I name the certificates?
-
One should use the hostname of the calling side as common name (CN) of the certificate's distinguished name (DN), for example, CN=localhost or CN=10.0.1.16;
+
One should use the hostname of the calling side as common name (CN) of the certificate's +distinguished name (DN), for example, CN=localhost or CN=10.0.1.16;

How should I name the users that are authenticated through certificates?
-
The user should have the same name as the common name of the certificate, for example, localhost or 10.0.1.16;
+
The user should have the same name as the common name of the certificate, for example, +localhost or 10.0.1.16;

I've enabled two-way SSL authentication, but it doesn't work!
-
There can be many reasons for this, like, can the truststore and keystore files be loaded (no warnings or errors will be printed for this!), or, is the name of the certificate matching the name of the host, or â¦? In general, if it doesn't work, one should enable SSL-debugging in Java by adding -Djavax.net.debug=ssl as system property. This will print lots of information about the keystore and truststore, the communication itself as well as detailed error messages. Also, the authentication parts in ACE provide lots of debugging information, logged at DEBUG level.
+
There can be many reasons for this, like, can the truststore and keystore files be +loaded (no warnings or errors will be printed for this!), or, is the name of the +certificate matching the name of the host, or â¦? In general, if it doesn't work, one +should enable SSL-debugging in Java by adding -Djavax.net.debug=ssl as system +property. This will print lots of information about the keystore and truststore, the +communication itself as well as detailed error messages. Also, the authentication parts in +ACE provide lots of debugging information, logged at DEBUG level.

What if my target runs on a machine with a dynamic IP address? Can I still use client certificates for authentication?
-
Not directly. Java uses the common name of the certificate and assumes this to be a valid, resolvable, hostname. If not, it will fail to accept the certificate as being valid. In the near future, ACE should support this functionality.
+
Not directly. Java uses the common name of the certificate and assumes this to be a +valid, resolvable, hostname. If not, it will fail to accept the certificate as being +valid. In the near future, ACE should support this +functionality.

-
References
-
-
Developer documentation on ACE Authentication;
-
JSSE Reference Guide for JDK 5.0;
-
-
Notes

-
One can argue whether this is strictly necessary for all internal communication paths, as we will see later on, one can configure which paths use two-way SSL authentication and which paths do not. ↩
+
One can argue whether this is strictly necessary for all internal communication +paths, as we will see later on, one can configure which paths use two-way SSL +authentication and which paths do not. ↩

-
Using a self-signed CA for two-way SSL authentication is not that much of a problem as one needs to make the certificate of the client available to the server, and the other way around. When both certificates are signed by the same CA, and both sides also trust this self-signed CA, the trust relation between client and server can be established as well. ↩
+
Using a self-signed CA for two-way SSL authentication is not that much of a problem +as one needs to make the certificate of the client available to the server, and the other +way around. When both certificates are signed by the same CA, and both sides also trust +this self-signed CA, the trust relation between client and server can be established as +well. ↩

-
Based on the certificate in the truststore, each side will be able to validate the certificate of the other side. ↩
+
Based on the certificate in the truststore, each side will be able to validate the +certificate of the other side. ↩
+
+
+
You probably do not want to specify the credentials using the commandline, see also +ACE-496. ↩

ACE Authentication

ACE authentication guide

Table of contents

Introduction

Configuring authentication

Using client certificate authentication

Introduction

Outline

Configuring two-way SSL authentication

Using multiple different keystores

FAQ

References

Notes