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]>
2026-10-30 02:52:16 +00:00 · 2026-08-12 08:04:27 +02:00
parent 2bd42e8fc4
commit 318bfc36d7
68 changed files with 3227 additions and 467 deletions
@@ -15,30 +15,36 @@ func CreateOIDCAppRequestToDomain(name, appID, projectID string, req *applicatio
 	if err != nil {
 		return nil, err
 	}
+	iosTeamID, iosBundleID := iosAppLinkConfigToDomain(req.GetIos())
+	androidPackageName, androidFingerprints := androidAppLinkConfigToDomain(req.GetAndroid())
 	return &domain.OIDCApp{
 		ObjectRoot: models.ObjectRoot{
 			AggregateID: projectID,
 		},
-		AppID:                    appID,
-		AppName:                  name,
-		OIDCVersion:              gu.Ptr(domain.OIDCVersionV1),
-		RedirectUris:             req.GetRedirectUris(),
-		ResponseTypes:            oidcResponseTypesToDomain(req.GetResponseTypes()),
-		GrantTypes:               oidcGrantTypesToDomain(req.GetGrantTypes()),
-		ApplicationType:          gu.Ptr(oidcApplicationTypeToDomain(req.GetApplicationType())),
-		AuthMethodType:           gu.Ptr(oidcAuthMethodTypeToDomain(req.GetAuthMethodType())),
-		PostLogoutRedirectUris:   req.GetPostLogoutRedirectUris(),
-		DevMode:                  &req.DevelopmentMode,
-		AccessTokenType:          gu.Ptr(oidcTokenTypeToDomain(req.GetAccessTokenType())),
-		AccessTokenRoleAssertion: gu.Ptr(req.GetAccessTokenRoleAssertion()),
-		IDTokenRoleAssertion:     gu.Ptr(req.GetIdTokenRoleAssertion()),
-		IDTokenUserinfoAssertion: gu.Ptr(req.GetIdTokenUserinfoAssertion()),
-		ClockSkew:                gu.Ptr(req.GetClockSkew().AsDuration()),
-		AdditionalOrigins:        req.GetAdditionalOrigins(),
-		SkipNativeAppSuccessPage: gu.Ptr(req.GetSkipNativeAppSuccessPage()),
-		BackChannelLogoutURI:     gu.Ptr(req.GetBackChannelLogoutUri()),
-		LoginVersion:             loginVersion,
-		LoginBaseURI:             loginBaseURI,
+		AppID:                         appID,
+		AppName:                       name,
+		OIDCVersion:                   gu.Ptr(domain.OIDCVersionV1),
+		RedirectUris:                  req.GetRedirectUris(),
+		ResponseTypes:                 oidcResponseTypesToDomain(req.GetResponseTypes()),
+		GrantTypes:                    oidcGrantTypesToDomain(req.GetGrantTypes()),
+		ApplicationType:               gu.Ptr(oidcApplicationTypeToDomain(req.GetApplicationType())),
+		AuthMethodType:                gu.Ptr(oidcAuthMethodTypeToDomain(req.GetAuthMethodType())),
+		PostLogoutRedirectUris:        req.GetPostLogoutRedirectUris(),
+		DevMode:                       &req.DevelopmentMode,
+		AccessTokenType:               gu.Ptr(oidcTokenTypeToDomain(req.GetAccessTokenType())),
+		AccessTokenRoleAssertion:      gu.Ptr(req.GetAccessTokenRoleAssertion()),
+		IDTokenRoleAssertion:          gu.Ptr(req.GetIdTokenRoleAssertion()),
+		IDTokenUserinfoAssertion:      gu.Ptr(req.GetIdTokenUserinfoAssertion()),
+		ClockSkew:                     gu.Ptr(req.GetClockSkew().AsDuration()),
+		AdditionalOrigins:             req.GetAdditionalOrigins(),
+		SkipNativeAppSuccessPage:      gu.Ptr(req.GetSkipNativeAppSuccessPage()),
+		BackChannelLogoutURI:          gu.Ptr(req.GetBackChannelLogoutUri()),
+		LoginVersion:                  loginVersion,
+		LoginBaseURI:                  loginBaseURI,
+		IOSTeamID:                     iosTeamID,
+		IOSBundleID:                   iosBundleID,
+		AndroidPackageName:            androidPackageName,
+		AndroidSHA256CertFingerprints: androidFingerprints,
 	}, nil
 }

