Live Reload with HTTPS

To aid with rapid development the Live Reload feature will allow your browser or mobile device to use your development web server instead of static files on your device. Whenever you change a file in your editor the device will reload your app and display your changes.

In the Ionic VS Code extension, you can chooseSettings>Live Reloadand then run on the Web or mobile device to use the Live Reload feature.

Live Reload will use http (not https) and this may affect your application particularly if it uses APIs that require a secure context (such as geolocation, crypto).

Live Reload with SSL

If your app uses APIs that require a secure context (like web crypto) then it must be served using HTTPS (or not use live reload). The device will also need to trust the connection which means that if you use a self-signed certificate it will need to be installed and trusted on the device.

The Ionic VS Code extension can help create a self-signed certificate and trust it on devices. ChooseSettings>Use HTTPS. When you check the boxUse HTTPSit will generate a self-signed certificate on your computer and will display a page with instructions on how to download, install and trust the certificate.

Skipping SSL Checks

Avoiding SSL errors is the quick way to work but it isn't the right way to work. The best way is to install and trust the certificate on the device (or your Mac/PC if testing using a web browser).

In some scenarios, the VS Code extension will use a plugin to avoid SSL errors when running on iOS and Android avoiding the need to trust the self-signed certificate.  

If you would like to avoid SSL errors in your project (eg for React/Vue) temporarily during development you can install the plugin@jcesarmobile/ssl-skipbut you must remove this plugin before committing your code as it is not intended for production applications. This plugin works for iOS and Android: on the web, you must use a valid trusted certificate (see below).

Self Signed Certificates

Creating your own self-signed certificate and using it with your development web server is quite challenging which is why the Ionic VS Code extension removes this complexity for you.

However, if you are interested in how this is done or would like to know how to do this manually then read on.

Let's break down the tasks you need to accomplish:

1. Create a Root CA Certificate
2. Create a Server Certificate
3. Install and Trust the Root CA Certificate
4. Run your app using the Server Certificate

Create a Root CA Certificate

To use HTTPS you need to have a certificate associated with your web server. In production, the certificate you use is issued by a trusted certificate authority (CA). In development, you will need to issue your own and for this, we'll use the tool openssl.

First, we'll create a private key (in this example the file is called ca.key):

openssl genrsa -out ca.key 4096

Next, we'll create the certificate:

openssl req -config cr-ca.txt -key ca.key -new -x509 -days 3650 -sha256 -out ca.crt

You'll notice that we need a file called cr-ca.txt. You can create this file a paste the following into it:

[req]
default_bits = 4096
default_md = sha256
distinguished_name = subject
req_extensions = req_ext
x509_extensions = x509_ext
string_mask = utf8only
prompt = no

[ subject ]
C = US
ST = WI
L = Madison
O = Ionic
OU = Development
CN = Ionic Root CA Certificate

[ req_ext ]
basicConstraints = critical, CA:true
keyUsage = critical, keyCertSign, cRLSign
subjectKeyIdentifier = hash
subjectAltName = @subject_alt_name
authorityKeyIdentifier = keyid:always,issuer:always
issuerAltName = issuer:copy

[ x509_ext ]
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer
basicConstraints = critical, CA:TRUE
keyUsage = critical, digitalSignature, keyEncipherment, cRLSign, keyCertSign

[ subject_alt_name ]
URI = https://ionic.io/
email = [e-mail]

