Mutual Authentication

Introduction

The Mutual Authentication feature allows the FNZ Studio Platform to communicate securely with another server. It enables HTTPS / SSL connections between FNZ Studio as a client and a remote service. For example, a secure connection may be required when retrieving or posting data to a remote server, or consuming a SOAP or REST service.

The connection can be authenticated either by the client (Server Authentication) or by both parties (Client/Mutual Authentication). The object being authenticated – not the authenticator – determines the type of authentication.

Mutual Authentication uses the Key Store, which contains private keys for client/mutual authentication, and the Trust Store, which contains certificates for server authentication.

The following Script Functions are available for Mutual Authentication (see details in section Script Functions):

Note that FNZ Studio also provides a UI module ( System Configuration > Passwords, Keys & Certificates), which allows performing some of these actions. See Secrets Management Framework.

• AddClientKeyAlias() – Adds runtime (not configuration) SSL-Host-to-Key-Alias mappings
• RemoveClientKeyAlias() – Removes runtime (not configuration) SSL-Host-to-Key-Alias mappings
• AddPrivateKey() – Adds a client key to the Key Store
• RemovePrivateKey() – Removes a client key from the Key Store
• AddTrustedCertificate() – Adds a certificate for a service to the Trust Store
• RetrieveTrustedCertificate() – Retrieves a certificate from the Trust Store so that it can be exported
• RemoveTrustedCertificate() – Removes a certificate from the Trust Store
• UseAlias() – Overrides the configuration for a host's standard alias
• RemoveSpecifiedAlias() – Removes an alias currently used to override the standard configuration
• HTTPGET() – Sends an HTTP Get request to the specified URL and supports SSL
• HTTPPOST() – Sends an HTTP Post request to the specified URL and supports adding SSL

The following schema shows an example of server authentication. The client initiates a connection with the server, which then supplies its certificate to the client for authentication. Once the server's authenticity has been verified, the connection is established and HTTP communication can take place over the secured connection:

The following schema shows an example of Client/Mutual Authentication. The client sends a connection request and the server sends back its certificate, but also requests the client's certificate. The client verifies the authenticity of the server certificate and then sends back its own certificate, which the server then verifies. Once each party has verified the validity of the other party's certificate, the secure connection is established and HTTP communication can take place over the secure connection:

Configuration

Server Authentication

If you are using server authentication only, configuration may not be necessary. If the server has a certificate supplied by a reputable certificate authority (CA) known to Java, no specific setting is required.

If the CA is not known, add a certificate for it using the AddTrustedCertificate Script Function or any of the certificates in the chain for the server.

If you have several servers which all have certificates supplied by the same CA, installing the CA certificate automatically builds the trust chain for all of them. It is not necessary to import them all.

In the case of self-signed certificates, it is possible to create a CA certificate used for creating the other self-signed certificates.

Client Authentication

The server authentication configuration described above (server certificates and Trust Store) also applies to client authentication.

For client authentication, it is additionally necessary to:

• Add your private key to the Key Store and give that key an alias.
• Configure FNZ Studio to associate this alias and the host of the service you intend to use:
  1. Go to System Configuration > Configuration Properties and locate the nm.security.ssl.serverAliasMappings property.
  2. Create a list of server-to-alias associations as the value of this property. The host is separated from the alias by a colon and each entry is separated by a semicolon. Example: dev.numcom.local:cerclient;test.numcom.local:certwo

Script Functions

Add Client Key Alias

The AddClientKeyAlias Script Function adds a runtime host-to-alias mapping. This is not saved as a configuration.

AddClientKeyAlias($hostname, $alias)

Example:

String $hostname := 'localhost';
String $alias := 'tester';
AddClientKeyAlias($hostname, $alias);

Add Private Key

The AddPrivateKey Script Function loads and stores a private key in the Key Store.

AddPrivateKey($alias, $keyfilepath, $password)

Example:

String $alias := 'tester';
String $keyfilepath := 'data/keys/mykey.pfx';
String $password := 'password';
AddPrivateKey($alias, $keyfilepath, $password);

Add Trusted Certificate

The AddTrustedCertificate Script Function loads and stores server or Certificate Authority certificates in the Trust Store. See Chapter 4, "Certificate Retrieval" for more information on retrieving certificates.

AddTrustedCertificate($alias, $certificatefilepath)

Example:

String $alias := 'service1';
String $certificatefilepath := 'data/certificates/mycert.cer';
AddTrustedCertificate($alias, $certificatefilepath);

Remove Client Key Alias