@@ -47,28 +53,35 @@ func UpdateOIDCAppConfigRequestToDomain(appID, projectID string, app *applicatio
 	if err != nil {
 		return nil, err
 	}
+	// nested messages: omit = no change; present (incl. empty) = set/clear
+	iosTeamID, iosBundleID := iosAppLinkConfigToDomain(app.Ios)
+	androidPackageName, androidFingerprints := androidAppLinkConfigToDomain(app.Android)
 	return &domain.OIDCApp{
 		ObjectRoot: models.ObjectRoot{
 			AggregateID: projectID,
 		},
-		AppID:                    appID,
-		RedirectUris:             app.RedirectUris,
-		ResponseTypes:            oidcResponseTypesToDomain(app.ResponseTypes),
-		GrantTypes:               oidcGrantTypesToDomain(app.GrantTypes),
-		ApplicationType:          oidcApplicationTypeToDomainPtr(app.ApplicationType),
-		AuthMethodType:           oidcAuthMethodTypeToDomainPtr(app.AuthMethodType),
-		PostLogoutRedirectUris:   app.PostLogoutRedirectUris,
-		DevMode:                  app.DevelopmentMode,
-		AccessTokenType:          oidcTokenTypeToDomainPtr(app.AccessTokenType),
-		AccessTokenRoleAssertion: app.AccessTokenRoleAssertion,
-		IDTokenRoleAssertion:     app.IdTokenRoleAssertion,
-		IDTokenUserinfoAssertion: app.IdTokenUserinfoAssertion,
-		ClockSkew:                gu.Ptr(app.GetClockSkew().AsDuration()),
-		AdditionalOrigins:        app.AdditionalOrigins,
-		SkipNativeAppSuccessPage: app.SkipNativeAppSuccessPage,
-		BackChannelLogoutURI:     app.BackChannelLogoutUri,
-		LoginVersion:             loginVersion,
-		LoginBaseURI:             loginBaseURI,
+		AppID:                         appID,
+		RedirectUris:                  app.RedirectUris,
+		ResponseTypes:                 oidcResponseTypesToDomain(app.ResponseTypes),
+		GrantTypes:                    oidcGrantTypesToDomain(app.GrantTypes),
+		ApplicationType:               oidcApplicationTypeToDomainPtr(app.ApplicationType),
+		AuthMethodType:                oidcAuthMethodTypeToDomainPtr(app.AuthMethodType),
+		PostLogoutRedirectUris:        app.PostLogoutRedirectUris,
+		DevMode:                       app.DevelopmentMode,
+		AccessTokenType:               oidcTokenTypeToDomainPtr(app.AccessTokenType),
+		AccessTokenRoleAssertion:      app.AccessTokenRoleAssertion,
+		IDTokenRoleAssertion:          app.IdTokenRoleAssertion,
+		IDTokenUserinfoAssertion:      app.IdTokenUserinfoAssertion,
+		ClockSkew:                     gu.Ptr(app.GetClockSkew().AsDuration()),
+		AdditionalOrigins:             app.AdditionalOrigins,
+		SkipNativeAppSuccessPage:      app.SkipNativeAppSuccessPage,
+		BackChannelLogoutURI:          app.BackChannelLogoutUri,
+		LoginVersion:                  loginVersion,
+		LoginBaseURI:                  loginBaseURI,
+		IOSTeamID:                     iosTeamID,
+		IOSBundleID:                   iosBundleID,
+		AndroidPackageName:            androidPackageName,
+		AndroidSHA256CertFingerprints: androidFingerprints,
 	}, nil
 }

@@ -213,10 +226,50 @@ func appOIDCConfigToPb(oidcApp *query.OIDCApp) *application.Application_OidcConf
 			SkipNativeAppSuccessPage: oidcApp.SkipNativeAppSuccessPage,
 			BackChannelLogoutUri:     oidcApp.BackChannelLogoutURI,
 			LoginVersion:             loginVersionToPb(oidcApp.LoginVersion, oidcApp.LoginBaseURI),
+			Ios:                      iosAppLinkConfigToPb(oidcApp.IOSTeamID, oidcApp.IOSBundleID),
+			Android:                  androidAppLinkConfigToPb(oidcApp.AndroidPackageName, oidcApp.AndroidSHA256CertFingerprints),
 		},
 	}
 }

