You’ve probably developed a great WebSocket application, and it works perfectly in production but iOS devices never upgrade to WebSockets when developing/testing locally. Everything else upgrades to WebSockets locally, but not iOS. Why is that?
As you’ve probably realized, Apple locks down iOS very firmly, some might say too firmly, and that’s probably why you found this page — your iOS device isn’t making a WebSocket connection to your server. Assuming you’re doing all the obvious stuff right, the problem is likely that your security certificate doesn’t match your server. As a security precaution, iOS is very picky about that!
The TL;DR is that you need to create a fully populated security certificate that matches your localhost server IP address. You can’t use “localhost” as the address, you must use the server’s local network IP address. These are the main steps you will complete in this walkthrough:
- Generate a Security Certificate
- Install the certificate on your server
- Install the certificate on the iOS device
- Give the certificate full permissions in iOS
Read on for the more detailed step by step instructions:
1. Generate a Security Certificate
Warning! Do not rush through these steps, you must fill in every detail of the security certificate or iOS won’t accept it. Some of the details don’t have to be accurate but they all have to be filled in!
First, check the IP address for your server. This is going to be the local network IP address of the computer running your server. They’re typically in one of the following formats: 192.168.X.X or 10.0.X.X
Using openssl (install it if you don’t have it), replace IP_ADDRESS with your IP Address from the previous step and run it in macOS terminal, Windows PowerShell, or linux command line:
openssl genrsa -out IP_ADDRESS.key 2048
That will generate a key file. Now we generate a certificate from that. Again, replace IP_ADDRESS with your same IP Address from the previous step. Before you run this command, I want to stress again that you need to fill in all of the questions that it prompts you with. They don’t need to be accurate, but if you leave some blank then it WILL NOT WORK!
openssl req -new -x509 -days 3652 -key IP_ADDRESS.key -out IP_ADDRESS.pem
Awesome, you’ve got your own certificate now!
2. Install the certificate on your server
The details for this step are going to vary widely depending on which server you use and how you’ve got it configured. Because this step is going to be different for nearly everyone, I can’t cover it in detail — you may want to google for a guide based on your server and configuration. A successful search will look something like, “Node.js Certificate Installation” (replace “Node.js” with whichever server you’re using).
3. Install the certificate on the iOS device
Email the .pem file you created in step 1 to an email account that is setup on the iPad. Tap the .pem file in the email and then tap “install”. Enter your password if prompted and then tap “install” on the popup. Tap “Done” and the certificate is installed.
4. Give the certificate full permissions in iOS
Most people miss this last step because after installing the certificate we assume we’re done, but this step is absolutely critical! Navigate to this screen in the Settings App:
General -> About -> Certificate Trust Settings
Find your certificate and tap the switch so it’s green. This will “enabled full trust” for that root certificate.
Now, you can browse to your server from iOS and your WebSockets will work (assuming they’re already working in another browser).