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

Okta Integrator Free Plan org (opens new window)
A custom domain
The Associated Domains Customizations feature enabled for your org

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.

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"
      ]
    }
  }

Edit This Page On GitHub

On this page