You have now created a root CA certificate (the file ca.crt) which will be used to issue server certificates. When your application uses HTTPS in a web browser or mobile device the server certificate will be checked and will only be marked as secure if the device trusts it. A device will trust a server certificate if it was signed by a CA that it trusts (we'll explain how to do that later).

Create a Server Certificate

Your development web server will host your application using your computer's IP Address(es) and hostname and these will be part of the server certificate presented when using HTTPS.

To create your certificate you can run:

openssl req -new -nodes -sha256 -keyout server.key -config cr.txt -out server.csr -newkey rsa:4096 -subj "/C=US/ST=/L=/O=/CN=myserver"
openssl x509 -sha256 -extfile cr.txt -extensions x509_ext -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 180

You will need a file called cr.txt and you can create this file by pasting the following:

[req]
default_bits = 4096
default_md = sha256
distinguished_name = subject
req_extensions = req_ext
x509_extensions = x509_ext
string_mask = utf8only
prompt = no

[ subject ]
C = US
ST = WI
L = Madison
O = Ionic
OU = Development
CN = 192.168.0.131

[ x509_ext ]
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid,issuer
basicConstraints = CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
subjectAltName = @alternate_names

[ req_ext ]
subjectKeyIdentifier = hash
basicConstraints = CA:FALSE
keyUsage = digitalSignature, keyEncipherment
subjectAltName = @alternate_names

[ alternate_names ]
DNS.2 =localhost
IP.1 =127.0.0.1
IP.2 =192.168.0.131

This is similar to the settings needed for a CA certificate but there are some important differences:

1. Short-lived - This certificate will expire soon - you should regenerate the certificate as part of a script. Mobile devices will not trust long-lived certificates (ref).
2. Assigned to your IP Address - You will need to change the IP Address in this configuration file to the external IP address(es) associated with your computer (change the setting called CN and underneath [alternate-names]).

At the end of this process, you have a server certificate (server.crt) and its private key (server.key) that can be used on your local development computer.

Install the Root CA Certificate

You will need to install and trust the Root CA Certificate (the file named ca.crt) on each device you will be testing your app. On a web browser, this will mean you won't get a certificate warning and when run on iOS or Android with Capacitor this will mean you won't get a white screen.

On a Mac

• Open the ca.crt file using the Keychain Access app
• Double click Ionic Root CA Certificate
• Expand the Trust section
• Choose Aways Trust from the drop-down next to When Using This Certificate

On iOS

Certificates can be installed through mobile Safari, so you need to serve up the file ca.crt temporarily to allow it to be installed. You could create a file index.html and include the HTML <a href="ca.crt">Download</a>. Then serve this file.

• Click the Download link
• Choose Allow to the configuration profile download
• If asked choose iPhone
• Go to the Settings app
• Press the Profile Downloaded option
• Press Install (& confirm several times)
• Press Done button
• Go to the General > About section
• Scroll to the bottom and choose Certificate Trust Settings
• Enable Ionic Root CA Certificate to enable full trust for the root Certificate

After installation when you open your app in mobile Safari with https://your-external-ip it will be trusted and will not show a certificate trust error.

You can run your app using Capacitor and it will display correctly, any Web APIs used like web crypto will work as you are serving the app using HTTPS with a trusted certificate.

On Android

Certificates can be downloaded through Chrome so you need to serve up the file ca.crt temporarily to allow it to be installed. You could create a file index.html and include the HTML <a href="ca.crt">Download</a>. Then serve this file.

• Click the Download link
• Go to the Android Settings app
• Go to Security > Encryption & Credentials
• Press Install a certificate
• Press CA Certificate and choose Install Anyway
• Choose the ca.crt.pem file that was downloaded earlier

After installation when you open your app in Chrome with https://your-external-ip it will be trusted and will not show a certificate trust error.

Unfortunately, an Android Capacitor App will not trust a user-installed CA certificate so if you are testing with this scenario you will need to bypass trust checks using a plugin. You can do this by running:

npm install @jcesarmobile/ssl-skip

Now, after syncing your Capacitor project your Android app will run as expected and any Web APIs that require a secure context like web crypto will work.

Run using a Certificate

Running your app using SSL and the server certificate you created can be done with the Ionic CLI with this command:

ionic serve --ssl -- --ssl-cert=server.crt --ssl-key=server.key

You'll notice that we have an extra -- which will forward the cert and key arguments onto Angular's CLI.

For React Apps, you'll need to follow these instructions.

For Vue Apps, you'll need to alter vue.config.js using info from this vue issue.

Troubleshooting

A white screen on startup is the typical problem associated with a misconfigured app that is attempting to use HTTPS. You may get better diagnostics by running your app in XCode or Android Studio. The problem will be related to one of the following:

1. The CA certificate is not installed - make sure the certificate appears in iOS Settings > General > Device Management, or Android Settings > Security > Encryption & Certificates, or Mac Keychain Access.
2. The CA certificate is not trusted -  make sure the certificate is trusted in iOS Settings > General > About > Certificate Trust Settings or by double clicking in Keychain Access and the trust section.
3. The Server certificate IP Address is wrong - make sure the IP Address you are using to serve the app is listed in the configuration of the server certificate. The external IP address of your computer can change dynamically so you may need to regenerate the server certificate.
4. The Server certificate has expired - make sure the expiration date on the server certificate is after today. Regenerate the server certificate if it is before.
5. Android Web View doesn't trust - The Android web view will not trust a CA Certificate that was installed by the user even if it was installed correctly. You can install the plugin @jcesarmobile/ssl-skip to avoid this problem.
6. Mobile Device is not on your network - Your mobile device must be able to see the external IP address of your development web server. Ensure that the mobile device is on the right wifi network (you should be able to access the web app in the browser of the mobile device). You should also ensure that your firewall is not blocking the port. Some corporate environments may prevent peer network traffic and you may need to consult with your IT department.

Conclusion

Creating, installing, trusting, and troubleshooting Self Signed certificates can be quite challenging. I would recommend using the default setup for Capacitor projects where possible to avoid worrying about this topic.

If you need HTTPS to use web APIs that require a secure context then I would recommend using the Ionic VS Code Extension to simplify the setup and maintenance of certificates.