Configuring Mutual Authentication Between Your MicroStrategy Identity PACS Adapter Machine and MicroStrategy Identity Server

You can make the connection more secure between the MicroStrategy Identity adapter for your physical access control system (PACS) and MicroStrategy Identity Server by implementing mutual, or two-way, authentication.

For example, in one-way authentication, the machine hosting the MicroStrategy Identity PACS Adapter presents a certificate to MicroStrategy Identity Server. If you configure mutual authentication, the PACS adapter machine presents a certificate to MicroStrategy Identity Server, and MicroStrategy Identity Server presents a certificate to the PACS adapter machine, allowing both the PACS adapter and MicroStrategy Identity Server machines to verify each other's identity.

Implementing mutual authentication between the MicroStrategy Identity PACS Adapter and MicroStrategy Identity Server consists of these high-level steps:

1. Creating the Certificates to be Used for Mutual Authentication
2. Configuring the PACS Adapter Machine and Test that it Works Without Mutual Authentication Enabled
3. Configuring the PACS Adapter Machine to Require a Client Certificate
4. Installing the Client Certificate in a Web Browser
5. Installing and Enabling Certificate Files on MicroStrategy Identity Server
6. Configuring MicroStrategy Identity Server to Use the Client Certificate

The steps below contain the information required to configure or use third-party applications with MicroStrategy Identity. The information provided is subject to change. See the appropriate third-party documentation for the latest information.

Creating the Certificates to be Used for Mutual Authentication

To generate the certificates that are used in mutual authentication, you can use a certificate generated by any certificate authority or use a self-signed certificate that you generate with an application for creating and managing security certificates, such as OpenSSL. For your final Identity installation, using a server certificate generated by a certificate authority is recommended. A self-signed certificate can be useful for testing the mutual authentication setup.

To use a certificate authority to generate the certificates, create a certificate signing request and send the certificate signing request to the certificate authority.

To create a self-signed root certificate and a client certificate that is signed by the root certificate, see the following:

• Creating a Root Certificate
• Generating a Server Certificate
• Generating a Client Certificate from the Server Certificate

Creating a Root Certificate

Create a root certificate key and certificate.

1. In OpenSSL, use a command such as the following:
   openssl req -new -x509 -extensions v3_ca -keyout rootcert.key -out rootcert.crt -days 1825
   This outputs rootcert.key and rootcert.crt files in the current directory.
2. Copy the openssl.cfg file from the OpenSSL installation directory to the current directory, and rename the copy openssl.my.cfg.
3. Edit the openssl.my.cfgconfiguration file using a text editor such as Notepad. Look for the CA_default section and change the following settings as follows:
   dir = .
certificate = rootcert.crt
private_key = rootcert.key
   This is a valid root certificate that you can use to sign the other certificates.

Generating a Server Certificate

Generate a server certificate that is signed with the root certificate.

1. In OpenSSL, use a command such as the following:
   openssl req -config openssl.my.cfg -new -nodes -keyout myCert.key -out myCert.csr -days 365
   When answering the prompts, it is recommended that you make the server name the distinguished name of the certificate. The command above generates a key called myCert.key and a certificate signing request called myCert.csr.
2. Sign the certificate signing request. In OpenSSL, use a command such as the following:
   openssl ca -config openssl.my.cfg -policy policy_example -out myCert.crt -infiles myCert.csr
   This outputs a .crt file from the certificate signing request, using the certificate authority certificate to sign it.
3. Create a file, in Public-Key Cryptography Standards #12 (PKCS12) format, that contains both the certificate and the private key. In OpenSSL, use a command such as the following:
   openssl pkcs12 -export -out myCert.pfx -inkey myCert.key -in myCert.crt -certfile rootcert.crt
   This creates a file in PKCS12 format that you can use when installing certificates on the web server and browser and in configuring the PACS adapter in the Identity Server.

Generating a Client Certificate from the Server Certificate

Use the server certificate to sign the client certificate.

1. Make a copy of the openssl.my.cfg you created.
2. Modify the file, using a text editor such as Notepad, to point to the myCert.crt and myCert.key instead of the root certificate.
3. Follow the same steps as in Generating a Server Certificate, but use the second copy of the configuration file in the -config switch and give all the files a different name.

You can use this certificate in a browser to access a web server with the server certificate in the trust store.

Next, configure the PACS adapter machine and test that you can access the PACS adapter machine with HTTPS enabled.

Configuring the PACS Adapter Machine and Test that it Works Without Mutual Authentication Enabled

Configure the server that is hosting the PACS adapter to work with standard, one-way authentication (HTTPS). Brief instructions are below for Tomcat and Microsoft Internet Information Services (IIS).

