Article

Setting Up an App’s Associated Domains

Share credentials with a website related to your app using associated domains.

Overview

A domain is a website. Often you will want to associate your website with your app because they are often different versions of the same app or are related and want to share data. To associate a website with an app, you will need to have a file on your website and an entitlement in your app.

An associated domain matches a com.apple.developer.associated-domains entitlement in your app with an apple-app-site-association file on your website.

It’s important to establish an association between domains and your app if you want to share credentials or if features in your app are based on your website.

Add the Associated Domains Entitlement

To set up the entitlement in your app, open the project’s Capabilities tab and enable Associated Domains. This step adds the associated domains entitlement to your app as well as the associated domains feature to your app ID. For more information, see Configure associated domains.

To add your domain to the entitlement, click Add (+) at the bottom of the Domains table in order to add a placeholder domain with the webcredentials: prefix. Replace the placeholder with your site’s domain, retaining the prefix.

Screenshot showing how to add the associated domains for your app.

Add the domains with which you want your app to share credentials. To match all subdomains of an associated domain, specify a wildcard with the prefix *. before the beginning of a specific domain (the period is required).

Each domain you specify uses the following format:

<service>:<fully qualified domain>[:port number]

Add the Apple App Site Association File

Next, add the Apple App Site Association file to your website.

Create a file named apple-app-site-association (without an extension). Update the file to contain the JSON representation of a dictionary listing the app identifiers associated with your domain for the webcredentials service.

{
   "webcredentials": {
       "apps": [    "D3KQX62K1A.com.example.DemoApp",
                    "D3KQX62K1A.com.example.DemoAdminApp" ]
    }
}

Use the following format for the app identifiers:

<Team Identifier>.<Bundle Identifier>

Place this file either in your site’s .well-known directory, or directly in its root directory. If you use the .well-known directory, the file’s URL should match the following format:

https://<fully qualified domain>/.well-known/apple-app-site-association

You must host the file using https:// with a valid certificate and without using any redirects.

Validate the Apple App Site Association File

When your app is installed on an iOS device, the system attempts to download and verify the association file from the domains listed in your entitlement. For each domain, iOS appends /apple-app-site-association (or /.well-known/apple-app-site-association) to its name. With this new URL, the system downloads the contents and ensures the file includes the app’s application identifier.

A validation may fail and the association will be denied if:

  • The JSON file is invalid or doesn’t contain the application identifier.

  • The server returns a 300-499 code. This includes redirects.

If the server returns a 500-599 code, the system assumes that the file is temporarily unavailable and tries again. By default, the system retries every three hours, up to eight times.

After an app successfully associates with a domain, it remains associated until the app is deleted from the device. During development, delete your app from your testing device each time you update the association file to immediately see your changes.

If the system successfully verifies the associated domain, Password AutoFill can display credentials from that domain in the QuickType bar. If you want to access and modify the shared web credentials, call the SecAddSharedWebCredential and SecRequestSharedWebCredential functions.

Topics

Entitlements

Associated Domains Entitlement

The associated domains for specific services, such as accessing Safari saved passwords and activity continuation.

See Also

First Steps

About the Password AutoFill Workflow

Learn how Password AutoFill interacts with both iOS and web apps.