Files
zitadel/apps/docs/content/guides/integrate/login/oidc/native-app-links.mdx
T
c9d747d407 fix(api): prevent cross-instance caching of well-known app link files (#12644)
# 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]>
2026-08-26 10:57:28 +02:00

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)