• In Tomcat, modify the server.xml file so the clientAuth setting is false and no trust store information is in the file. For steps to do this, see your third-party documentation.
• In Microsoft IIS, turn off the secure sockets layer (SSL) binding requirement:
  1. In IIS Manager, locate the server site where the HTTPS binding will eventually be assigned. The adapter application is in this site. A common location is the Default Web Site, but your configuration may be different.
  2. Right-click the site and select Edit Bindings.
  3. Click Add. From the Type drop-down list, select HTTPS.
  4. Open the site settings and double-click SSL Settings.
  5. Select the Require SSL check box.
  6. Select Ignore.
  7. Click Apply.

Next, change the PACS adapter machine to require the client to have a certificate.

Configuring the PACS Adapter Machine to Require a Client Certificate

Configure the machine hosting the PACS adapter to require a client certificate that will be used to access it.

1. Enable client certificate support. Instructions are below for both Tomcat and Microsoft IIS.
   • In Tomcat: Using a text editor, modify the server.xml file so the clientAuth setting is true, the trust store information in the file points to the PKCS12 file for the certificate that signed the client certificate, and the trust store password is included. The certificate to which the trust store points may be the server certificate or another certificate. For steps to change this file, see your third-party documentation.
   • In IIS:
     1. Open IIS Manager, select the website (typically Default Web Site), and choose SSL Settings.
     2. Select the Require SSL check box, then click Require.
     3. Click Apply.
2. Restart the web server on the PACS adapter machine.
3. Confirm that you are denied access to the PACS adapter when you connect via a web browser without a certificate. Use the diagnose URL for your PACS adapter, as described in the The PACS adapter is configured to work with MicroStrategy Identity, and a user can open a door using MicroStrategy Badge. For steps, see Enabling access to physical locations with MicroStrategy Badge..

Next, install the client certificate in a web browser to test whether the setup works.

Installing the Client Certificate in a Web Browser

Install the client certificate in your web browser on any machine and confirm that the call to diagnose succeeds with the certificate installed. This is the same certificate you will install on MicroStrategy Identity Server, but before trying it on MicroStrategy Identity Server, you are installing it in a web browser to confirm that it works. Steps to install the certificate in the Google Chrome browser are below as an example. For steps to install the certificate in your browser, see your browser's third-party documentation.

To install the client certificate in Chrome:

1. Open Settings.
2. Click Show advanced settings.
3. Under HTTPS/SSL, click Manage certificates.
4. Click Import.
5. Import the certificate you created earlier in Generating a Client Certificate from the Server Certificate.

After the certificate is installed in the browser, ensure that you can connect to the PACS adapter. From your browser, use the diagnose URL for your PACS adapter, as described in the The PACS adapter is configured to work with MicroStrategy Identity, and a user can open a door using MicroStrategy Badge. For steps, see Enabling access to physical locations with MicroStrategy Badge..

Next, install and enable the certificates on MicroStrategy Identity Server.

Installing and Enabling Certificate Files on MicroStrategy Identity Server

Add the certificate and related files to the Identity Server file system: the certificate file itself (in .p12 format) and a password file for the certificate (in .txt format). These are the files you created in Creating the Certificates to be Used for Mutual Authentication. Note the paths where you added the certificate files; you will use the path information in the next task. Depending on the type of server hosting the PACS adapter, follow the steps below to enable client certificate support:

• Enabling Client Certificate Support in Apache Tomcat
• Enabling Client Certificate Support in Microsoft IIS

For MicroStrategy Cloud implementations, if you do not have access to MicroStrategy Identity Server, contact MicroStrategy at support@microstrategy.com. Inform the support personnel that you are implementing mutual authentication between your PACS adapter and MicroStrategy Identity Server and that you need to have them install and enable certificate files on MicroStrategy Identity Server.

Enabling Client Certificate Support in Apache Tomcat

To enable client certificates in Tomcat:

1. Using a text editor, modify the server.xml file. In the file, add a connector for SSL access and configure it for client certificate support. Look at the connector for a regular, non-client certificate SSL. An example is shown below.
   <Connector port="443" protocol="org.apache.coyote.http11.Http11Protocol"maxThreads="150" SSLEnabled="true" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" keystoreType="pkcs12" keystoreFile="c:/pki/myCert.p12" keystorePass="password" />
   This specifies the PKCS12 file you created earlier as the server certificate used for SSL. The path to that file and the password for the PKCS12 file are given as arguments to the connector. With this configuration, you can connect to port 443 with HTTPS and access the PACS adapter.
