From e9c72c0fe8a1d67e338f5971fa41d7c0062d21e3 Mon Sep 17 00:00:00 2001 From: Matt Hinz Date: Thu, 16 Jan 2025 16:38:16 -0800 Subject: [PATCH 1/3] Tweak how local cert is generated - Don't include port in CN - Add SAN including the IP address (required for Safari on iOS) [skip changelog] --- Makefile | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 4ee599d6467..45b43c507cc 100644 --- a/Makefile +++ b/Makefile @@ -215,7 +215,8 @@ tmp/$(HOST)-$(PORT).key tmp/$(HOST)-$(PORT).crt: ## Self-signed cert for local H -sha256 \ -nodes \ -days 365 \ - -subj "/C=US/ST=District of Columbia/L=Washington/O=GSA/OU=Login.gov/CN=$(HOST):$(PORT)" \ + -subj "/C=US/ST=District of Columbia/L=Washington/O=GSA/OU=Login.gov/CN=$(HOST)" \ + -addext "subjectAltName=IP:$(HOST)" \ -keyout tmp/$(HOST)-$(PORT).key \ -out tmp/$(HOST)-$(PORT).crt From aaf74619733adc4c84be1a597026a1fb3bdfef87 Mon Sep 17 00:00:00 2001 From: Matt Hinz Date: Thu, 16 Jan 2025 17:08:29 -0800 Subject: [PATCH 2/3] Update docs for local development - Bind to a specific IP - Describe how to trust cert on iOS --- docs/mobile.md | 44 +++++++++++++++++++++++++++++++++++++++----- 1 file changed, 39 insertions(+), 5 deletions(-) diff --git a/docs/mobile.md b/docs/mobile.md index 206f86e6b45..72e6d248f18 100644 --- a/docs/mobile.md +++ b/docs/mobile.md @@ -9,29 +9,63 @@ Instructions to use an iPhone or Android mobile device for local app development These instructions will configure your local copy of the identity-idp app to serve web pages over your local computer network — the wifi in your home or office. You can broadcast the app to a mobile phone or tablet. Both your mobile device and your development computer (your laptop) must be connected to the same wifi network. -By default, the application binds to `localhost`. These instructions bind to `0.0.0.0` instead. Some Android users report they can access `localhost:3000` directly on their phone, however. +By default, the application binds to `localhost`. To access it from a mobile device on the same network, you will need to bind it to an accessible IP address. -1. Find your Local Area Network IP address. On a MacBook, this is available at **System Preferences → Network**. The address may start with `192.168`. +1. Find your Local Area Network IP address. On a MacBook, this is available at **System Preferences → Network**. The IP address you are looking for likely starts with `192.168.` or `10.` 2. In your app's `application.yml` file, add the below. Be sure to indent these lines and include them in the `development:` section. Also, fill in your actual LAN IP address. The final line creates a **confirm now** link in place of email confirmation. ```yaml development: - domain_name: 192.168.x.x:3000 - mailer_domain_name: 192.168.x.x:3000 + domain_name: :3000 + mailer_domain_name: :3000 enable_load_testing_mode: true ``` 3. Start your app's local web server with: ```bash -HOST=0.0.0.0 make run-https +HOST= make run-https ``` 4. On your phone's browser, open a new tab. In the address bar, type in `https://` (don't forget the `s`) followed by your LAN IP and port number (like `https://192.168.x.x:3000`). When you visit this page, you may see a **Your connection is not private** message. Click **Advanced** and **Proceed** to continue. You should then see the sign in screen of the identity-idp app. After you complete these steps, pages from the app are served from your development machine to your mobile device, where you may now use the identity-idp app. For front-end development, you may now want to turn on browser development tools per the next section of these instructions. +### Special instructions for iOS + +It is becoming more common for browsers to entirely block access to sites using self-signed certificates, not even providing an escape hatch like the one described above. + +If you are not able to access the locally running app from your iPhone, follow these steps: + +#### 1. Somehow get the `.crt` file into the iOS Files app + +When you run `make run-https`, the system generates a self-signed SSL certificate for you and stores it in the `tmp` directory. The file will be named something like `-3000.crt`. You need to get that file onto your phone and into the iOS Files app. + +One way to do this is via Google Drive: + +1. Upload the file to Google Drive. +2. Open the Google Drive app on your phone and "Download" the `.crt` file. +3. When prompted for a destination, select "Save to Files". + +#### 2. Import the certificate into iOS + +1. Open the Files app. +2. Tap on the `.crt` file (fun fact: it may now show a `.cer` extension!). +3. You should see some kind of message about a profile being downloaded. +4. Open the Settings app. Notice you have a new "Profile Downloaded" item there. Tap that. +5. Install the profile. You will be prompted for confirmation many times. + +#### 3. Trust the certificate + +1. Go to **Settings > General > About > Certificate Trust Settings**. +2. Tick the little box next to the certificate you just installed. + +At this point, you _should_ be able to access the IdP running on your local development computer from your phone. + +> [!WARNING] +> Do not forget to un-trust the certificate and remove the profile when you are done. + ## Debugging with the desktop browser After you have completed the [§ Use the app from a mobile device](#use-the-app-from-a-mobile-device) instructions above, you may further want to use your desktop browser's development and dubugging tools. From 3a000a97f5feefdda5ef1373ac53c3ae35f26193 Mon Sep 17 00:00:00 2001 From: Matt Hinz Date: Fri, 17 Jan 2025 08:18:03 -0800 Subject: [PATCH 3/3] Don't include port number in name of SSL cert files This will ensure new keys / certs are generated without requiring folks to remove the old ones first. --- Makefile | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Makefile b/Makefile index 45b43c507cc..668fc0dead9 100644 --- a/Makefile +++ b/Makefile @@ -207,7 +207,7 @@ test_serial: export RAILS_ENV := test test_serial: $(CONFIG) ## Runs RSpec and yarn tests serially bundle exec rake spec && yarn test -tmp/$(HOST)-$(PORT).key tmp/$(HOST)-$(PORT).crt: ## Self-signed cert for local HTTPS development +tmp/$(HOST).key tmp/$(HOST).crt: ## Self-signed cert for local HTTPS development mkdir -p tmp openssl req \ -newkey rsa:2048 \ @@ -217,8 +217,8 @@ tmp/$(HOST)-$(PORT).key tmp/$(HOST)-$(PORT).crt: ## Self-signed cert for local H -days 365 \ -subj "/C=US/ST=District of Columbia/L=Washington/O=GSA/OU=Login.gov/CN=$(HOST)" \ -addext "subjectAltName=IP:$(HOST)" \ - -keyout tmp/$(HOST)-$(PORT).key \ - -out tmp/$(HOST)-$(PORT).crt + -keyout tmp/$(HOST).key \ + -out tmp/$(HOST).crt run: browsers.json ## Runs the development server foreman start -p $(PORT) @@ -227,8 +227,8 @@ urn: @echo "⚱️" make run -run-https: tmp/$(HOST)-$(PORT).key tmp/$(HOST)-$(PORT).crt ## Runs the development server with HTTPS - HTTPS=on FOREMAN_HOST="ssl://$(HOST):$(PORT)?key=tmp/$(HOST)-$(PORT).key&cert=tmp/$(HOST)-$(PORT).crt" foreman start -p $(PORT) +run-https: tmp/$(HOST).key tmp/$(HOST).crt ## Runs the development server with HTTPS + HTTPS=on FOREMAN_HOST="ssl://$(HOST):$(PORT)?key=tmp/$(HOST).key&cert=tmp/$(HOST).crt" foreman start -p $(PORT) normalize_yaml: ## Normalizes YAML files (alphabetizes keys, fixes line length, smart quotes) yarn normalize-yaml .rubocop.yml --disable-sort-keys --disable-smart-punctuation