IIS for mobile dev: use WACS client to make LetsEncrypt https cert
Question: how to make a free trusted HTTPS certificate for use when developing mobile apps with IIS on a development system which is intentionally private?
Short answer: use the win-acme client with dns validation
( retested 22.Apr.2020 )
The screenshots here were made with WACS v2.0.3.206 on March 9, 2019.
1. As a gesture of respect to the ancestors, bow to https://letsencrypt.org
2. You need the wacs.exe client which you get from github on the releases tab in the win-acme project, or, even better in April 2020, start at https://www.win-acme.com/ and use their Download menu.
If you are building a WebHub Appliance, reference PowerShell script 01114_IIS_Win_ACME_Simple.ps1, which will download and install a recent pluggable version of WACS plus the extra Route 53 files for you.
Reminder: You will also need to be able to login to your DNS control panel, wherever that might be. This example uses AWS Route 53. The approach works with ANY DNS host that lets you add and delete TXT records. This includes GKG.NET, which was tested yesterday.
If you want professional support for WACS or just want to buy (@WouterTinus) a beer for maintaining wacs.exe, please check out his patreon page.
The steps below are for the situation where port 80 on a private development machine does not respond to verification tests from the letsencrypt.org system located in public internet space.
AND. This example uses a domain name, lite.demos.href.com, that was public at the time of writing, but that is not the point. This technique works for domains that resolve to 192.168.0.14 or any other local network number.
3. Ok. After unzipping, just run wacs.exe.
4. Make use of option M: Create new certificate with advanced options.
TIP
In some parts of WACS, pressing the menu letter or number is enough. In some parts, you also must press [Enter]. A word to the wise: do not press [Enter] too quickly or you can find yourself having answered an extra question. At that point, you can kill the process and start over.
For the first menu, type M [Enter] to move forward.
For Emphasis ::: you Must press M to get into the More options sub Menu, in which you will find a way to validate your private subdoMain using DNS. If you are using AWS Route 53, you should have installed the Route 53 DNS plug-in BEFORE starting wacs.exe.
5. This next menu hints at the power of the WACS client.
The right answer varies. Keep in mind you will be making and deleting 1 DNS entry for each site you make a cert for. If you can do your mobile testing on a single domain, just focus on that one domain.
If you are not sure, try an option and follow it forward a few steps. Things become obvious with experience.
For this walk though, 1: Single binding of an IIS site was selected, followed by the name of the domain. ( lite.demos.href.com )
6. Accept the default cert name.
7. DO NOT CHOOSE THE DEFAULT HERE !
Instead choose 2 [dns-01] Manually create record so that you will be given the necessary details on the screen. ( NB: the menu numbers can change from version to version. You want a DNS option and generally the first DNS option is the correct one. )
If you are using the Route 53 plug-in, you will be prompted for credentials including the Access Key and Secret Access Key for the account which will make the Route 53 entries on your behalf.
8. Choose the default, 2: Standard RSA key pair.
9. Choose the default, 2: Windows Certificate Store.
10. Choose the default, 1: Create or update https bindings in IIS.
11. Would you like to run additional installer steps y/n: Answer n.
12: Use different site for installation: Answer n.
13. Answer the questions about your email address and terms of service.
AH HA
At this point you are given the precious DNS details which you must copy and paste into the appropriate spots in your own DNS control panel...
[INFO] Authorize identifier: lite.demos.href.com
[INFO] Authorizing lite.demos.href.com using dns-01 validation (Manual)
Domain: lite.demos.href.com
Record: _acme-challenge.lite.demos.href.com
Type: TXT
Content: "oKxxxxxxxxgc"
Note 1: Some DNS control panels add quotes automatically. Only one set is required.
Note 2: Make sure your name servers are synchronised, this may take several minutes!
Please press enter after you've created and verified the record.
14. Go into DNS and add the TXT record as explained by WACS.... then return to WACS and press [Enter].
15A. To avoid getting Validation-Failed in WACS because your DNS change has not rippled yet, especially if your DNS control panel does not let you set the TTL, you should use a tool to verify that your TXT record can be seen from the public internet. For example, you could visit Network-Tools nslookup and keep checking for your TXT record by clicking their [Go] button. ( Note, for the DNS Server used during NSLOOKUP, you can use the OPEN DNS server 208.67.222.222, or put in the name server configured for your own domain. )
15B. Within WACS, wait for validation to come back True or False. This validation is happening between letsencrypt.org in the public internet and your DNS provider...
16. Back in your DNS panel, delete the same TXT record you created a moment ago. Return to WACS and press [Enter].
17. There are a couple of final questions within WACS for the automatic renewal feature. These manual dns renewals cannot work automatically so this is less interesting, basically you just want to get out.
18. Finally, make sure it all worked. Check the results in IIS. At the top of your IIS tree, you can go into the feature Server Certificates to verify that a new cert has been added.
19. In IIS, at your site level, go into Bindings and where previously you only had a binding on port 80 for the domain name, now there will be a binding for port 443 using the new https certificate.
20. Test in a web browser, https://lite.demos.href.com/robots.txt and you should see further confirmation that the https protocol is working propertly (obviously do this within your LAN).
21. Get your mobile device connected to the same LAN, and test. You should be able to connect without any infuriatingly mysterious https certificate errors.
22. If you have spare time, plant a tree or water a seedling.
 |
| https://flic.kr/p/qJccKy |
UPDATE January 2020
"WACS" now supports some plug-ins to do DNS entries automatically. This is a HUGE time-saver. To take advantage of this, make sure you have a recent release from win-acme.com and also download the appropriate plug-ins depending on where you have your DNS control panel. AWS Route 53 is fully supported.( retested 22.Apr.2020 )
The Original Long Answer Follows
This particular post is addressed to people who have used IIS for a while and have installed at least one security certificate successfully. If it accidentally helps a total beginner, well, remember to pass it forward.The screenshots here were made with WACS v2.0.3.206 on March 9, 2019.
1. As a gesture of respect to the ancestors, bow to https://letsencrypt.org
2. You need the wacs.exe client which you get from github on the releases tab in the win-acme project, or, even better in April 2020, start at https://www.win-acme.com/ and use their Download menu.
If you are building a WebHub Appliance, reference PowerShell script 01114_IIS_Win_ACME_Simple.ps1, which will download and install a recent pluggable version of WACS plus the extra Route 53 files for you.
Reminder: You will also need to be able to login to your DNS control panel, wherever that might be. This example uses AWS Route 53. The approach works with ANY DNS host that lets you add and delete TXT records. This includes GKG.NET, which was tested yesterday.
 |
| https://flic.kr/p/5dkAP |
If you want professional support for WACS or just want to buy (@WouterTinus) a beer for maintaining wacs.exe, please check out his patreon page.
IMPORTANT NOTE
If you are making certs for a public machine, where DNS for the domain(s) naturally points to the server hosting those domains, then you do not need the complex steps below. Instead use the default, recommended choices, with http authentication and automatic installation into IIS.The steps below are for the situation where port 80 on a private development machine does not respond to verification tests from the letsencrypt.org system located in public internet space.
AND. This example uses a domain name, lite.demos.href.com, that was public at the time of writing, but that is not the point. This technique works for domains that resolve to 192.168.0.14 or any other local network number.
3. Ok. After unzipping, just run wacs.exe.
4. Make use of option M: Create new certificate with advanced options.
TIP
In some parts of WACS, pressing the menu letter or number is enough. In some parts, you also must press [Enter]. A word to the wise: do not press [Enter] too quickly or you can find yourself having answered an extra question. At that point, you can kill the process and start over.
For the first menu, type M [Enter] to move forward.
For Emphasis ::: you Must press M to get into the More options sub Menu, in which you will find a way to validate your private subdoMain using DNS. If you are using AWS Route 53, you should have installed the Route 53 DNS plug-in BEFORE starting wacs.exe.
5. This next menu hints at the power of the WACS client.
The right answer varies. Keep in mind you will be making and deleting 1 DNS entry for each site you make a cert for. If you can do your mobile testing on a single domain, just focus on that one domain.
If you are not sure, try an option and follow it forward a few steps. Things become obvious with experience.
For this walk though, 1: Single binding of an IIS site was selected, followed by the name of the domain. ( lite.demos.href.com )
6. Accept the default cert name.
7. DO NOT CHOOSE THE DEFAULT HERE !
Instead choose 2 [dns-01] Manually create record so that you will be given the necessary details on the screen. ( NB: the menu numbers can change from version to version. You want a DNS option and generally the first DNS option is the correct one. )
If you are using the Route 53 plug-in, you will be prompted for credentials including the Access Key and Secret Access Key for the account which will make the Route 53 entries on your behalf.
8. Choose the default, 2: Standard RSA key pair.
9. Choose the default, 2: Windows Certificate Store.
10. Choose the default, 1: Create or update https bindings in IIS.
11. Would you like to run additional installer steps y/n: Answer n.
12: Use different site for installation: Answer n.
13. Answer the questions about your email address and terms of service.
AH HA
At this point you are given the precious DNS details which you must copy and paste into the appropriate spots in your own DNS control panel...
[INFO] Authorize identifier: lite.demos.href.com
[INFO] Authorizing lite.demos.href.com using dns-01 validation (Manual)
Domain: lite.demos.href.com
Record: _acme-challenge.lite.demos.href.com
Type: TXT
Content: "oKxxxxxxxxgc"
Note 1: Some DNS control panels add quotes automatically. Only one set is required.
Note 2: Make sure your name servers are synchronised, this may take several minutes!
Please press enter after you've created and verified the record.
14. Go into DNS and add the TXT record as explained by WACS.... then return to WACS and press [Enter].
15A. To avoid getting Validation-Failed in WACS because your DNS change has not rippled yet, especially if your DNS control panel does not let you set the TTL, you should use a tool to verify that your TXT record can be seen from the public internet. For example, you could visit Network-Tools nslookup and keep checking for your TXT record by clicking their [Go] button. ( Note, for the DNS Server used during NSLOOKUP, you can use the OPEN DNS server 208.67.222.222, or put in the name server configured for your own domain. )
15B. Within WACS, wait for validation to come back True or False. This validation is happening between letsencrypt.org in the public internet and your DNS provider...
16. Back in your DNS panel, delete the same TXT record you created a moment ago. Return to WACS and press [Enter].
17. There are a couple of final questions within WACS for the automatic renewal feature. These manual dns renewals cannot work automatically so this is less interesting, basically you just want to get out.
18. Finally, make sure it all worked. Check the results in IIS. At the top of your IIS tree, you can go into the feature Server Certificates to verify that a new cert has been added.
19. In IIS, at your site level, go into Bindings and where previously you only had a binding on port 80 for the domain name, now there will be a binding for port 443 using the new https certificate.
20. Test in a web browser, https://lite.demos.href.com/robots.txt and you should see further confirmation that the https protocol is working propertly (obviously do this within your LAN).
21. Get your mobile device connected to the same LAN, and test. You should be able to connect without any infuriatingly mysterious https certificate errors.
22. If you have spare time, plant a tree or water a seedling.
Comments