feat: native app links for passkeys (#12580)

# Which Problems Are Solved

- Native iOS/Android passkeys need OS trust files on the ZITADEL domain;
without them, Associated Domains / App Links verification fails.
- Operators could not configure iOS Team ID + Bundle ID or Android
package name + SHA-256 fingerprints on OIDC apps.
- `/.well-known/apple-app-site-association` and
`/.well-known/assetlinks.json` were not served from application config.

# How the Problems Are Solved

- Add iOS/Android app-link fields on OIDC app create/update (Application
API v2 + Management), with validation.
- Persist and project those fields; query active app-link configs
instance-wide.
- Serve AASA (`webcredentials`) and Digital Asset Links
(`get_login_creds`) from well-known paths, with configurable
`Cache-Control` and fingerprint normalization at serve time.
- Console UI to edit the fields, with links to the well-known endpoints.
- Operator docs for configuration, endpoints, caching, and verification.

# Additional Changes

- Document on API fields that well-known responses may be HTTP-cached
and platform verifiers may delay propagation.
- Runtime config: `WellKnown.AppLinksCacheControlMaxAge` (default `5m`;
`0` → `no-store`).

# Additional Context

- Closes #12497
- Implemented and reviewed as stack:
  - #12531 API contract
  - #12532 storage wiring
  - #12536 well-known endpoints
  - #12537 console
  - #12547 docs

---------

Co-authored-by: Cursor <[email protected]>
This commit is contained in:
Livio Spring
2026-08-12 08:04:27 +02:00
committed by GitHub
co-authored by Cursor
parent 2bd42e8fc4
commit 318bfc36d7
68 changed files with 3227 additions and 467 deletions
+24 -1
View File
@@ -7,6 +7,8 @@ import (
"strings"
"time"
"github.com/muhlemmer/gu"
http_util "github.com/zitadel/zitadel/internal/api/http"
"github.com/zitadel/zitadel/internal/eventstore/v1/models"
)
@@ -49,6 +51,14 @@ type OIDCApp struct {
BackChannelLogoutURI *string
LoginVersion *LoginVersion
LoginBaseURI *string
// IOSTeamID and IOSBundleID are Associated Domains / passkey trust fields.
// Both must be set together, or both empty. Composed as TEAMID.BUNDLEID in AASA.
IOSTeamID *string
IOSBundleID *string
// AndroidPackageName and AndroidSHA256CertFingerprints are Digital Asset Links /
// passkey trust fields. Package name is required when fingerprints are non-empty.
AndroidPackageName *string
AndroidSHA256CertFingerprints []string
State AppState
}
@@ -138,7 +148,7 @@ const (
)
func (a *OIDCApp) IsValid() bool {
if (a.ClockSkew != nil && (*a.ClockSkew > time.Second*5 || *a.ClockSkew < time.Second*0)) || !a.OriginsValid() {
if (a.ClockSkew != nil && (*a.ClockSkew > time.Second*5 || *a.ClockSkew < time.Second*0)) || !a.OriginsValid() || !a.AppLinkConfigValid() {
return false
}
grantTypes := a.getRequiredGrantTypes()
@@ -154,6 +164,19 @@ func (a *OIDCApp) IsValid() bool {
return true
}
// AppLinkConfigValid checks sibling rules for iOS/Android association fields.
// Nil and blank (after trim) are treated the same: both iOS fields must be set or
// both empty; Android package name is required whenever fingerprints are present.
func (a *OIDCApp) AppLinkConfigValid() bool {
teamID := strings.TrimSpace(gu.Value(a.IOSTeamID))
bundleID := strings.TrimSpace(gu.Value(a.IOSBundleID))
if (teamID == "") != (bundleID == "") {
return false
}
packageName := strings.TrimSpace(gu.Value(a.AndroidPackageName))
return len(a.AndroidSHA256CertFingerprints) == 0 || packageName != ""
}
func (a *OIDCApp) OriginsValid() bool {
for _, origin := range a.AdditionalOrigins {
if !http_util.IsOrigin(strings.TrimSpace(origin)) {
+81
View File
@@ -669,3 +669,84 @@ func TestOIDCOriginAllowList(t *testing.T) {
})
}
}
func TestOIDCApp_AppLinkConfigValid(t *testing.T) {
tests := []struct {
name string
app *OIDCApp
want bool
}{
{
name: "empty config",
app: &OIDCApp{},
want: true,
},
{
name: "ios both set",
app: &OIDCApp{
IOSTeamID: gu.Ptr("TEAMID"),
IOSBundleID: gu.Ptr("com.example.app"),
},
want: true,
},
{
name: "ios team only",
app: &OIDCApp{
IOSTeamID: gu.Ptr("TEAMID"),
},
want: false,
},
{
name: "ios bundle only",
app: &OIDCApp{
IOSBundleID: gu.Ptr("com.example.app"),
},
want: false,
},
{
name: "ios both empty strings",
app: &OIDCApp{
IOSTeamID: gu.Ptr(""),
IOSBundleID: gu.Ptr(""),
},
want: true,
},
{
name: "android package only",
app: &OIDCApp{
AndroidPackageName: gu.Ptr("com.example.app"),
},
want: true,
},
{
name: "android package and fingerprints",
app: &OIDCApp{
AndroidPackageName: gu.Ptr("com.example.app"),
AndroidSHA256CertFingerprints: []string{"AA:BB"},
},
want: true,
},
{
name: "android fingerprints without package",
app: &OIDCApp{
AndroidSHA256CertFingerprints: []string{"AA:BB"},
},
want: false,
},
{
name: "android fingerprints with empty package",
app: &OIDCApp{
AndroidPackageName: gu.Ptr(" "),
AndroidSHA256CertFingerprints: []string{"AA:BB"},
},
want: false,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
if got := tt.app.AppLinkConfigValid(); got != tt.want {
t.Errorf("AppLinkConfigValid() = %v, want %v", got, tt.want)
}
})
}
}