Integrate with other articles

Author: baanders

articles/digital-twins/TOC.yml

@@ -149,7 +149,7 @@
       items:
       - name: 403 (Forbidden)
         href: troubleshoot-error-403.md
-      - name: 404 (Not found)
+      - name: 404 Sub-Domain not found
         href: troubleshoot-error-404.md
       - name: Azure Digital Twins Explorer authentication
         href: troubleshoot-error-azure-digital-twins-explorer-authentication.md

articles/digital-twins/how-to-authenticate-client.md

@@ -109,6 +109,20 @@ Also, to use authentication in a function, remember to:
 * Use [environment variables](/sandbox/functions-recipes/environment-variables?tabs=csharp) as appropriate
 * Assign permissions to the functions app that enable it to access the Digital Twins APIs. For more information on Azure Functions processes, see [*How-to: Set up an Azure function for processing data*](how-to-create-azure-function.md).
 
+## Authenticate across tenants
+
+Azure Digital Twins is a service that only supports one  [Azure Active Directory (Azure AD) tenant](../active-directory/develop/quickstart-create-new-tenant.md): the main tenant from the subscription where the Azure Digital Twins instance is located.
+
+[!INCLUDE [digital-twins-tenant-limitation](../../includes/digital-twins-tenant-limitation.md)]
+
+If you need to access your Azure Digital Twins instance using a service principal or user account that lives in a different from the instance, you can have each federated identity from another tenant request a **token** from the Azure Digital Twins instance's "home" tenant. 
+
+[!INCLUDE [digital-twins-tenant-solution-1](../../includes/digital-twins-tenant-solution-1.md)]
+
+You can also specify the home tenant in the credential options in your code. 
+
+[!INCLUDE [digital-twins-tenant-solution-2](../../includes/digital-twins-tenant-solution-2.md)]
+
 ## Other credential methods
 
 If the highlighted authentication scenarios above do not cover the needs of your app, you can explore other types of authentication offered in the [**Microsoft identity platform**](../active-directory/develop/v2-overview.md#getting-started). The documentation for this platform covers additional authentication scenarios, organized by application type.

articles/digital-twins/how-to-use-apis-sdks.md

@@ -181,7 +181,7 @@ The following list provides additional detail and general guidelines for using t
 * You can use an HTTP REST-testing tool like Postman to make direct calls to the Azure Digital Twins APIs. For more information about this process, see [*How-to: Make requests with Postman*](how-to-use-postman.md).
 * To use the SDK, instantiate the `DigitalTwinsClient` class. The constructor requires credentials that can be obtained with a variety of authentication methods in the `Azure.Identity` package. For more on `Azure.Identity`, see its [namespace documentation](/dotnet/api/azure.identity). 
 * You may find the `InteractiveBrowserCredential` useful while getting started, but there are several other options, including credentials for [managed identity](/dotnet/api/azure.identity.interactivebrowsercredential), which you will likely use to authenticate [Azure functions set up with MSI](../app-service/overview-managed-identity.md?tabs=dotnet) against Azure Digital Twins. For more about `InteractiveBrowserCredential`, see its [class documentation](/dotnet/api/azure.identity.interactivebrowsercredential).
-* Requests to the Azure Digital Twins APIs require a User or Service Principal that is a part of the same [Azure Active Directory](../active-directory/fundamentals/active-directory-whatis.md) (Azure AD) tenant where the Azure Digital Twins instance resides. To prevent bad actors from scanning URLs to discover where Azure Digital Twins instances live, 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](../active-directory/external-identities/what-is-b2b.md) collaboration.
+* Requests to the Azure Digital Twins APIs require a user or service principal that is a part of the same [Azure Active Directory](../active-directory/fundamentals/active-directory-whatis.md) (Azure AD) tenant where the Azure Digital Twins instance resides. To prevent bad actors from scanning URLs to discover where Azure Digital Twins instances live, 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](../active-directory/external-identities/what-is-b2b.md) collaboration. For information on how to achieve access across multiple tenants, see [*How-to: Write app authentication code*](how-to-authenticate-client.md#authenticate-across-tenants).
 * All service API calls are exposed as member functions on the `DigitalTwinsClient` class.
 * All service functions exist in synchronous and asynchronous versions.
 * All service functions throw an exception for any return status of 400 or above. Make sure you wrap calls into a `try` section, and catch at least `RequestFailedExceptions`. For more about this type of exception, see [here](/dotnet/api/azure.requestfailedexception).

articles/digital-twins/how-to-use-postman.md

@@ -72,6 +72,8 @@ Otherwise, you can open an [Azure Cloud Shell](https://shell.azure.com) window i
     ```
     ---
 
+    >[!NOTE]
+    > If you need to access your Azure Digital Twins instance using a service principal or user account that lives in a different from the instance, you'll need to request a **token** from the Azure Digital Twins instance's "home" tenant. For more information on this process, see [*How-to: Write app authentication code*](how-to-authenticate-client.md#authenticate-across-tenants).
 
 3. Copy the value of `accessToken` in the result, and save it to use in the next section. This is your **token value** that you will provide to Postman to authorize your requests.
 

articles/digital-twins/media/troubleshoot-error-404/defaultazurecredentialoptions.png

@@ -1,46 +1,42 @@
 ---
-title: "Azure Digital Twins request failed with Status: 404 (Not found)"
-description: "Causes and resolutions for 'Service request failed. Status: 404 (Not found)' on Azure Digital Twins."
+title: "Azure Digital Twins request failed with Status: 404 Sub-Domain not found"
+description: "Causes and resolutions for 'Service request failed. Status: 404 Sub-Domain not found' on Azure Digital Twins."
 ms.service: digital-twins
 author: baanders
 ms.author: baanders
 ms.topic: troubleshooting
 ms.date: 4/13/2021
 ---
 
-# Service request failed. Status: 404 (Not found)
+# Service request failed. Status: 404 Sub-Domain not found
 
 This article describes causes and resolution steps for receiving a 404 error from service requests to Azure Digital Twins. 
 
 ## Symptoms
 
-This error may occur when accessing an Azure Digital Twins instance using a principal or user account that lives in a different [Azure Active Directory (Azure AD) tenant](../active-directory/develop/quickstart-create-new-tenant.md) from the instance. The correct [roles](concepts-security.md) seem to be assigned to the identity, but API requests fail with an error status of `404 (Not found)`.
+This error may occur when accessing an Azure Digital Twins instance using a service principal or user account that lives in a different [Azure Active Directory (Azure AD) tenant](../active-directory/develop/quickstart-create-new-tenant.md) from the instance. The correct [roles](concepts-security.md) seem to be assigned to the identity, but API requests fail with an error status of `404 Sub-Domain not found`.
 
 ## Causes
 
 ### Cause #1
 
 While [Azure AD B2B](../active-directory/external-identities/what-is-b2b.md) allows for the mapping of identities from one tenant into a second tenant, other Azure services may not support multiple tenants. Azure Digital Twins is a service that only supports one tenant: the main tenant from the subscription where the Azure Digital Twins instance is located.
 
+[!INCLUDE [digital-twins-tenant-limitation](../../includes/digital-twins-tenant-limitation.md)]
+
 ## Solutions
 
 ### Solution #1
 
-You can mitigate 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:
-
-```azurecli-interactive
-az account get-access-token --tenant <home-tenant-ID> --resource https://digitaltwins.azure.net
-```
+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. 
 
-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 the DefaultAzureCredential should allow the federated identity to access the Azure Digital Twins resource.
+[!INCLUDE [digital-twins-tenant-solution-1](../../includes/digital-twins-tenant-solution-1.md)]
 
 ### Solution #2
 
-If you're using the `DefaultAzureCredential` class in your code, you can specify the home tenant in the `DefaultAzureCredential` options, like with `InteractiveBrowserTenantId` in the following example:
-
-:::image type="content" source="media/troubleshoot-error-404/defaultazurecredentialoptions.png" alt-text="Screenshot of code showing the DefaultAzureCredentialOptions method. The value of InteractiveBrowserTenantId is set to a sample tenant ID value.":::
+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.
 
-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](/dotnet/api/azure.identity.defaultazurecredentialoptions?view=azure-dotnet&preserve-view=true).
+[!INCLUDE [digital-twins-tenant-solution-2](../../includes/digital-twins-tenant-solution-2.md)]
 
 ## Next steps
 

articles/digital-twins/troubleshoot-error-404.md

@@ -0,0 +1,10 @@
+---
+author: baanders
+description: include file describing the cross-tenant limitation with Azure Digital Twins
+ms.service: digital-twins
+ms.topic: include
+ms.date: 4/13/2021
+ms.author: baanders
+---
+
+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 bad actors from scanning URLs to discover where Azure Digital Twins instances live, 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](../articles/digital-twins/concepts-security.md) through [Azure AD B2B](../articles/active-directory/external-identities/what-is-b2b.md) collaboration. 

includes/digital-twins-tenant-limitation.md

@@ -0,0 +1,16 @@
+---
+author: baanders
+description: include file describing a token solution to the cross-tenant limitation with Azure Digital Twins
+ms.service: digital-twins
+ms.topic: include
+ms.date: 4/13/2021
+ms.author: baanders
+---
+
+One way to do this is with the following CLI command:
+
+```azurecli-interactive
+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.

includes/digital-twins-tenant-solution-1.md

@@ -0,0 +1,14 @@
+---
+author: baanders
+description: include file describing a code solution to the cross-tenant limitation with Azure Digital Twins
+ms.service: digital-twins
+ms.topic: include
+ms.date: 4/13/2021
+ms.author: baanders
+---
+
+The following example shows how to set a tenant ID value for `InteractiveBrowserTenantId` in the `DefaultAzureCredential` options:
+
+:::image type="content" source="../articles/digital-twins/media/troubleshoot-error-404/defaultazurecredentialoptions.png" alt-text="Screenshot of code showing the DefaultAzureCredentialOptions method. The value of InteractiveBrowserTenantId is set to a sample tenant ID value.":::
+
+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](/dotnet/api/azure.identity.defaultazurecredentialoptions?view=azure-dotnet&preserve-view=true).