Troubleshoot Azure Digital Twins failed service request: Error 404 (Sub-Domain not found)

This article describes causes and resolution steps for receiving a 404 error from service requests to Azure Digital Twins. This information is specific to the Azure Digital Twins service.

Symptoms

This error may occur when accessing an Azure Digital Twins instance using a service principal or user account that belongs to a different Azure Active Directory (Azure AD) tenant from the instance. The correct roles seem to be assigned to the identity, but API requests fail with an error status of 404 Sub-Domain not found.

Causes

Cause #1

Azure Digital Twins requires that all authenticating users belong to the same Azure AD tenant as the Azure Digital Twins instance.

As a result, requests to the Azure Digital Twins APIs require a user or service principal that is a part of the same tenant where the Azure Digital Twins instance resides. To prevent malicious scanning of Azure Digital Twins endpoints, requests with access tokens from outside the originating tenant will be returned a "404 Sub-Domain not found" error message. This error will be returned even if the user or service principal was given an Azure Digital Twins Data Owner or Azure Digital Twins Data Reader role through Azure AD B2B collaboration.

Solutions

Solution #1

You can resolve this issue by having each federated identity from another tenant request a token from the Azure Digital Twins instance's "home" tenant.

One way to do this is with the following CLI command, where <home-tenant-ID> is the ID of the Azure AD tenant that contains the Azure Digital Twins instance:

az account get-access-token --tenant <home-tenant-ID> --resource https://digitaltwins.azure.net

After requesting this, the identity will receive a token issued for the https://digitaltwins.azure.net Azure AD resource, which has a matching tenant ID claim to the Azure Digital Twins instance. Using this token in API requests or with your Azure.Identity code should allow the federated identity to access the Azure Digital Twins resource.

Solution #2

If you're using the DefaultAzureCredential class in your code and you continue encountering this issue after getting a token, you can specify the home tenant in the DefaultAzureCredential options to clarify the tenant even when authentication defaults down to another type.

The following example shows how to set a sample tenant ID value for InteractiveBrowserTenantId in the DefaultAzureCredential options:

public class DefaultAzureCredentialOptionsSample
{
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    private static DefaultAzureCredentialOptions credentialOptions = new DefaultAzureCredentialOptions()
    {
        ExcludeSharedTokenCacheCredential = true,
        ExcludeVisualStudioCodeCredential = true,
        TenantId = "<your-Azure-Active-Directory-tenant-ID"
    };

    private static DefaultAzureCredential credential = new DefaultAzureCredential(credentialOptions);

    DigitalTwinsClient client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
}

There are similar options available to set a tenant for authentication with Visual Studio and Visual Studio Code. For more information on the options available, see the DefaultAzureCredentialOptions documentation.

Next steps

Read more about security and permissions on Azure Digital Twins: