Identity Cloud

Upload an iOS apple-app-site-association file

What is an iOS apple-app-site-association file?

An apple-app-site-association file is a metadata file that creates a secure association between your domain and your iOS apps. This lets you use universal links to open your iOS apps from your website. By convention, it is accessed from your website using the endpoint /.well-known/apple-app-site-association.

For more information on creating and using a apple-app-site-association file, refer to Supporting associated domains.

To help you integrate your iOS apps with Identity Cloud, you can upload an apple-app-site-association file to a tenant environment and access it through a custom domain associated with the environment. You can do this for each custom domain in your set of environments.

As the configuration in your upper environments is immutable, you can only modify the content of an apple-app-site-association file in your development environment configuration. You must then promote any configuration changes to your upper environments.

Ensure you have set up a custom domain for each environment and realm where you need to upload an iOS apple-app-site-association file.

High-level process

The high-level process to configure and promote an apple-app-site-association file is as follows:

  1. In your development environment, use the endpoint naming format /openidm/config/fidc/apple-app-site-association.<custom-domain-fqdn> to set apple-app-site-association content in your configuration with an association to a custom domain; for example, for the custom domain id.mycompany.com, use the endpoint /openidm/config/fidc/apple-app-site-association.id.mycompany.com.

  2. Promote the configuration to the upper environment that’s configured to use the custom domain. For example, if your production environment is configured to use the custom domain, you will need to promote to your staging environment, and then promote again to your production environment.

  3. Access the apple-app-site-association file from your custom domain using the endpoint /.well-known/apple-app-site-association; for example, for the custom domain id.mycompany.com, use the URL https://id.mycompany.com/.well-known/apple-app-site-association.

View an apple-app-site-association file

Use a custom domain to view an apple-app-site-association file. You don’t need to use an access token as the file is publicly accessible.

  1. View the apple-app-site-association file using a GET request:

    Show request 
    $ curl \
--request GET 'https://<custom-domain-fqdn>/.well-known/apple-app-site-association'(1)
    1 Replace <custom-domain-fqdn> with your custom domain; for example, id.mycompany.com.
    Show response 
    {
  "applinks": {
    "details": [
      {
        "appIDs": [
          "XXXXXXXXXX.com.example.AppName"
        ],
        "components": [
          {
            "/": "/reset/*",
            "comment": "Success after reset password journey"
          }
        ]
      }
    ]
  },
  "webcredentials": {
    "apps": [
      "XXXXXXXXXX.com.example.AppName"
    ]
  }
}

Upload or replace an apple-app-site-association file

  1. Refer to the High-level process for configuring and promoting an apple-app-site-association file.

  2. In your development environment:

    1. Get an access token.

    2. Set the apple-app-site-association file contents in your configuration:

      Show request 
      $ curl \
--request PUT 'https://<tenant-env-fqdn>/openidm/config/fidc/apple-app-site-association.<custom-domain-fqdn>' \(1) (2)
--header 'Authorization: Bearer <access-token>' \(3)
--header 'Content-Type: application/json' \
--data-raw '{(4)
  "data": {
    "applinks": {
      "details": [
        {
          "appIDs": [
            "XXXXXXXXXX.com.example.AppName"
          ],
          "components": [
            {
              "/": "/reset/*",
              "comment": "Success after reset password journey"
            }
          ]
        }
      ]
    },
    "webcredentials": {
      "apps": [
        "XXXXXXXXXX.com.example.AppName"
      ]
    }
  }
}'
      1 Replace <tenant-env-fqdn> with the domain of your development environment; for example, openam-mycompany.forgeblocks.com.
      2 Replace <custom-domain-fqdn> with your custom domain; for example, id.mycompany.com.
      3 Replace <access-token> with your access token.
      4 Replace the example apple-app-site-association JSON content with your own JSON content.
      Show response 
      {
  "_id": "fidc/apple-app-site-association.id.mycompany.com",
  "data": {
    "applinks": {
      "details": [
        {
          "appIDs": [
            "XXXXXXXXXX.com.example.AppName"
          ],
          "components": [
            {
              "/": "/reset/*",
              "comment": "Success after reset password journey"
            }
          ]
        }
      ]
    },
    "webcredentials": {
      "apps": [
        "XXXXXXXXXX.com.example.AppName"
      ]
    }
  }
}

    3. (Optional) Repeat the previous step for each additional custom domain that needs the apple-app-site-association file uploading or replacing.

  3. Run a series of promotions to add the development environment configuration to your upper environments. Refer to:

  4. Use your custom domain to view the apple-app-site-association file. If you uploaded or replaced additional apple-app-site-association files, repeat this for each custom domain.

Delete an apple-app-site-association file

  1. Refer to the High-level process for configuring and promoting an apple-app-site-association file.

  2. In your development environment:

    1. Get an access token.

    2. Delete the apple-app-site-association file contents from your configuration:

      Show request 
      curl \
--request DELETE 'https://<tenant-env-fqdn>/openidm/config/fidc/apple-app-site-association.<custom-domain-fqdn>' \(1) (2)
--header 'Authorization: Bearer <access-token>'(3)
      1 Replace <tenant-env-fqdn> with the domain of your development environment, for example openam-mycompany.forgeblocks.com.
      2 Replace <custom-domain-fqdn> with your custom domain, for example id.mycompany.com.
      3 Replace <access-token> with the access token.
      Show response 
      {
  "_id": "fidc/apple-app-site-association.id.mycompany.com",
  "data": {
    "applinks": {
      "details": [
        {
          "appIDs": [
            "XXXXXXXXXX.com.example.AppName"
          ],
          "components": [
            {
              "/": "/reset/*",
              "comment": "Success after reset password journey"
            }
          ]
        }
      ]
    },
    "webcredentials": {
      "apps": [
        "XXXXXXXXXX.com.example.AppName"
      ]
    }
  }
}

    3. (Optional) Repeat the previous step for each additional custom domain that needs the apple-app-site-association file deleting.

  3. Run a series of promotions to add the development environment configuration to your upper environments. Refer to:

  4. Use your custom domain to view the apple-app-site-association file and check that it is empty. If you deleted additional apple-app-site-association files, repeat this for each custom domain.

Copyright © 2010-2024 ForgeRock, all rights reserved.