+func iosAppLinkConfigToDomain(cfg *application.IOSAppLinkConfig) (teamID, bundleID *string) {
+	if cfg == nil {
+		return nil, nil
+	}
+	return gu.Ptr(cfg.GetTeamId()), gu.Ptr(cfg.GetBundleId())
+}
+
+func androidAppLinkConfigToDomain(cfg *application.AndroidAppLinkConfig) (packageName *string, fingerprints []string) {
+	if cfg == nil {
+		return nil, nil
+	}
+	fps := cfg.GetSha256CertFingerprints()
+	if fps == nil {
+		fps = []string{}
+	}
+	return gu.Ptr(cfg.GetPackageName()), fps
+}
+
+func iosAppLinkConfigToPb(teamID, bundleID string) *application.IOSAppLinkConfig {
+	if teamID == "" && bundleID == "" {
+		return nil
+	}
+	return &application.IOSAppLinkConfig{
+		TeamId:   teamID,
+		BundleId: bundleID,
+	}
+}
+
+func androidAppLinkConfigToPb(packageName string, fingerprints []string) *application.AndroidAppLinkConfig {
+	if packageName == "" && len(fingerprints) == 0 {
+		return nil
+	}
+	return &application.AndroidAppLinkConfig{
+		PackageName:            packageName,
+		Sha256CertFingerprints: fingerprints,
+	}
+}
+
 func oidcResponseTypesFromModel(responseTypes []domain.OIDCResponseType) []application.OIDCResponseType {
 	oidcResponseTypes := make([]application.OIDCResponseType, len(responseTypes))
 	for i, responseType := range responseTypes {
@@ -66,29 +66,41 @@ func TestCreateOIDCAppRequestToDomain(t *testing.T) {
 				LoginVersion: &application.LoginVersion{Version: &application.LoginVersion_LoginV2{LoginV2: &application.LoginV2{
 					BaseUri: gu.Ptr("https://login"),
 				}}},
+				Ios: &application.IOSAppLinkConfig{
+					TeamId:   "TEAMID",
+					BundleId: "com.example.app",
+				},
+				Android: &application.AndroidAppLinkConfig{
+					PackageName:            "com.example.app",
+					Sha256CertFingerprints: []string{"AA:BB:CC"},
+				},
 			},
 			expectedModel: &domain.OIDCApp{
-				ObjectRoot:               models.ObjectRoot{AggregateID: "project1"},
-				AppName:                  "all fields set",
-				AppID:                    "app1",
-				OIDCVersion:              gu.Ptr(domain.OIDCVersionV1),
-				RedirectUris:             []string{"https://redirect"},
-				ResponseTypes:            []domain.OIDCResponseType{domain.OIDCResponseTypeCode},
-				GrantTypes:               []domain.OIDCGrantType{domain.OIDCGrantTypeAuthorizationCode},
-				ApplicationType:          gu.Ptr(domain.OIDCApplicationTypeWeb),
-				AuthMethodType:           gu.Ptr(domain.OIDCAuthMethodTypeBasic),
-				PostLogoutRedirectUris:   []string{"https://logout"},
-				DevMode:                  gu.Ptr(true),
-				AccessTokenType:          gu.Ptr(domain.OIDCTokenTypeBearer),
-				AccessTokenRoleAssertion: gu.Ptr(true),
-				IDTokenRoleAssertion:     gu.Ptr(true),
-				IDTokenUserinfoAssertion: gu.Ptr(true),
-				ClockSkew:                gu.Ptr(5 * time.Second),
-				AdditionalOrigins:        []string{"https://origin"},
-				SkipNativeAppSuccessPage: gu.Ptr(true),
-				BackChannelLogoutURI:     gu.Ptr("https://backchannel"),
-				LoginVersion:             gu.Ptr(domain.LoginVersion2),
-				LoginBaseURI:             gu.Ptr("https://login"),
+				ObjectRoot:                    models.ObjectRoot{AggregateID: "project1"},
+				AppName:                       "all fields set",
+				AppID:                         "app1",
+				OIDCVersion:                   gu.Ptr(domain.OIDCVersionV1),
+				RedirectUris:                  []string{"https://redirect"},
+				ResponseTypes:                 []domain.OIDCResponseType{domain.OIDCResponseTypeCode},
+				GrantTypes:                    []domain.OIDCGrantType{domain.OIDCGrantTypeAuthorizationCode},
+				ApplicationType:               gu.Ptr(domain.OIDCApplicationTypeWeb),
+				AuthMethodType:                gu.Ptr(domain.OIDCAuthMethodTypeBasic),
+				PostLogoutRedirectUris:        []string{"https://logout"},
+				DevMode:                       gu.Ptr(true),
+				AccessTokenType:               gu.Ptr(domain.OIDCTokenTypeBearer),
+				AccessTokenRoleAssertion:      gu.Ptr(true),
+				IDTokenRoleAssertion:          gu.Ptr(true),
+				IDTokenUserinfoAssertion:      gu.Ptr(true),
+				ClockSkew:                     gu.Ptr(5 * time.Second),
+				AdditionalOrigins:             []string{"https://origin"},
+				SkipNativeAppSuccessPage:      gu.Ptr(true),
+				BackChannelLogoutURI:          gu.Ptr("https://backchannel"),
+				LoginVersion:                  gu.Ptr(domain.LoginVersion2),
+				LoginBaseURI:                  gu.Ptr("https://login"),
+				IOSTeamID:                     gu.Ptr("TEAMID"),
+				IOSBundleID:                   gu.Ptr("com.example.app"),
+				AndroidPackageName:            gu.Ptr("com.example.app"),
+				AndroidSHA256CertFingerprints: []string{"AA:BB:CC"},
 			},
 		},
 	}
@@ -182,6 +194,71 @@ func TestUpdateOIDCAppConfigRequestToDomain(t *testing.T) {
 				LoginBaseURI:             gu.Ptr("https://login"),
 			},
 		},
+		{
+			testName:  "omit app links leaves nil",
+			appID:     "app1",
+			projectID: "proj1",
+			req:       &application.UpdateOIDCApplicationConfigurationRequest{},
+			expectedModel: &domain.OIDCApp{
+				ObjectRoot:    models.ObjectRoot{AggregateID: "proj1"},
+				AppID:         "app1",
+				ResponseTypes: []domain.OIDCResponseType{domain.OIDCResponseTypeCode},
+				GrantTypes:    []domain.OIDCGrantType{domain.OIDCGrantTypeAuthorizationCode},
+				ClockSkew:     gu.Ptr(time.Duration(0)),
+				LoginVersion:  gu.Ptr(domain.LoginVersionUnspecified),
+				LoginBaseURI:  gu.Ptr(""),
+			},
+		},
+		{
+			testName:  "set app links",
+			appID:     "app1",
+			projectID: "proj1",
+			req: &application.UpdateOIDCApplicationConfigurationRequest{
+				Ios: &application.IOSAppLinkConfig{
+					TeamId:   "TEAMID",
+					BundleId: "com.example.app",
+				},
+				Android: &application.AndroidAppLinkConfig{
+					PackageName:            "com.example.app",
+					Sha256CertFingerprints: []string{"AA:BB:CC"},
+				},
+			},
+			expectedModel: &domain.OIDCApp{
+				ObjectRoot:                    models.ObjectRoot{AggregateID: "proj1"},
+				AppID:                         "app1",
+				ResponseTypes:                 []domain.OIDCResponseType{domain.OIDCResponseTypeCode},
+				GrantTypes:                    []domain.OIDCGrantType{domain.OIDCGrantTypeAuthorizationCode},
+				ClockSkew:                     gu.Ptr(time.Duration(0)),
+				LoginVersion:                  gu.Ptr(domain.LoginVersionUnspecified),
+				LoginBaseURI:                  gu.Ptr(""),
+				IOSTeamID:                     gu.Ptr("TEAMID"),
+				IOSBundleID:                   gu.Ptr("com.example.app"),
+				AndroidPackageName:            gu.Ptr("com.example.app"),
+				AndroidSHA256CertFingerprints: []string{"AA:BB:CC"},
+			},
+		},
+		{
+			testName:  "clear app links with empty messages",
+			appID:     "app1",
+			projectID: "proj1",
+			req: &application.UpdateOIDCApplicationConfigurationRequest{
+				Ios:     &application.IOSAppLinkConfig{},
+				Android: &application.AndroidAppLinkConfig{},
+			},
+			expectedModel: &domain.OIDCApp{
+				ObjectRoot:                    models.ObjectRoot{AggregateID: "proj1"},
+				AppID:                         "app1",
+				ResponseTypes:                 []domain.OIDCResponseType{domain.OIDCResponseTypeCode},
+				GrantTypes:                    []domain.OIDCGrantType{domain.OIDCGrantTypeAuthorizationCode},
+				ClockSkew:                     gu.Ptr(time.Duration(0)),
+				LoginVersion:                  gu.Ptr(domain.LoginVersionUnspecified),
+				LoginBaseURI:                  gu.Ptr(""),
+				IOSTeamID:                     gu.Ptr(""),
+				IOSBundleID:                   gu.Ptr(""),
+				AndroidPackageName:            gu.Ptr(""),
+				AndroidSHA256CertFingerprints: []string{},
+			},
+		},
 	}

 	for _, tc := range tt {
@@ -453,26 +530,30 @@ func TestAppOIDCConfigToPb(t *testing.T) {
 		{
 			name: "full config",
 			input: &query.OIDCApp{
-				RedirectURIs:             []string{"https://example.com/callback"},
-				ResponseTypes:            []domain.OIDCResponseType{domain.OIDCResponseTypeCode},
-				GrantTypes:               []domain.OIDCGrantType{domain.OIDCGrantTypeAuthorizationCode},
-				AppType:                  domain.OIDCApplicationTypeWeb,
-				ClientID:                 "client123",
-				AuthMethodType:           domain.OIDCAuthMethodTypeBasic,
-				PostLogoutRedirectURIs:   []string{"https://example.com/logout"},
-				ComplianceProblems:       []string{"problem1", "problem2"},
-				IsDevMode:                true,
-				AccessTokenType:          domain.OIDCTokenTypeBearer,
-				AssertAccessTokenRole:    true,
-				AssertIDTokenRole:        true,
-				AssertIDTokenUserinfo:    true,
-				ClockSkew:                5 * time.Second,
-				AdditionalOrigins:        []string{"https://app.example.com"},
-				AllowedOrigins:           []string{"https://allowed.example.com"},
-				SkipNativeAppSuccessPage: true,
-				BackChannelLogoutURI:     "https://example.com/backchannel",
-				LoginVersion:             domain.LoginVersion2,
-				LoginBaseURI:             gu.Ptr("https://login.example.com"),
+				RedirectURIs:                  []string{"https://example.com/callback"},
+				ResponseTypes:                 []domain.OIDCResponseType{domain.OIDCResponseTypeCode},
+				GrantTypes:                    []domain.OIDCGrantType{domain.OIDCGrantTypeAuthorizationCode},
+				AppType:                       domain.OIDCApplicationTypeWeb,
+				ClientID:                      "client123",
+				AuthMethodType:                domain.OIDCAuthMethodTypeBasic,
+				PostLogoutRedirectURIs:        []string{"https://example.com/logout"},
+				ComplianceProblems:            []string{"problem1", "problem2"},
+				IsDevMode:                     true,
+				AccessTokenType:               domain.OIDCTokenTypeBearer,
+				AssertAccessTokenRole:         true,
+				AssertIDTokenRole:             true,
+				AssertIDTokenUserinfo:         true,
+				ClockSkew:                     5 * time.Second,
+				AdditionalOrigins:             []string{"https://app.example.com"},
+				AllowedOrigins:                []string{"https://allowed.example.com"},
+				SkipNativeAppSuccessPage:      true,
+				BackChannelLogoutURI:          "https://example.com/backchannel",
+				LoginVersion:                  domain.LoginVersion2,
+				LoginBaseURI:                  gu.Ptr("https://login.example.com"),
+				IOSTeamID:                     "TEAMID",
+				IOSBundleID:                   "com.example.app",
+				AndroidPackageName:            "com.example.app",
+				AndroidSHA256CertFingerprints: []string{"AA:BB:CC"},
 			},
 			expected: &application.Application_OidcConfiguration{
 				OidcConfiguration: &application.OIDCConfiguration{
@@ -506,6 +587,14 @@ func TestAppOIDCConfigToPb(t *testing.T) {
 							},
 						},
 					},
+					Ios: &application.IOSAppLinkConfig{
+						TeamId:   "TEAMID",
+						BundleId: "com.example.app",
+					},
+					Android: &application.AndroidAppLinkConfig{
+						PackageName:            "com.example.app",
+						Sha256CertFingerprints: []string{"AA:BB:CC"},
+					},
 				},
 			},
 		},
