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
@@ -0,0 +1,187 @@
//go:build integration
package well_known_test
import (
"context"
"encoding/json"
"io"
"net/http"
"os"
"testing"
"time"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
"github.com/zitadel/zitadel/internal/api/well_known"
"github.com/zitadel/zitadel/internal/integration"
"github.com/zitadel/zitadel/pkg/grpc/application/v2"
)
var (
CTX context.Context
IAMOwnerCtx context.Context
Instance *integration.Instance
)
func TestMain(m *testing.M) {
os.Exit(func() int {
ctx, cancel := context.WithTimeout(context.Background(), 15*time.Minute)
defer cancel()
Instance = integration.NewInstance(ctx)
CTX = ctx
IAMOwnerCtx = Instance.WithAuthorization(ctx, integration.UserTypeIAMOwner)
return m.Run()
}())
}
func TestWellKnownAppLinks(t *testing.T) {
issuer := Instance.OIDCIssuer()
t.Run("empty when no apps configured", func(t *testing.T) {
assertEventuallyJSON(t, issuer+well_known.AppleAppSiteAssociationPath, map[string]any{
"webcredentials": map[string]any{
"apps": []any{},
},
})
assertEventuallyJSON(t, issuer+well_known.AssetLinksPath, []any{})
})
project := Instance.CreateProject(IAMOwnerCtx, t, Instance.DefaultOrg.GetId(), integration.ProjectName(), false, false)
ios1 := &application.IOSAppLinkConfig{TeamId: "TEAMAAAAAA", BundleId: "com.example.one"}
android1 := &application.AndroidAppLinkConfig{
PackageName: "com.example.one",
Sha256CertFingerprints: []string{"11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11"},
}
createOIDCAppWithLinks(t, project.GetId(), ios1, android1)
ios2 := &application.IOSAppLinkConfig{TeamId: "TEAMBBBBBB", BundleId: "com.example.two"}
createOIDCAppWithLinks(t, project.GetId(), ios2, nil)
android2 := &application.AndroidAppLinkConfig{
PackageName: "com.example.two",
Sha256CertFingerprints: []string{"22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22:22"},
}
createOIDCAppWithLinks(t, project.GetId(), nil, android2)
// duplicate iOS app id should be deduped in AASA
createOIDCAppWithLinks(t, project.GetId(), ios1, nil)
assertEventuallyJSONUnorderedApps(t, issuer,
[]string{
"TEAMAAAAAA.com.example.one",
"TEAMBBBBBB.com.example.two",
},
[]any{
map[string]any{
"relation": []any{"delegate_permission/common.get_login_creds"},
"target": map[string]any{
"namespace": "android_app",
"package_name": "com.example.one",
"sha256_cert_fingerprints": []any{android1.Sha256CertFingerprints[0]},
},
},
map[string]any{
"relation": []any{"delegate_permission/common.get_login_creds"},
"target": map[string]any{
"namespace": "android_app",
"package_name": "com.example.two",
"sha256_cert_fingerprints": []any{android2.Sha256CertFingerprints[0]},
},
},
},
)
}
func createOIDCAppWithLinks(t *testing.T, projectID string, ios *application.IOSAppLinkConfig, android *application.AndroidAppLinkConfig) {
t.Helper()
_, err := Instance.Client.ApplicationV2.CreateApplication(IAMOwnerCtx, &application.CreateApplicationRequest{
ProjectId: projectID,
Name: integration.ApplicationName(),
ApplicationType: &application.CreateApplicationRequest_OidcConfiguration{
OidcConfiguration: &application.CreateOIDCApplicationRequest{
RedirectUris: []string{"http://example.com"},
ResponseTypes: []application.OIDCResponseType{application.OIDCResponseType_OIDC_RESPONSE_TYPE_CODE},
GrantTypes: []application.OIDCGrantType{application.OIDCGrantType_OIDC_GRANT_TYPE_AUTHORIZATION_CODE},
ApplicationType: application.OIDCApplicationType_OIDC_APP_TYPE_NATIVE,
AuthMethodType: application.OIDCAuthMethodType_OIDC_AUTH_METHOD_TYPE_NONE,
Version: application.OIDCVersion_OIDC_VERSION_1_0,
AccessTokenType: application.OIDCTokenType_OIDC_TOKEN_TYPE_BEARER,
Ios: ios,
Android: android,
},
},
})
require.NoError(t, err)
}
func assertEventuallyJSON(t *testing.T, url string, want any) {
t.Helper()
retryDuration, tick := integration.WaitForAndTickWithMaxDuration(CTX, time.Minute)
require.EventuallyWithT(t, func(ct *assert.CollectT) {
resp, err := http.Get(url)
if !assert.NoError(ct, err) {
return
}
defer func() {
_, _ = io.Copy(io.Discard, resp.Body)
_ = resp.Body.Close()
}()
if !assert.Equal(ct, http.StatusOK, resp.StatusCode) {
return
}
assert.Contains(ct, resp.Header.Get("Content-Type"), "application/json")
assert.Equal(ct, "public, max-age=300", resp.Header.Get("Cache-Control"))
body, err := io.ReadAll(resp.Body)
if !assert.NoError(ct, err) {
return
}
var got any
if !assert.NoError(ct, json.Unmarshal(body, &got)) {
return
}
assert.Equal(ct, want, got)
}, retryDuration, tick)
}
func assertEventuallyJSONUnorderedApps(t *testing.T, url string, wantApps []string, wantAssetLinks []any) {
t.Helper()
retryDuration, tick := integration.WaitForAndTickWithMaxDuration(CTX, time.Minute)
require.EventuallyWithT(t, func(ct *assert.CollectT) {
aasaResp, err := http.Get(url + well_known.AppleAppSiteAssociationPath)
if !assert.NoError(ct, err) {
return
}
defer aasaResp.Body.Close()
if !assert.Equal(ct, http.StatusOK, aasaResp.StatusCode) {
return
}
var aasa struct {
WebCredentials struct {
Apps []string `json:"apps"`
} `json:"webcredentials"`
}
if !assert.NoError(ct, json.NewDecoder(aasaResp.Body).Decode(&aasa)) {
return
}
assert.ElementsMatch(ct, wantApps, aasa.WebCredentials.Apps)
assetResp, err := http.Get(url + well_known.AssetLinksPath)
if !assert.NoError(ct, err) {
return
}
defer assetResp.Body.Close()
if !assert.Equal(ct, http.StatusOK, assetResp.StatusCode) {
return
}
var got []any
if !assert.NoError(ct, json.NewDecoder(assetResp.Body).Decode(&got)) {
return
}
assert.ElementsMatch(ct, wantAssetLinks, got)
}, retryDuration, tick)
}
+196
View File
@@ -0,0 +1,196 @@
package well_known
import (
"context"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"fmt"
"net/http"
"strings"
"time"
"github.com/zitadel/zitadel/backend/v3/instrumentation/logging"
http_util "github.com/zitadel/zitadel/internal/api/http"
"github.com/zitadel/zitadel/internal/query"
)
const (
AppleAppSiteAssociationPath = "/.well-known/apple-app-site-association"
AssetLinksPath = "/.well-known/assetlinks.json"
)
// HandlerPrefixes are registered with [api.API.RegisterHandlerPrefixes].
var HandlerPrefixes = []string{
AppleAppSiteAssociationPath,
AssetLinksPath,
}
// Config holds runtime options for the well-known handlers.
type Config struct {
// AppLinksCacheControlMaxAge sets the Cache-Control max-age for
// apple-app-site-association and assetlinks.json responses.
// 0 sets Cache-Control: no-store.
AppLinksCacheControlMaxAge time.Duration
}
type appLinkQuerier interface {
SearchOIDCAppLinkConfigs(ctx context.Context) ([]*query.OIDCAppLinkConfig, error)
}
type Handler struct {
queries appLinkQuerier
cacheControlMaxAge time.Duration
}
func NewHandler(queries appLinkQuerier, config Config) *Handler {
return &Handler{
queries: queries,
cacheControlMaxAge: config.AppLinksCacheControlMaxAge,
}
}
func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
switch r.URL.Path {
case AppleAppSiteAssociationPath:
h.serveAppleAppSiteAssociation(w, r)
case AssetLinksPath:
h.serveAssetLinks(w, r)
default:
http.NotFound(w, r)
}
}
type appleAppSiteAssociation struct {
WebCredentials appleWebCredentials `json:"webcredentials"`
}
type appleWebCredentials struct {
Apps []string `json:"apps"`
}
type assetLink struct {
Relation []string `json:"relation"`
Target assetLinkTarget `json:"target"`
}
type assetLinkTarget struct {
Namespace string `json:"namespace"`
PackageName string `json:"package_name"`
SHA256CertFingerprints []string `json:"sha256_cert_fingerprints"`
}
func (h *Handler) serveAppleAppSiteAssociation(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodGet && r.Method != http.MethodHead {
http.Error(w, http.StatusText(http.StatusMethodNotAllowed), http.StatusMethodNotAllowed)
return
}
configs, err := h.queries.SearchOIDCAppLinkConfigs(r.Context())
if err != nil {
logging.Error(r.Context(), "unable to query OIDC app link configs for apple-app-site-association", "err", err)
http.Error(w, http.StatusText(http.StatusInternalServerError), http.StatusInternalServerError)
return
}
h.writeJSON(w, r, buildAppleAppSiteAssociation(configs))
}
func (h *Handler) serveAssetLinks(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodGet && r.Method != http.MethodHead {
http.Error(w, http.StatusText(http.StatusMethodNotAllowed), http.StatusMethodNotAllowed)
return
}
configs, err := h.queries.SearchOIDCAppLinkConfigs(r.Context())
if err != nil {
logging.Error(r.Context(), "unable to query OIDC app link configs for assetlinks.json", "err", err)
http.Error(w, http.StatusText(http.StatusInternalServerError), http.StatusInternalServerError)
return
}
h.writeJSON(w, r, buildAssetLinks(r.Context(), configs))
}
func buildAppleAppSiteAssociation(configs []*query.OIDCAppLinkConfig) appleAppSiteAssociation {
apps := make([]string, 0)
seen := make(map[string]struct{})
for _, cfg := range configs {
if cfg.IOSTeamID == "" || cfg.IOSBundleID == "" {
continue
}
appID := cfg.IOSTeamID + "." + cfg.IOSBundleID
if _, ok := seen[appID]; ok {
continue
}
seen[appID] = struct{}{}
apps = append(apps, appID)
}
return appleAppSiteAssociation{
WebCredentials: appleWebCredentials{Apps: apps},
}
}
func buildAssetLinks(ctx context.Context, configs []*query.OIDCAppLinkConfig) []assetLink {
links := make([]assetLink, 0)
for _, cfg := range configs {
if cfg.AndroidPackageName == "" || len(cfg.AndroidSHA256CertFingerprints) == 0 {
continue
}
links = append(links, assetLink{
Relation: []string{"delegate_permission/common.get_login_creds"},
Target: assetLinkTarget{
Namespace: "android_app",
PackageName: cfg.AndroidPackageName,
SHA256CertFingerprints: normalizeSHA256Fingerprints(ctx, cfg.AndroidSHA256CertFingerprints),
},
})
}
return links
}
// normalizeSHA256Fingerprints returns colon-separated uppercase hex fingerprints
// for assetlinks.json. Normalization is applied at serve time only so stored /
// client state can keep the format clients sent.
func normalizeSHA256Fingerprints(ctx context.Context, fps []string) []string {
out := make([]string, len(fps))
for i, fp := range fps {
out[i] = normalizeSHA256Fingerprint(ctx, fp)
}
return out
}
func normalizeSHA256Fingerprint(ctx context.Context, fp string) string {
if strings.Contains(fp, ":") {
return strings.ToUpper(fp) // already 32 valid pairs per API validation; only case may vary
}
raw, err := hex.DecodeString(fp) // guaranteed 64 hex chars
if err != nil || len(raw) != sha256.Size {
logging.Warn(ctx, "stored android sha256 fingerprint is not canonical hex; serving as-is",
"fingerprint", fp, "err", err)
return strings.ToUpper(fp)
}
parts := make([]string, len(raw))
for i, b := range raw {
parts[i] = fmt.Sprintf("%02X", b)
}
return strings.Join(parts, ":")
}
func (h *Handler) writeJSON(w http.ResponseWriter, r *http.Request, v any) {
w.Header().Set("Content-Type", "application/json")
h.setCacheControl(w)
w.WriteHeader(http.StatusOK)
if r.Method == http.MethodHead {
return
}
if err := json.NewEncoder(w).Encode(v); err != nil {
logging.Error(r.Context(), "unable to encode well-known response", "err", err)
}
}
func (h *Handler) setCacheControl(w http.ResponseWriter) {
if h.cacheControlMaxAge <= 0 {
w.Header().Set(http_util.CacheControl, "no-store")
return
}
w.Header().Set(http_util.CacheControl,
fmt.Sprintf("public, max-age=%d", int(h.cacheControlMaxAge/time.Second)),
)
}
+241
View File
@@ -0,0 +1,241 @@
package well_known
import (
"context"
"net/http"
"net/http/httptest"
"testing"
"time"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
http_util "github.com/zitadel/zitadel/internal/api/http"
"github.com/zitadel/zitadel/internal/query"
)
func TestBuildAppleAppSiteAssociation(t *testing.T) {
t.Parallel()
tt := []struct {
name string
configs []*query.OIDCAppLinkConfig
wantApps []string
}{
{
name: "empty",
configs: nil,
wantApps: []string{},
},
{
name: "skips incomplete ios",
configs: []*query.OIDCAppLinkConfig{
{IOSTeamID: "TEAM"},
{IOSBundleID: "com.example"},
},
wantApps: []string{},
},
{
name: "aggregates and dedupes",
configs: []*query.OIDCAppLinkConfig{
{IOSTeamID: "TEAM1", IOSBundleID: "com.one"},
{IOSTeamID: "TEAM2", IOSBundleID: "com.two"},
{IOSTeamID: "TEAM1", IOSBundleID: "com.one"},
{AndroidPackageName: "com.android", AndroidSHA256CertFingerprints: []string{"AA"}},
},
wantApps: []string{"TEAM1.com.one", "TEAM2.com.two"},
},
}
for _, tc := range tt {
t.Run(tc.name, func(t *testing.T) {
t.Parallel()
got := buildAppleAppSiteAssociation(tc.configs)
assert.Equal(t, tc.wantApps, got.WebCredentials.Apps)
})
}
}
func TestBuildAssetLinks(t *testing.T) {
t.Parallel()
tt := []struct {
name string
configs []*query.OIDCAppLinkConfig
want []assetLink
}{
{
name: "empty",
configs: nil,
want: []assetLink{},
},
{
name: "skips incomplete android",
configs: []*query.OIDCAppLinkConfig{
{AndroidPackageName: "com.example"},
{AndroidSHA256CertFingerprints: []string{"AA"}},
},
want: []assetLink{},
},
{
name: "aggregates and normalizes fingerprints",
configs: []*query.OIDCAppLinkConfig{
{
IOSTeamID: "TEAM",
IOSBundleID: "com.ios",
AndroidPackageName: "com.one",
AndroidSHA256CertFingerprints: []string{"aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899"},
},
{
AndroidPackageName: "com.two",
AndroidSHA256CertFingerprints: []string{
"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:aa:bb",
"eeff00112233445566778899aabbccddeeff00112233445566778899aabbccdd",
},
},
},
want: []assetLink{
{
Relation: []string{"delegate_permission/common.get_login_creds"},
Target: assetLinkTarget{
Namespace: "android_app",
PackageName: "com.one",
SHA256CertFingerprints: []string{
"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",
},
},
},
{
Relation: []string{"delegate_permission/common.get_login_creds"},
Target: assetLinkTarget{
Namespace: "android_app",
PackageName: "com.two",
SHA256CertFingerprints: []string{
"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:AA:BB",
"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:AA:BB:CC:DD",
},
},
},
},
},
}
for _, tc := range tt {
t.Run(tc.name, func(t *testing.T) {
t.Parallel()
assert.Equal(t, tc.want, buildAssetLinks(t.Context(), tc.configs))
})
}
}
func TestNormalizeSHA256Fingerprint(t *testing.T) {
t.Parallel()
tt := []struct {
name string
in string
want string
}{
{
name: "already canonical",
in: "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",
want: "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",
},
{
name: "lowercase with colons",
in: "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",
want: "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",
},
{
name: "lowercase without separators",
in: "aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899",
want: "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",
},
{
name: "invalid continuous hex uppercased",
in: "aabb",
want: "AABB",
},
{
name: "colon form uppercased without reparse",
in: "aa:bb",
want: "AA:BB",
},
}
for _, tc := range tt {
t.Run(tc.name, func(t *testing.T) {
t.Parallel()
assert.Equal(t, tc.want, normalizeSHA256Fingerprint(t.Context(), tc.in))
})
}
}
type stubAppLinkQuerier struct {
configs []*query.OIDCAppLinkConfig
err error
}
func (s stubAppLinkQuerier) SearchOIDCAppLinkConfigs(_ context.Context) ([]*query.OIDCAppLinkConfig, error) {
return s.configs, s.err
}
func TestHandlerCacheControl(t *testing.T) {
t.Parallel()
tt := []struct {
name string
maxAge time.Duration
wantHeader string
}{
{
name: "default max-age",
maxAge: 5 * time.Minute,
wantHeader: "public, max-age=300",
},
{
name: "no-store when zero",
maxAge: 0,
wantHeader: "no-store",
},
{
name: "no-store when negative",
maxAge: -time.Minute,
wantHeader: "no-store",
},
}
for _, tc := range tt {
t.Run(tc.name, func(t *testing.T) {
t.Parallel()
h := NewHandler(stubAppLinkQuerier{}, Config{AppLinksCacheControlMaxAge: tc.maxAge})
for _, path := range []string{AppleAppSiteAssociationPath, AssetLinksPath} {
req := httptest.NewRequest(http.MethodGet, path, nil)
rec := httptest.NewRecorder()
h.ServeHTTP(rec, req)
require.Equal(t, http.StatusOK, rec.Code)
assert.Equal(t, tc.wantHeader, rec.Header().Get(http_util.CacheControl), path)
assert.NotContains(t, rec.Header().Get(http_util.CacheControl), "stale-while-revalidate")
}
})
}
}
func TestHandlerHeadOmitsBody(t *testing.T) {
t.Parallel()
h := NewHandler(stubAppLinkQuerier{}, Config{AppLinksCacheControlMaxAge: 5 * time.Minute})
for _, path := range []string{AppleAppSiteAssociationPath, AssetLinksPath} {
t.Run(path, func(t *testing.T) {
t.Parallel()
req := httptest.NewRequest(http.MethodHead, path, nil)
rec := httptest.NewRecorder()
h.ServeHTTP(rec, req)
require.Equal(t, http.StatusOK, rec.Code)
assert.Equal(t, "application/json", rec.Header().Get("Content-Type"))
assert.Equal(t, "public, max-age=300", rec.Header().Get(http_util.CacheControl))
assert.Empty(t, rec.Body.Bytes())
})
}
}