The RemoveClientKeyAlias Script Function removes a runtime host-to-alias mapping. This is not saved as a configuration.

RemoveClientKeyAlias($alias)

Return value: (Boolean) 'true' if the operation succeeds, 'false' if it fails .

Example:

String $alias := 'tester';
RemoveClientKeyAlias($alias);

Remove Private Key

The RemovePrivateKey Script Function removes a private key from the Key Store.

RemovePrivateKey($alias)

Return value: (Boolean) 'true' if the operation succeeds, 'false' if it fails .

String $alias := 'tester';

RemovePrivateKey($alias);

Remove SSL Alias

The RemoveSSLAlias Script Function removes an alias that overrides the default alias for a service. It does not take any parameters.

RemoveSSLAlias()

Parameters: None

Remove Trusted Certificate

The RemoveTrustedCertificate Script Function removes a certificate from the Trust Store.

RemoveTrustedCertificate($alias)

Example:

String $alias := 'service1';
RemoveTrustedCertificate($alias);

Retrieve Trusted Certificate

The RetrieveTrustedCertificate Script Function exports a certificate from the Trust Store.

RetrieveTrustedCertificate($alias)

Example:

String $alias := 'service1';
String $fileContent := RetrieveTrustedCertificate($alias);
LocalFile $file := NewObject('LocalFile', 'certs/service1.cer');
$file.writeText($file, 'ISO-8859-1');

Use SSL Alias

The UseSSLAlias Script Function sets an alias that overrides the default alias for a service

UseSSLAlias($alias)

Return value: None

Example:

String $alias := 'anotherAlias';
UseSSLAlias($alias);

HTTP GET

The HTTPGET Script Function sends an HTTP Get request to the specified URL.

HTTPGET($url, $file, $username, $password, $timeout, $proxyHost)

• 1 unknown I/O error
• 2 malformed URL
• 3 unknown host
• 4 socket timeout
• 10 unknown socket error
• 11 connection error
• 12 no route to host
• 13 port unreachable
• 14 SSL client authentication failed
• 15 Security Issue accessing KeyStores

Example:

String $url := 'http://localhost:8080/myservice';
String $file := 'work/file.dat';
String $username := 'username';
String $password := 'password';
Integer $timeout := 120;
String $proxyHost := 'proxy';
Integer $proxyPort := 8008;
String $proxyUser := 'pass';
String $proxyPassword := 'username';
String $certificateAlias := 'password';
Integer $statusCode := HTTPGET($url, $file, $username, $password, $timeout, $proxyHost, $proxyPort, $proxyUser, $proxyPassword, $certificateAlias);

HTTP POST

The HTTPPOST Script Function sends an HTTP Post request to the specified URL.

HTTPPOST($url)

• 200 ok
• 304 not modified
• 401 unauthorized
• 403 forbidden
• 404 not found
• 500 internal server error.

• 1 unknown I/O error
• 2 malformed URL
• 3 unknown host
• 4 socket timeout
• 10 unknown socket error
• 11 connection error
• 12 no route to host
• 13 port unreachable
• 14 SSL client authentication failed
• 15 Security Issue accessing KeyStores

Example:

String $url := 'http://localhost:8080/myservice';
Named Any $data := {}:Any;
String $file := 'work/file.dat';
String $username := 'username';
String $password := 'password';
Integer $timeout := 120;
String $proxyHost := 'proxy';
Integer $proxyPort := 8008;
String $proxyUser := 'pass';
String $proxyPassword := 'username';
String $certificateAlias := 'password';
Integer $statusCode := HTTPPOST($url, $data, $file, $username, $password, $timeout, $proxyHost, $proxyPort, $proxyUser, $proxyPassword, $certificateAlias);

Certificate Retrieval

Before importing a certificate into the Trust Store, you need to retrieve it from the remote server. The procedure is very similar for all browsers; this chapter is based on a Firefox.

1. Enter the URL of the server. If its certificate is not from a known Certificate Authority, your browser displays a warning. Expand "I understand the risks" and click on "Add exceptions…".

   Figure 5: Expanded untrusted connection

2. View the certificate (see the example certificate below).

   Figure 6: Add exception

   

   Figure 7: View certificate

3. After closing the window and confirming the security exception, go to Preferences > Advanced > Certificates > View Certificates. From here, you can either export a CA certificate or a certificate for a specific server. Select a certificate and export it to your local disk.

   Figure 8: Authorities

   

   Figure 9: Servers

4. Save the exported certificate file on a server accessible to FNZ Studio (ask a system administrator). The path to this file can be used as a parameter for the AddTrustedCertificate Script Function.