@@ -0,0 +1,159 @@
+//go:build integration
+
+package app_test
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
+
+	"github.com/zitadel/zitadel/internal/integration"
+	"github.com/zitadel/zitadel/pkg/grpc/application/v2"
+)
+
+func TestOIDCAppLinkConfig(t *testing.T) {
+	p := instance.CreateProject(IAMOwnerCtx, t, instance.DefaultOrg.GetId(), integration.ProjectName(), false, false)
+
+	ios := &application.IOSAppLinkConfig{
+		TeamId:   "ABCDE12345",
+		BundleId: "com.example.app",
+	}
+	android := &application.AndroidAppLinkConfig{
+		PackageName:            "com.example.app",
+		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"},
+	}
+
+	t.Run("create with incomplete ios config is rejected", func(t *testing.T) {
+		_, err := instance.Client.ApplicationV2.CreateApplication(IAMOwnerCtx, &application.CreateApplicationRequest{
+			ProjectId: p.GetId(),
+			Name:      integration.ApplicationName(),
+			ApplicationType: &application.CreateApplicationRequest_OidcConfiguration{
+				OidcConfiguration: baseOIDCCreateRequest(iosOnlyTeamID()),
+			},
+		})
+		require.Equal(t, codes.InvalidArgument, status.Code(err))
+	})
+
+	t.Run("create get update omit and clear round trip", func(t *testing.T) {
+		created, err := instance.Client.ApplicationV2.CreateApplication(IAMOwnerCtx, &application.CreateApplicationRequest{
+			ProjectId: p.GetId(),
+			Name:      integration.ApplicationName(),
+			ApplicationType: &application.CreateApplicationRequest_OidcConfiguration{
+				OidcConfiguration: baseOIDCCreateRequestWithAppLinks(ios, android),
+			},
+		})
+		require.NoError(t, err)
+		require.NotEmpty(t, created.GetApplicationId())
+
+		assertOIDCAppLinks(t, created.GetApplicationId(), ios, android)
+
+		updatedIos := &application.IOSAppLinkConfig{
+			TeamId:   "NEWTEAM123",
+			BundleId: "com.example.app.updated",
+		}
+		updatedAndroid := &application.AndroidAppLinkConfig{
+			PackageName:            "com.example.app.updated",
+			Sha256CertFingerprints: []string{"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:EE:FF:00"},
+		}
+		_, err = instance.Client.ApplicationV2.UpdateApplication(IAMOwnerCtx, &application.UpdateApplicationRequest{
+			ProjectId:     p.GetId(),
+			ApplicationId: created.GetApplicationId(),
+			ApplicationType: &application.UpdateApplicationRequest_OidcConfiguration{
+				OidcConfiguration: &application.UpdateOIDCApplicationConfigurationRequest{
+					Ios:     updatedIos,
+					Android: updatedAndroid,
+				},
+			},
+		})
+		require.NoError(t, err)
+		assertOIDCAppLinks(t, created.GetApplicationId(), updatedIos, updatedAndroid)
+
+		_, err = instance.Client.ApplicationV2.UpdateApplication(IAMOwnerCtx, &application.UpdateApplicationRequest{
+			ProjectId:     p.GetId(),
+			ApplicationId: created.GetApplicationId(),
+			ApplicationType: &application.UpdateApplicationRequest_OidcConfiguration{
+				OidcConfiguration: &application.UpdateOIDCApplicationConfigurationRequest{
+					PostLogoutRedirectUris: []string{"http://example.com/home-omitted"},
+				},
+			},
+		})
+		require.NoError(t, err)
+		assertOIDCAppLinks(t, created.GetApplicationId(), updatedIos, updatedAndroid)
+
+		_, err = instance.Client.ApplicationV2.UpdateApplication(IAMOwnerCtx, &application.UpdateApplicationRequest{
+			ProjectId:     p.GetId(),
+			ApplicationId: created.GetApplicationId(),
+			ApplicationType: &application.UpdateApplicationRequest_OidcConfiguration{
+				OidcConfiguration: &application.UpdateOIDCApplicationConfigurationRequest{
+					Ios:     &application.IOSAppLinkConfig{},
+					Android: &application.AndroidAppLinkConfig{},
+				},
+			},
+		})
+		require.NoError(t, err)
+		assertOIDCAppLinks(t, created.GetApplicationId(), nil, nil)
+	})
+}
+
+func baseOIDCCreateRequest(opts ...func(*application.CreateOIDCApplicationRequest)) *application.CreateOIDCApplicationRequest {
+	req := &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,
+		PostLogoutRedirectUris: []string{"http://example.com/home"},
+		Version:                application.OIDCVersion_OIDC_VERSION_1_0,
+		AccessTokenType:        application.OIDCTokenType_OIDC_TOKEN_TYPE_BEARER,
+	}
+	for _, opt := range opts {
+		opt(req)
+	}
+	return req
+}
+
+func baseOIDCCreateRequestWithAppLinks(ios *application.IOSAppLinkConfig, android *application.AndroidAppLinkConfig) *application.CreateOIDCApplicationRequest {
+	return baseOIDCCreateRequest(func(req *application.CreateOIDCApplicationRequest) {
+		req.Ios = ios
+		req.Android = android
+	})
+}
+
+func iosOnlyTeamID() func(*application.CreateOIDCApplicationRequest) {
+	return func(req *application.CreateOIDCApplicationRequest) {
+		req.Ios = &application.IOSAppLinkConfig{TeamId: "ABCDE12345"}
+	}
+}
+
+func assertOIDCAppLinks(t *testing.T, appID string, wantIOS *application.IOSAppLinkConfig, wantAndroid *application.AndroidAppLinkConfig) {
+	t.Helper()
+	retryDuration, tick := integration.WaitForAndTickWithMaxDuration(IAMOwnerCtx, time.Minute)
+	require.EventuallyWithT(t, func(ct *assert.CollectT) {
+		res, err := instance.Client.ApplicationV2.GetApplication(IAMOwnerCtx, &application.GetApplicationRequest{
+			ApplicationId: appID,
+		})
+		require.NoError(ct, err)
+		cfg := res.GetApplication().GetOidcConfiguration()
+		require.NotNil(ct, cfg)
+
+		if wantIOS == nil {
+			assert.Nil(ct, cfg.GetIos())
+		} else {
+			require.NotNil(ct, cfg.GetIos())
+			assert.Equal(ct, wantIOS.GetTeamId(), cfg.GetIos().GetTeamId())
+			assert.Equal(ct, wantIOS.GetBundleId(), cfg.GetIos().GetBundleId())
+		}
+
+		if wantAndroid == nil {
+			assert.Nil(ct, cfg.GetAndroid())
+		} else {
+			require.NotNil(ct, cfg.GetAndroid())
+			assert.Equal(ct, wantAndroid.GetPackageName(), cfg.GetAndroid().GetPackageName())
+			assert.Equal(ct, wantAndroid.GetSha256CertFingerprints(), cfg.GetAndroid().GetSha256CertFingerprints())
+		}
+	}, retryDuration, tick)
+}
@@ -47,29 +47,35 @@ func AddOIDCAppRequestToDomain(req *mgmt_pb.AddOIDCAppRequest) (*domain.OIDCApp,
 	if err != nil {
 		return nil, err
 	}
+	iosTeamID, iosBundleID := app_grpc.IOSAppLinkConfigToDomain(req.GetIos())
+	androidPackageName, androidFingerprints := app_grpc.AndroidAppLinkConfigToDomain(req.GetAndroid())
 	return &domain.OIDCApp{
 		ObjectRoot: models.ObjectRoot{
 			AggregateID: req.ProjectId,
 		},
-		AppName:                  req.Name,
-		OIDCVersion:              gu.Ptr(app_grpc.OIDCVersionToDomain(req.Version)),
-		RedirectUris:             req.RedirectUris,
-		ResponseTypes:            app_grpc.OIDCResponseTypesToDomain(req.ResponseTypes),
-		GrantTypes:               app_grpc.OIDCGrantTypesToDomain(req.GrantTypes),
-		ApplicationType:          gu.Ptr(app_grpc.OIDCApplicationTypeToDomain(req.AppType)),
-		AuthMethodType:           gu.Ptr(app_grpc.OIDCAuthMethodTypeToDomain(req.AuthMethodType)),
-		PostLogoutRedirectUris:   req.PostLogoutRedirectUris,
-		DevMode:                  gu.Ptr(req.GetDevMode()),
-		AccessTokenType:          gu.Ptr(app_grpc.OIDCTokenTypeToDomain(req.AccessTokenType)),
-		AccessTokenRoleAssertion: gu.Ptr(req.GetAccessTokenRoleAssertion()),
-		IDTokenRoleAssertion:     gu.Ptr(req.GetIdTokenRoleAssertion()),
-		IDTokenUserinfoAssertion: gu.Ptr(req.GetIdTokenUserinfoAssertion()),
-		ClockSkew:                gu.Ptr(req.GetClockSkew().AsDuration()),
-		AdditionalOrigins:        req.AdditionalOrigins,
-		SkipNativeAppSuccessPage: gu.Ptr(req.GetSkipNativeAppSuccessPage()),
-		BackChannelLogoutURI:     gu.Ptr(req.GetBackChannelLogoutUri()),
-		LoginVersion:             gu.Ptr(loginVersion),
-		LoginBaseURI:             gu.Ptr(loginBaseURI),
+		AppName:                       req.Name,
+		OIDCVersion:                   gu.Ptr(app_grpc.OIDCVersionToDomain(req.Version)),
+		RedirectUris:                  req.RedirectUris,
+		ResponseTypes:                 app_grpc.OIDCResponseTypesToDomain(req.ResponseTypes),
+		GrantTypes:                    app_grpc.OIDCGrantTypesToDomain(req.GrantTypes),
+		ApplicationType:               gu.Ptr(app_grpc.OIDCApplicationTypeToDomain(req.AppType)),
+		AuthMethodType:                gu.Ptr(app_grpc.OIDCAuthMethodTypeToDomain(req.AuthMethodType)),
+		PostLogoutRedirectUris:        req.PostLogoutRedirectUris,
+		DevMode:                       gu.Ptr(req.GetDevMode()),
+		AccessTokenType:               gu.Ptr(app_grpc.OIDCTokenTypeToDomain(req.AccessTokenType)),
+		AccessTokenRoleAssertion:      gu.Ptr(req.GetAccessTokenRoleAssertion()),
+		IDTokenRoleAssertion:          gu.Ptr(req.GetIdTokenRoleAssertion()),
+		IDTokenUserinfoAssertion:      gu.Ptr(req.GetIdTokenUserinfoAssertion()),
+		ClockSkew:                     gu.Ptr(req.GetClockSkew().AsDuration()),
+		AdditionalOrigins:             req.AdditionalOrigins,
+		SkipNativeAppSuccessPage:      gu.Ptr(req.GetSkipNativeAppSuccessPage()),
+		BackChannelLogoutURI:          gu.Ptr(req.GetBackChannelLogoutUri()),
+		LoginVersion:                  gu.Ptr(loginVersion),
+		LoginBaseURI:                  gu.Ptr(loginBaseURI),
+		IOSTeamID:                     iosTeamID,
+		IOSBundleID:                   iosBundleID,
+		AndroidPackageName:            androidPackageName,
+		AndroidSHA256CertFingerprints: androidFingerprints,
 	}, nil
 }

