On-Prem Mobile with HTTPS
1. Scope
Android requires your application releases to tracker specific newer version of the Android SDK on each release to the app store. This combined with new policies on Android that disallow non-encrypted HTTP service calls has created a support scenario for customers who use the Android app with HTTP on-premise. The solution and ultimately best practice is to use HTTPS between the CIP server and the mobile application.
2. Background
It is assume the reader of this document is familiar with x.509 certificate chains and specifically certificate authorities and the differences between a domain CA and a public CA. Some useful reading on these topics can be found at:
3. Best Practice
All CIP Reporting hosted solutions are over HTTPS but on-premise systems are often deployed using HTTP to avoid certificate management overhead. If your system is using HTTP you should consider adopting the best practice of using HTTPS on all your CIP servers. For non-mobile applications this is as simple as generating a CSR, generating a signed certificate, and installing it on your CIP server commonly done with your domain CA.
The CIP server runs on port 4399 for HTTP by default and 4398 for HTTPS by default. The default deployment of a CIP server will install a self-signed certificate on port 4398. You can reach your CIP server over HTTPS at:
4. Unique Challenges
This scenario is further complicated by the fact that Android devises are unaware of your domain CA by default (unless you are using management software for your mobile devices that remedies this issue). This means the typical and usual practice of generating certificates from your domain CA will result in certificates that are not trusted and blocked by Android. There are two solutions to this issue either to use a certificate signed by a public CA or update your Android device to trust your domain CA.
4.1 Using a Public CA
This solution also has unique challenges in that public CAs will not sign certificates that use non-internet addressable domain names. For example, on your network if your CIP server hostname is “cip.local” no public CA will give you a signed certificate for that hostname. This is because the hostname uniqueness cannot be guaranteed. If you could buy public certificates using these names you could “man in the middle” attack your employers servers.
To use a public CA you must have an internet addressable fully qualified domain name (FQDN). To do this on a local network requires playing games with DNS. Assume the following:
Your internal domain is known as “.local”
Your CIP server is “cip.local”
One strategy would be to purchase a publicly signed certificate for “cip.mycompany.com” from a public CA. Then you can install that certificate on your CIP server. However, on your local network you need that domain name to resolve to your local server. Generally you can do this on your domain by adding a local DNS record that routes that FQDN to the IP address of your CIP server. At this point on your local network you can access your CIP server over HTTPS using the following URL:
Externally on the internet the FQDN never resolves because there is no actual public DNS record for the host. You should be able to test this with a browser on a desktop on your network and from a browser on your Android device and ensure you get no certificate errors. Assuming you are successful your Android device will work correctly.
4.2 Installing the Domain CA as a Trusted Root
All internet capable computing systems maintain a list of trusted root CAs. The list of trusted root CAs varies by operating system, company, device, policy, etc. On a Windows domain typically Microsoft manages a list of trusted roots that gets updated by way of Windows Update. Further, on a domain usually the domain CA itself is automatically added to the trusted roots on the domain thus your local CA can sign certificates and your domain enabled workstations trust them. Android, unfortunately, is not domain joined and does not trust your domain CA.
You can however export your domain CAs certificate, upload it to the storage of your Android device, and import it. You can import the certificate under security settings of your Android device. We do not go into specific steps on this because each Android device and version varies but it is generally easy to figure out in a few moments. You must export your domain CA certificate, upload it to your Android device, and then install it as a trusted root. At that point you should be able to install a domain CA signed certificate on your CIP server and access it both from a desktop and your Android device without certificate errors using the following URL:
5. Certificate Installation
Once you have obtained your server certificate, private key, and any intermediate certificates from your Certificate Authority (CA), you will need to install them on your CIP server to enable HTTPS. Follow these steps to install your certificates using the provided commands:
All these commands must be run from the CIP Shell.
Install the Server Certificate
The server certificate is the certificate issued specifically for your domain by the CA.
Use the command
cert install server [path/to/your/server.crt]to install your server certificate. Replace[path/to/your/server.crt]with the actual path to your server certificate file.
Example:
cert install server /etc/ssl/certs/cip_server_certificate.crtInstall the Private Key
The private key is generated when you create your CSR (Certificate Signing Request). It should be kept secure and private.
Use the command
cert install private [path/to/your/private.key]to install your private key. Replace[path/to/your/private.key]with the actual path to your private key file.
Example:
cert install private /etc/ssl/private/cip_server_private.keyInstall Intermediate Certificates (if applicable)
Intermediate certificates are used to chain yours to the root certificate of your CA, aiding in the trust process.
Use the command
cert install intermediate [path/to/your/intermediate.crt]to install any intermediate certificates provided by your CA. Replace[path/to/your/intermediate.crt]with the actual path to your intermediate certificate file.
Example:
cert install intermediate /etc/ssl/certs/cip_intermediate_certificate.crt
Ensure that after installing the certificates, you verify the configuration by accessing your CIP server over HTTPS using the corresponding URL mentioned in section 4. If you encounter any certificate errors, double-check the installation steps and the certificate paths.
CIP support will assist with these issues and advise as best we can on how to proceed based on what works best for you as a customer. Our support team will also assist with setting up HTTPS on our side and generating CSRs, etc.
6. Certificate Lifecycle
Certificates are a point of maintenance that you are likely already familiar with. However, you should be aware that your certificates will expire based on the details of the CA who signed your certificate. You should be aware of these expirations and be prepared to renew certificates in advance of their expiration. This is something you need to track as a customer to avoid your CIP server being inaccessible due to a certificate expiration. A best practice we have observed is customers creating a shared calendar in IT to track certificates issued and expirations.
7. Migration
Your CIP server uses both HTTP and HTTPS in parallel on different ports by default. Once you enable HTTPS to resolve Android mobile issues you do not necessarily need to change your clients to HTTPS, but you should. However, you can migrate slowly by updating URLs on your clients without interruption. Once they are all migrated to HTTPS we recommend disabling HTTP.