Customize associated domains

This guide explains how to create associations between your custom domains and three well-known URI endpoints.

Learning outcomes

Learn how to create well-known URI files.

What you need

About associated domains

Associated domains create a secure link between your custom domain and native apps.

This guide describes how to configure three important well-known URI endpoints that are used by iOS, Android, and WebAuthn. You can use these endpoints to establish a trusted relationship between your app, authorized referring domains, and the web credentials of users for those domains.

For example, when you host the /.well-known/apple-app-site-association file in your custom domain, you can allow universal links and app links (opens new window).

Three well-known URIs

/.well-known/apple-app-site-association: The iOS well-known URI file that establishes a secure link between a website and a native iOS or macOS app.
/.well-known/assetlinks.json: The Android well-known URI file that establishes a secure link between a website and a native Android app.
/.well-known/webauthn: The WebAuthn well-known URI file that allows you to specify other web origins that are allowed to share and use the same WebAuthn credentials (passkeys).

The iOS and Android well-known URIs have similar functions that enable secure associations between your custom domain and native mobile apps. While you can use the WebAuthn well-known URI to improve the sign-in experience of your users.

Redirect URI support in the Okta Client SDK for Swift

The Okta Client SDK for Swift (opens new window) supports both custom URIs and HTTPS redirect URLs on supporting platforms and versions. The use of an https:// redirect URI is recommended, but this requires that your app is configured to use associated domains. See Apple Developer documentation - Supporting associated domains (opens new window).

Ensure that you complete the following items:

Include the domain of the redirect URI as a webcredential in your app's associated domains capability (opens new window).
Verify that the app identifier (that is, the <TEAM_ID>.<BUNDLE_ID>) is included in the webcredentials list on that domain's /.well-known/apple-app-site-association well-known URI. See Create an apple-app-site-association customization.
Change the redirect_uri value used in your client configuration to the https URL configured within your OAuth2 client configuration.

Note: The use of HTTPS addresses within the redirect callback URI is limited by the availability of support within ASWebAuthenticationSession. The session requires a minimum of iOS v17.4, macOS v14.4, watchOS v10.4, tvOS v17.4, or visionOS v1.1.

Use associated domains in Okta

In your org, you can view, create, and customize these files by using the Associated Domain Customizations API (opens new window) or in the Admin Console (opens new window).

Note: The maximum file size for each well-known URI file is 100 KB.

There are various ways to configure these well-known URIs with your org. Review the following documentation resources to learn more about configuring each well-known URI.

Create an apple-app-site-association customization

Before you create a customization, retrieve your brandId with the List all brands (opens new window) endpoint.

Then, use the Replace the customized well-known URI endpoint (opens new window) to create a custom well-known URI for /.well-known/apple-app-site-association.

Note: You must format the apple-app-site-association well-known URI as a JSON object.

Create your own PUT request.
In the path parameters, use your brandId.
Set apple-app-site-association as the path.
Use the following request body template and enter your own parameters and values.
After you've set your request body parameters, send the PUT /api/v1/brands/{brandId}/well-known-uris/{path}/customized request.

  {
    "representation": {
      "key1": "value1",
      "key2": "value2",
      "key3": {
        "key3.1": "value3.1"
      }
    }
  }

Note: The apple-app-site-association well-known URI file can't include an authsrv parameter. The custom well-known URI content is merged with hardcoded authsrv information that enables Okta Verify.

When creating your own URI file, review this example (opens new window) of an apple-app-site-association URI file.

Create an assetLinks.json customization

Retrieve your brandId with the List all brands (opens new window) endpoint.

Use the Replace the customized well-known URI endpoint (opens new window) to create a custom well-known URI for /.well-known/assetlinks.json.

Note: You must format the assetLinks.json well-known URI as a JSON array.

Create your own PUT request.
In the path parameters, use your brandId.
Set assetlinks.json as the path.
Use the following request body template and enter your own parameters and values.
After you've set your request body parameters, send the PUT /api/v1/brands/{brandId}/well-known-uris/{path}/customized request.

{
  "representation": [
    {
      "key1": "value1",
      "key2": "value2",
      "key3": {
        "key3.1": "value3.1"
      }
    }
  ]
}

When creating your own URI file, review this example (opens new window) of an assetLinks.json URI file.

Create a webauthn customization

Retrieve your brandId with the List all brands (opens new window) endpoint.

Use the Replace the customized well-known URI endpoint (opens new window) to create a custom well-known URI for /.well-known/webauthn.

Note: You must format the webauthn well-known URI as a JSON object and the origins parameter as an array of strings.

Create your own PUT request.
In the path parameters, use your brandId.
Set webauthn as the path.
Use the following request body example.
After you've set your request body parameters, send the PUT /api/v1/brands/{brandId}/well-known-uris/{path}/customized request.

In the following request body example, the well-known URI file declares that the domains listed in the origins parameter are part of a single, trusted entity. The origins parameter contains an array of URLs and it instructs web browsers to allow a single WebAuthn credential, such as a passkey, to be used in the listed domains.

  {
    "representation": {
      "origins": [
        "https://www.example.com",
        "https://store.example.com"
      ]
    }
  }

Review the System Log

After you create associations for your custom domains, you can verify that they're created by referring to the system.well_known_uri.update event type. See Event Types.

The system.well_known_uri.update event type includes the following information about your association.

Your custom brand ID
The path of the well-known URI that you created an association with
The previous content of the well-known URI association and its updated content
The date and time when you created it

Edit This Page On GitHub

On this page