@@ -112,28 +118,35 @@ func UpdateOIDCAppConfigRequestToDomain(app *mgmt_pb.UpdateOIDCAppConfigRequest)
 	if err != nil {
 		return nil, err
 	}
+	// nested messages: omit = no change; present (incl. empty) = set/clear
+	iosTeamID, iosBundleID := app_grpc.IOSAppLinkConfigToDomain(app.Ios)
+	androidPackageName, androidFingerprints := app_grpc.AndroidAppLinkConfigToDomain(app.Android)
 	return &domain.OIDCApp{
 		ObjectRoot: models.ObjectRoot{
 			AggregateID: app.ProjectId,
 		},
-		AppID:                    app.AppId,
-		RedirectUris:             app.RedirectUris,
-		ResponseTypes:            app_grpc.OIDCResponseTypesToDomain(app.ResponseTypes),
-		GrantTypes:               app_grpc.OIDCGrantTypesToDomain(app.GrantTypes),
-		ApplicationType:          gu.Ptr(app_grpc.OIDCApplicationTypeToDomain(app.AppType)),
-		AuthMethodType:           gu.Ptr(app_grpc.OIDCAuthMethodTypeToDomain(app.AuthMethodType)),
-		PostLogoutRedirectUris:   app.PostLogoutRedirectUris,
-		DevMode:                  gu.Ptr(app.GetDevMode()),
-		AccessTokenType:          gu.Ptr(app_grpc.OIDCTokenTypeToDomain(app.AccessTokenType)),
-		AccessTokenRoleAssertion: gu.Ptr(app.GetAccessTokenRoleAssertion()),
-		IDTokenRoleAssertion:     gu.Ptr(app.GetIdTokenRoleAssertion()),
-		IDTokenUserinfoAssertion: gu.Ptr(app.GetIdTokenUserinfoAssertion()),
-		ClockSkew:                gu.Ptr(app.GetClockSkew().AsDuration()),
-		AdditionalOrigins:        app.AdditionalOrigins,
-		SkipNativeAppSuccessPage: gu.Ptr(app.GetSkipNativeAppSuccessPage()),
-		BackChannelLogoutURI:     gu.Ptr(app.GetBackChannelLogoutUri()),
-		LoginVersion:             gu.Ptr(loginVersion),
-		LoginBaseURI:             gu.Ptr(loginBaseURI),
+		AppID:                         app.AppId,
+		RedirectUris:                  app.RedirectUris,
+		ResponseTypes:                 app_grpc.OIDCResponseTypesToDomain(app.ResponseTypes),
+		GrantTypes:                    app_grpc.OIDCGrantTypesToDomain(app.GrantTypes),
+		ApplicationType:               gu.Ptr(app_grpc.OIDCApplicationTypeToDomain(app.AppType)),
+		AuthMethodType:                gu.Ptr(app_grpc.OIDCAuthMethodTypeToDomain(app.AuthMethodType)),
+		PostLogoutRedirectUris:        app.PostLogoutRedirectUris,
+		DevMode:                       gu.Ptr(app.GetDevMode()),
+		AccessTokenType:               gu.Ptr(app_grpc.OIDCTokenTypeToDomain(app.AccessTokenType)),
+		AccessTokenRoleAssertion:      gu.Ptr(app.GetAccessTokenRoleAssertion()),
+		IDTokenRoleAssertion:          gu.Ptr(app.GetIdTokenRoleAssertion()),
+		IDTokenUserinfoAssertion:      gu.Ptr(app.GetIdTokenUserinfoAssertion()),
+		ClockSkew:                     gu.Ptr(app.GetClockSkew().AsDuration()),
+		AdditionalOrigins:             app.AdditionalOrigins,
+		SkipNativeAppSuccessPage:      gu.Ptr(app.GetSkipNativeAppSuccessPage()),
+		BackChannelLogoutURI:          gu.Ptr(app.GetBackChannelLogoutUri()),
+		LoginVersion:                  gu.Ptr(loginVersion),
+		LoginBaseURI:                  gu.Ptr(loginBaseURI),
+		IOSTeamID:                     iosTeamID,
+		IOSBundleID:                   iosBundleID,
+		AndroidPackageName:            androidPackageName,
+		AndroidSHA256CertFingerprints: androidFingerprints,
 	}, nil
 }

