mirror of
https://github.com/andwati/zitadel.git
synced 2026-11-19 19:48:45 +00:00
# Which Problems Are Solved The `/.well-known/apple-app-site-association` and `/.well-known/assetlinks.json` responses are instance specific: the body depends on the requested host. The responses did not declare this, so a shared cache whose cache key does not include the host could store one instance's file and serve it on another instance's domain. This could result in a wrong or empty file being returned intermittently, breaking native passkey verification. Dropping the `public` directive (#12634) was not sufficient: depending on its cache mode, a shared cache may store any response carrying a `max-age`. The docs page for native app links also still documented the old `Cache-Control: public` header and only the single `get_login_creds` relation (missing `handle_all_urls`, added in #12634). # How the Problems Are Solved - Send **`Vary: Host`** on both well-known responses, declaring that the body depends on the host: a spec-compliant shared cache must store per-host variants or skip caching. Clients addressing a single host (the Apple and Google verifiers, browsers) are unaffected and keep honoring the configured `max-age`. - Correct the outdated caching reasoning in the code comments. - Guard the header with unit and integration tests. - Update the native app links docs page: both Digital Asset Links relations and the current response headers. # Additional Changes None. `WellKnown.AppLinksCacheControlMaxAge` behavior is unchanged (`0` still results in `no-store`). # Additional Context - Follow-up to #12634; relates to #12497. - Verified with interleaved requests against two instances: responses are no longer reused across domains, and each domain consistently serves its own configuration. - To be cherry-picked to `v4.x` from `main` once merged. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Fable 5 <[email protected]>
131 lines
4.5 KiB
Plaintext
131 lines
4.5 KiB
Plaintext
---
|
|
title: Native app links for passkeys
|
|
description: "Configure iOS and Android association on OIDC apps so ZITADEL can serve apple-app-site-association and assetlinks.json for native passkeys"
|
|
sidebar_label: Native App Links
|
|
---
|
|
|
|
Native mobile apps that create or use passkeys with platform WebAuthn APIs need the issuer domain to publish OS trust association files.
|
|
ZITADEL serves those files from your instance based on iOS and Android settings on OIDC applications.
|
|
|
|
## Prerequisites
|
|
|
|
- An OIDC **Native** application in your project
|
|
- Passkeys enabled in your login policy
|
|
- A stable issuer / [custom domain](/concepts/features/custom-domain) (passkeys are domain-bound)
|
|
- Platform association configured in the mobile app project (Associated Domains on iOS; Digital Asset Links / App Links on Android)
|
|
|
|
## Configure the OIDC application
|
|
|
|
Set association fields on each Native OIDC app that should participate in passkey trust.
|
|
|
|
You can do this in the [Console](/guides/manage/console/applications-overview#native-app-links) under the app's **Native App Links** section, or via the Application API / Management API OIDC app create and update endpoints (`ios` / `android`).
|
|
|
|
### iOS
|
|
|
|
| Field | Description |
|
|
|-------|-------------|
|
|
| **Team ID** | Apple Developer Team ID (exactly 10 alphanumeric characters), for example `ABCDE12345` |
|
|
| **Bundle ID** | App bundle identifier (`CFBundleIdentifier`), for example `com.example.app` — do not include the Team ID prefix |
|
|
|
|
ZITADEL publishes these as a single App ID in the association file: `{team_id}.{bundle_id}`.
|
|
|
|
### Android
|
|
|
|
| Field | Description |
|
|
|-------|-------------|
|
|
| **Package name** | Android `applicationId` / package name from the app manifest |
|
|
| **SHA-256 certificate fingerprints** | Signing certificate fingerprints (64 hex characters, optionally colon-separated). Include debug and release fingerprints as needed. |
|
|
|
|
### Update semantics
|
|
|
|
On update:
|
|
|
|
- Omit a field group to leave it unchanged
|
|
- Send an empty message / empty values to clear
|
|
- Send populated values to replace
|
|
|
|
## Well-known endpoints
|
|
|
|
ZITADEL aggregates association data from **active** OIDC apps on the instance and serves:
|
|
|
|
| Path | Purpose |
|
|
|------|---------|
|
|
| `${CUSTOM_DOMAIN}/.well-known/apple-app-site-association` | iOS Associated Domains / `webcredentials` |
|
|
| `${CUSTOM_DOMAIN}/.well-known/assetlinks.json` | Android Digital Asset Links for `delegate_permission/common.handle_all_urls` and `delegate_permission/common.get_login_creds` |
|
|
|
|
If no apps are configured, both endpoints still return HTTP `200` with empty collections.
|
|
|
|
### Example: apple-app-site-association
|
|
|
|
```json
|
|
{
|
|
"webcredentials": {
|
|
"apps": [
|
|
"ABCDE12345.com.example.one",
|
|
"FGHIJ67890.com.example.two"
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
Duplicate iOS App IDs across apps are deduplicated.
|
|
|
|
### Example: assetlinks.json
|
|
|
|
```json
|
|
[
|
|
{
|
|
"relation": [
|
|
"delegate_permission/common.handle_all_urls",
|
|
"delegate_permission/common.get_login_creds"
|
|
],
|
|
"target": {
|
|
"namespace": "android_app",
|
|
"package_name": "com.example.one",
|
|
"sha256_cert_fingerprints": [
|
|
"AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
|
|
]
|
|
}
|
|
}
|
|
]
|
|
```
|
|
|
|
Fingerprints are normalized to colon-separated uppercase hex when served.
|
|
|
|
Both relations from [Google's Credential Manager prerequisites](https://developer.android.com/identity/credential-manager/prerequisites) are included, as some devices reject passkey creation when `handle_all_urls` is missing.
|
|
The additional relation only takes effect if your app declares matching intent filters.
|
|
|
|
## Caching
|
|
|
|
The contents are specific to your instance domain, so HTTP caching is disabled and the files are always served directly by ZITADEL:
|
|
|
|
```
|
|
Cache-Control: no-store
|
|
```
|
|
|
|
<Callout type="info">
|
|
Platform verifiers cache association files on their side.
|
|
After you change app link settings, allow time for OS verification to refresh before expecting passkeys to work with the new values.
|
|
</Callout>
|
|
|
|
## Verify
|
|
|
|
```bash
|
|
curl -i "${CUSTOM_DOMAIN}/.well-known/apple-app-site-association"
|
|
curl -i "${CUSTOM_DOMAIN}/.well-known/assetlinks.json"
|
|
```
|
|
|
|
Confirm:
|
|
|
|
- HTTP status `200`
|
|
- `Content-Type: application/json`
|
|
- `Cache-Control: no-store` header
|
|
- JSON contents match your configured apps
|
|
|
|
## Related
|
|
|
|
- [Passkeys concept](/concepts/features/passkeys)
|
|
- [Console applications](/guides/manage/console/applications-overview)
|
|
- [Custom domain](/concepts/features/custom-domain)
|
|
- [Passkeys in a custom login UI](/guides/integrate/login-ui/passkey) (browser / WebAuthn APIs)
|