From 016df96bcceef61436dab76476503dad3fb69da2 Mon Sep 17 00:00:00 2001
From: Joshua Lusk <luskjh@gmail.com>
Date: Tue, 26 May 2026 09:52:41 -0400
Subject: add keychain access troubleshooting for mTLS

---
 .repo/keychain.png | Bin 0 -> 114658 bytes
 README.md          |  27 +++++++++++++++++++++++++--
 2 files changed, 25 insertions(+), 2 deletions(-)
 create mode 100644 .repo/keychain.png

diff --git a/.repo/keychain.png b/.repo/keychain.png
new file mode 100644
index 0000000..60050bb
Binary files /dev/null and b/.repo/keychain.png differ
diff --git a/README.md b/README.md
index 53b6ac7..8ab85e5 100644
--- a/README.md
+++ b/README.md
@@ -55,12 +55,35 @@ $ make bootstrap ANSIBLE_USER=root ANSIBLE_PORT=22
 
 The subdomain `hollyhock` is secured with mTLS - once the `devops`
 playbook is run succesfully, on macOS you need to add
-`tmp/hollyhock.p12` to your keychain:
+`tmp/hollyhock.p12` to your keychain (see troubleshooting before
+attempting an import):
 
 ```sh
-$ security import tmp/hollyhock.p12 -k ~/Library/Keychains/login.keychain-db -P <mtls_p12_password>
+$ security import tmp/hollyhock.p12 \
+  -k ~/Library/Keychains/login.keychain-db \
+  -P <mtls_p12_password>
 ```
 
+#### Troubleshooting
+
+mTLS can be a little finicky. Here are some things to try
+(tips are macOS specific).
+
+If you have any specific applications you know will need to access the
+key (like your web browser), you can specify it on import `-T`:
+
+```sh
+$ security import tmp/hollyhock.p12 \
+  -k ~/Library/Keychains/login.keychain-db \
+  -P <mtls_p12_password>
+  -T /Applications/Google\ Chrome.app
+```
+
+If you've imported multiple times, you may want to clear out the old
+certificates directly in Keychain Access before re-importing:
+
+![keychain access](.repo/keychain.png)
+
 ## CI / deployments
 
 There is a CI workflow that runs the same pre-commit hooks on GitHub as
-- 
cgit v1.2.3