@@ -3,6 +3,7 @@ package project
 import (
 	"net/url"

+	"github.com/muhlemmer/gu"
 	"google.golang.org/protobuf/types/known/durationpb"

 	object_grpc "github.com/zitadel/zitadel/internal/api/grpc/object"
@@ -68,6 +69,8 @@ func AppOIDCConfigToPb(app *query.OIDCApp) *app_pb.App_OidcConfig {
 			SkipNativeAppSuccessPage: app.SkipNativeAppSuccessPage,
 			BackChannelLogoutUri:     app.BackChannelLogoutURI,
 			LoginVersion:             loginVersionToPb(app.LoginVersion, app.LoginBaseURI),
+			Ios:                      iosAppLinkConfigToPb(app.IOSTeamID, app.IOSBundleID),
+			Android:                  androidAppLinkConfigToPb(app.AndroidPackageName, app.AndroidSHA256CertFingerprints),
 		},
 	}
 }
@@ -345,3 +348,41 @@ func LoginVersionToDomain(version *app_pb.LoginVersion) (domain.LoginVersion, st
 		return domain.LoginVersionUnspecified, "", nil
 	}
 }
+
+func IOSAppLinkConfigToDomain(cfg *app_pb.IOSAppLinkConfig) (teamID, bundleID *string) {
+	if cfg == nil {
+		return nil, nil
+	}
+	return gu.Ptr(cfg.GetTeamId()), gu.Ptr(cfg.GetBundleId())
+}
+
+func AndroidAppLinkConfigToDomain(cfg *app_pb.AndroidAppLinkConfig) (packageName *string, fingerprints []string) {
+	if cfg == nil {
+		return nil, nil
+	}
+	fps := cfg.GetSha256CertFingerprints()
+	if fps == nil {
+		fps = []string{}
+	}
+	return gu.Ptr(cfg.GetPackageName()), fps
+}
+
+func iosAppLinkConfigToPb(teamID, bundleID string) *app_pb.IOSAppLinkConfig {
+	if teamID == "" && bundleID == "" {
+		return nil
+	}
+	return &app_pb.IOSAppLinkConfig{
+		TeamId:   teamID,
+		BundleId: bundleID,
+	}
+}
+
+func androidAppLinkConfigToPb(packageName string, fingerprints []string) *app_pb.AndroidAppLinkConfig {
+	if packageName == "" && len(fingerprints) == 0 {
+		return nil
+	}
+	return &app_pb.AndroidAppLinkConfig{
+		PackageName:            packageName,
+		Sha256CertFingerprints: fingerprints,
+	}
+}
@@ -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)
+}
@@ -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)),
+	)
+}
@@ -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())
+		})
+	}
+}