2. Enable client certificates. Change the connector to something similar to the following:

   <Connector port="443" protocol="org.apache.coyote.http11.Http11Protocol"maxThreads="150" SSLEnabled="true" scheme="https" secure="true"clientAuth="true" sslProtocol="TLS" keystoreType="pkcs12" keystoreFile="c:/pki/myCert.p12" keystorePass="password" truststoreType="pkcs12" truststoreFile="c:/pki/myCert.p12"truststorePass="password" SSLVerifyClient="require" SSLVerifyDepth="4" />
   This specifies that the trust store is the PKCS12 file you created. The client certificate must be signed by this certificate to be able to access the web server.

Enabling Client Certificate Support in Microsoft IIS

To enable client certificates in Microsoft IIS:

1. Import the certificate into IIS:
   1. Open the IIS Manager.
   2. Double-click Server Certificates.
   3. Click Import and select the .p12 server certificate you created in Creating the Certificates to be Used for Mutual Authentication.
2. Enable SSL on IIS:
   1. In IIS Manager, locate the server site where the HTTPS binding will be assigned. This is the site hosting the adapter application. A common location is the Default Web Site, but your configuration may be different.
   2. Right-click the server and select Edit Bindings.
   3. Click Add and from the Type drop-down list, select HTTPS. In the dialog box, select the imported certificate. Ensure the port and host name are correct.
   4. Test the adapter manually with a web browser.
   5. After making the above changes, you should be able to connect with a browser to IIS using HTTPS. Use the resource/diagnose call to confirm that the connection works. Use the diagnose URL for your PACS adapter, as described in the The PACS adapter is configured to work with MicroStrategy Identity, and a user can open a door using MicroStrategy Badge. For steps, see Enabling access to physical locations with MicroStrategy Badge..
3. Enable Client Certificate Support:
   1. Open IIS Manager, select the adapter web application (typically Default Web Site), then choose SSL Settings.
   2. Select the Require SSL check box and click Require.
   3. Click Apply.
   4. Confirm that you cannot connect to the web application from the browser via HTTPS because the certificate is not installed.
   5. Install the client certificate in the browser.
   6. Confirm that you can connect to the server via HTTPS. To do this, use the diagnose URL for your PACS adapter as described in the The PACS adapter is configured to work with MicroStrategy Identity, and a user can open a door using MicroStrategy Badge. For steps, see Enabling access to physical locations with MicroStrategy Badge..

Next, configure MicroStrategy Identity Server to use the client certificate.

Configuring MicroStrategy Identity Server to Use the Client Certificate

Update the org_adapter_config table in the MicroStrategy Identity Server database to add the location of the certificate file and the password file into the JSON for the opt_properties of the adapter. If you do not have access to this, contact MicroStrategy at support@microstrategy.com. Inform the support personnel that you are implementing mutual authentication between your PACS adapter and MicroStrategy Identity Server and you need to configure MicroStrategy Identity Server to use the client certificate.

1. In the MicroStrategy Identity Server database, in the org_adapter_config table, locate the row for your PACS adapter.
2. Find the opt_properties field for your PACS adapter. It looks like the following example:
   {"bypass_ssl":"true","timeout":"7000"}

3. Update the field to add attributes and values for the certificate file path, client_certificate_file, and the password file path, client_certificate_password_file. An example of the updated opt_properties field is below:
   {"client_certificate_password_file":"/mstr/config/mainpwd.txt", "client_certificate_file":"/mstr/client.p12", "bypass_ssl":"true", "timeout":"7000"}
   You must provide both file paths, and they should be absolute paths. If a file path includes backslashes, such as in a Microsoft Windows-based system, you must double-escape each backslash as follows: \\\\.

4. Update the database with the new values. An example SQL statement to update the database is below:
   update org_adapter_config set opt_properties='{"client_certificate_password_file":"/mstr/config/mainpwd.txt", "client_certificate_file":"/mstr/client.p12", "bypass_ssl":"true", "timeout":"7000"}' where id=id_no

5. Log into MicroStrategy Identity Manager:
   1. Navigate to the Identity Manager home page.

   2. On your smartphone, open MicroStrategy Badge and scan the displayed QR code.

6. Click Physical Gateways.
7. Under Building Access, click Edit for the PACS adapter you are configuring with mutual authentication.
8. Click Reconfigure PACS. You do not need to change any settings.

9. Click Save.

Mutual authentication is enabled, and you can use MicroStrategy Badge to open one of the doors that you could open before you configured mutual authentication.

Related Topics

Integrating Lenel® OnGuard® with MicroStrategy Identity

Integrating Paxton Net2 with MicroStrategy Identity

Integrating S2 NetBox® with MicroStrategy Identity

Configuring Your Custom PACS Adapter for MicroStrategy Identity