Stateless auth proxy that converts AT Protocol native apps from public to confidential OAuth clients. Deploy once, get 180-day refresh tokens instead of 24-hour ones.
update readme with iOS info
+132
-1
+132
-1
README.md
+132
-1
README.md
···
123
123
"code_challenge": "<pkce_challenge>",
124
124
"code_challenge_method": "S256",
125
125
"state": "<state>",
126
-
"redirect_uri": "yourapp://oauth/callback"
126
+
"redirect_uri": "https://yourapp.com/oauth/callback"
127
127
}
128
128
```
129
129
···
156
156
| Refresh token lifetime | 24 hours | 180 days |
157
157
| Session lifetime | 7 days max | Unlimited |
158
158
| User re-login frequency | Every 1-7 days | Only when user chooses |
159
+
160
+
## HTTPS Redirect URIs (Required for iOS)
161
+
162
+
Bluesky's auth server enforces that `application_type: "native"` clients must use `token_endpoint_auth_method: "none"`. This means **you cannot use the proxy with `application_type: "native"`** — the PAR request will fail with:
163
+
164
+
```
165
+
{"error":"invalid_client_metadata","error_description":"Native clients must authenticate using \"none\" method"}
166
+
```
167
+
168
+
To use `private_key_jwt`, your client metadata must declare `application_type: "web"`, which requires HTTPS redirect URIs instead of custom URL schemes.
169
+
170
+
The AT Protocol OAuth spec explicitly supports this: native clients are allowed to use an HTTPS URL as long as the URL origin matches the `client_id`. For example, if your `client_id` is `https://yourapp.com/oauth/client-metadata.json`, your redirect URI must be `https://yourapp.com/...`.
171
+
172
+
Your client metadata should look like:
173
+
174
+
```json
175
+
{
176
+
"client_id": "https://yourapp.com/oauth/client-metadata.json",
177
+
"redirect_uris": ["https://yourapp.com/oauth/callback"],
178
+
"application_type": "web",
179
+
"token_endpoint_auth_method": "private_key_jwt",
180
+
"token_endpoint_auth_signing_alg": "ES256",
181
+
"dpop_bound_access_tokens": true,
182
+
"jwks_uri": "https://auth.yourapp.com/.well-known/jwks.json"
183
+
}
184
+
```
185
+
186
+
### iOS Setup
187
+
188
+
On iOS, HTTPS OAuth callbacks are handled via `ASWebAuthenticationSession`'s HTTPS callback API (iOS 17.4+). You also need an Apple App Site Association (AASA) file for Universal Links as a safety net.
189
+
190
+
#### 1. Apple App Site Association File
191
+
192
+
Serve this at `https://yourapp.com/.well-known/apple-app-site-association`:
193
+
194
+
```json
195
+
{
196
+
"applinks": {
197
+
"details": [
198
+
{
199
+
"appIDs": ["<TEAM_ID>.<BUNDLE_ID>"],
200
+
"components": [
201
+
{
202
+
"/": "/oauth/callback",
203
+
"comment": "AT Protocol OAuth callback"
204
+
}
205
+
]
206
+
}
207
+
]
208
+
},
209
+
"webcredentials": {
210
+
"apps": ["<TEAM_ID>.<BUNDLE_ID>"]
211
+
}
212
+
}
213
+
```
214
+
215
+
Replace `<TEAM_ID>` with your Apple Developer Team ID and `<BUNDLE_ID>` with your app's bundle identifier.
216
+
217
+
Requirements:
218
+
- Must be served with `Content-Type: application/json`
219
+
- Must **not** redirect — Apple's CDN fetches it directly
220
+
- Apple caches the file via its CDN; updates can take hours to propagate
221
+
- Verify propagation: `https://app-site-association.cdn-apple.com/a/v1/yourapp.com`
222
+
223
+
#### 2. Entitlements
224
+
225
+
Add an Associated Domains entitlement to your app (via Xcode: target > Signing & Capabilities > Associated Domains, or via an `.entitlements` file):
226
+
227
+
```xml
228
+
<key>com.apple.developer.associated-domains</key>
229
+
<array>
230
+
<string>applinks:yourapp.com</string>
231
+
<string>webcredentials:yourapp.com</string>
232
+
</array>
233
+
```
234
+
235
+
#### 3. ASWebAuthenticationSession
236
+
237
+
Use the HTTPS callback initializer instead of the custom-scheme one:
238
+
239
+
```swift
240
+
// Before (custom scheme — won't work with the proxy)
241
+
let session = ASWebAuthenticationSession(
242
+
url: authURL,
243
+
callbackURLScheme: "yourapp"
244
+
) { callbackURL, error in ... }
245
+
246
+
// After (HTTPS callback — required for the proxy)
247
+
let session = ASWebAuthenticationSession(
248
+
url: authURL,
249
+
callback: .https(host: "yourapp.com", path: "/oauth/callback")
250
+
) { callbackURL, error in ... }
251
+
```
252
+
253
+
This requires iOS 17.4+.
254
+
255
+
#### 4. Remove Custom URL Scheme
256
+
257
+
If you were previously using a custom URL scheme (e.g., `yourapp://oauth/callback`) for OAuth, remove the `CFBundleURLTypes` entry from your `Info.plist`. The custom scheme is no longer needed for OAuth callbacks.
258
+
259
+
#### 5. Web Fallback Page
260
+
261
+
Add a simple page at `/oauth/callback` on your website. `ASWebAuthenticationSession` intercepts the redirect before it reaches the server, but having a real page there improves the experience for edge cases (e.g., users who land there in a browser):
262
+
263
+
```html
264
+
<h1>Redirecting to YourApp...</h1>
265
+
<p>If you're not redirected automatically, open the app on your device.</p>
266
+
```
267
+
268
+
### Deployment Sequence
269
+
270
+
Order matters — deploy bottom-up so each layer is ready before the one above depends on it:
271
+
272
+
1. Deploy the auth proxy and verify it's live (`curl https://auth.yourapp.com/health`)
273
+
2. Deploy the AASA file to your website
274
+
3. **Wait** for Apple CDN propagation — verify via `https://app-site-association.cdn-apple.com/a/v1/yourapp.com`
275
+
4. Deploy updated client metadata (`application_type: "web"`, HTTPS redirect URI)
276
+
5. Build and test the iOS app **on a real device** (Universal Links don't work in Simulator)
277
+
6. Submit the app update
278
+
279
+
> **Warning:** Do not deploy the client metadata update before the AASA file is cached by Apple's CDN. If it isn't, Universal Links won't work and the OAuth callback won't route to your app.
280
+
281
+
### Rollback
282
+
283
+
If something goes wrong, revert your `client-metadata.json`:
284
+
- `application_type`: `"web"` back to `"native"`
285
+
- `redirect_uris`: HTTPS URL back to custom scheme
286
+
- `token_endpoint_auth_method`: `"private_key_jwt"` back to `"none"`
287
+
- Remove `jwks_uri` and `token_endpoint_auth_signing_alg`
288
+
289
+
The iOS app also needs a new build to switch back to `callbackURLScheme`. To minimize rollback friction, keep the AASA file deployed permanently — it has no downside even when unused.
159
290
160
291
## Key Rotation
161
292