Skip to content

how-to-authenticate-client.md

Latest commit

 

History

History
168 lines (95 loc) · 13.4 KB

how-to-authenticate-client.md

File metadata and controls

168 lines (95 loc) · 13.4 KB
title Write app authentication code
titleSuffix Azure Digital Twins
description Learn how to write authentication code in a client application
author baanders
ms.author baanders
ms.date 02/24/2025
ms.topic how-to
ms.service azure-digital-twins

Write client app authentication code

After you set up an Azure Digital Twins instance and authentication, you can create a client application to interact with the instance. This article explains how to write code in that client app to authenticate it against the Azure Digital Twins instance.

Azure Digital Twins authenticates using Microsoft Entra Security Tokens based on OAUTH 2.0. To authenticate your SDK, get a bearer token with the right permissions to Azure Digital Twins, and pass it along with your API calls.

This article describes how to obtain credentials using the Azure.Identity client library. While this article shows code examples in C#, such as what you'd write for the .NET (C#) SDK, you can use a version of Azure.Identity regardless of what SDK you're using. For more information on the SDKs available for Azure Digital Twins, see Azure Digital Twins APIs and SDKs.

Prerequisites

First, complete the setup steps in Set up an instance and authentication. This setup ensures that you have an Azure Digital Twins instance and your user has access permissions. After that setup, you're ready to write client app code.

To continue, you need a client app project in which you write your code. If you don't already have a client app project set up, create a basic project in your language of choice to use with this tutorial.

Authenticate using Azure.Identity library

Azure.Identity is a client library that provides several credential-obtaining methods that you can use to get a bearer token and authenticate with your SDK. Although this article gives examples in C#, you can view Azure.Identity for several languages, including...

Three common credential-obtaining methods in Azure.Identity are:

  • DefaultAzureCredential provides a default TokenCredential authentication flow for applications that are deployed to Azure. This method is the recommended choice for local development. It's also capable of trying the other two methods recommended in this article; it wraps ManagedIdentityCredential and can access InteractiveBrowserCredential with a configuration variable.
  • ManagedIdentityCredential works well in cases where you need managed identities (MSI). This method is a good candidate for working with Azure Functions and deploying to Azure services.
  • InteractiveBrowserCredential is intended for interactive applications. This is one method of creating an authenticated SDK client.

The rest of this article shows how to use these methods with the .NET (C#) SDK.

Add Azure.Identity to your .NET project

To set up your .NET project to authenticate with Azure.Identity, complete the following steps:

  1. Include the SDK package Azure.DigitalTwins.Core and the Azure.Identity package in your project. Depending on your tools of choice, you can include the packages using the Visual Studio package manager or the dotnet command-line tool.

  2. Add the following using statements to your project code:

    :::code language="csharp" source="~/digital-twins-docs-samples/sdks/csharp/authentication.cs" id="Azure_Digital_Twins_dependencies":::

Next, add code to obtain credentials using one of the methods in Azure.Identity. The following sections give more detail about using each method.

DefaultAzureCredential method

DefaultAzureCredential provides a default TokenCredential authentication flow for applications that are deployed to Azure. This method is the recommended choice for local development.

To use the default Azure credentials, you need the Azure Digital Twins instance's URL (instructions to find).

Here's a code sample to add a DefaultAzureCredential to your project:

:::code language="csharp" source="~/digital-twins-docs-samples/sdks/csharp/authentication.cs" id="DefaultAzureCredential_full":::

[!INCLUDE Azure Digital Twins: DefaultAzureCredential known issue note]

Set up local Azure credentials

[!INCLUDE Azure Digital Twins: local credentials prereq (inner)]

ManagedIdentityCredential method

The ManagedIdentityCredential method works well in cases where you need managed identities (MSI)—for example, when authenticating with Azure Functions.

You can use ManagedIdentityCredential in the same project as DefaultAzureCredential or InteractiveBrowserCredential to authenticate a different part of the project.

To use the default Azure credentials, you need the Azure Digital Twins instance's URL (instructions to find). You might also need an app registration and the registration's Application (client) ID.

In an Azure function, you can use the managed identity credentials like this:

:::code language="csharp" source="~/digital-twins-docs-samples/sdks/csharp/authentication.cs" id="ManagedIdentityCredential":::

When you create the credential without parameters, as shown in the previous example, it returns the credential for the function app's system-assigned identity, if it has one. To specify a user-assigned identity instead, pass the user-assigned identity's client ID into the id parameter for the constructor.

InteractiveBrowserCredential method

The InteractiveBrowserCredential method is intended for interactive applications and brings up a web browser for authentication. Use this method instead of DefaultAzureCredential when you require interactive authentication.

To use the interactive browser credentials, you need an app registration that has permissions to the Azure Digital Twins APIs. For steps on how to set up this app registration, see Create an app registration with Azure Digital Twins access. Once the app registration is set up, you need the following values:

Here's an example of the code to create an authenticated SDK client using InteractiveBrowserCredential.

:::code language="csharp" source="~/digital-twins-docs-samples/sdks/csharp/authentication.cs" id="InteractiveBrowserCredential":::

Note

Although the example above places the client ID, tenant ID, and instance URL directly into the code, it's a good idea to get these values from a configuration file or environment variable instead.

Authenticate Azure Functions

This section contains important configuration choices for authenticating with Azure Functions. First, you read about recommended class-level variables and authentication code that allow the function to access Azure Digital Twins. Then, you read about some final configuration steps to complete for your function after its code is published to Azure.

Write application code

When writing the Azure function, consider adding these variables and code to your function:

  • Code to read the Azure Digital Twins service URL as an environment variable or configuration setting. It's a good practice to read the service URL from an application setting/environment variable, rather than hard-coding it in the function. In an Azure function, that code to read the environment variable might look like this:

    :::code language="csharp" source="~/digital-twins-docs-samples/sdks/csharp/adtIngestFunctionSample.cs" id="ADT_service_URL":::

    Later, after publishing the function, create and set the value of the environment variable for this code to read. For instructions on how to do so, see Configure application settings.

  • A static variable to hold an HttpClient instance. HttpClient is relatively expensive to create, so you probably want to create it once with the authentication code to avoid creating it for every function invocation.

    :::code language="csharp" source="~/digital-twins-docs-samples/sdks/csharp/adtIngestFunctionSample.cs" id="HTTP_client":::

  • Managed identity credential. Create a managed identity credential that your function uses to access Azure Digital Twins.

    :::code language="csharp" source="~/digital-twins-docs-samples/sdks/csharp/adtIngestFunctionSample.cs" id="ManagedIdentityCredential":::

    When you create the credential without parameters, as shown in the previous example, it returns the credential for the function app's system-assigned identity, if it has one. To specify a user-assigned identity instead, pass the user-assigned identity's client ID into the id parameter for the constructor.

    Later, after publishing the function, ensure that the function's identity has permission to access the Azure Digital Twins APIs. For instructions on how to do so, see Assign an access role.

  • A local variable DigitalTwinsClient. Add the variable inside your function to hold your Azure Digital Twins client instance. Don't make this variable static inside your class. :::code language="csharp" source="~/digital-twins-docs-samples/sdks/csharp/adtIngestFunctionSample.cs" id="DigitalTwinsClient":::

  • A null check for adtInstanceUrl. To catch any exceptions, add the null check and then wrap your function logic in a try/catch block.

After you add these variables to a function, your function code might look like the following example.

:::code language="csharp" source="~/digital-twins-docs-samples/sdks/csharp/adtIngestFunctionSample.cs":::

When you're finished with your function code, including adding authentication and the function's logic, publish the app to Azure.

Configure published app

Finally, complete the following configuration steps for a published Azure function to make sure it can access your Azure Digital Twins instance.

[!INCLUDE digital-twins-configure-function-app-cli.md]

Authenticate across tenants

Azure Digital Twins is a service that only supports one Microsoft Entra tenant: the main tenant from the subscription where the Azure Digital Twins instance is located.

[!INCLUDE digital-twins-tenant-limitation]

If you need to access your Azure Digital Twins instance using a service principal or user account that belongs to a different tenant 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]

You can also specify the home tenant in the credential options in your code.

[!INCLUDE digital-twins-tenant-solution-2]

Other credential methods

If the highlighted authentication scenarios described in this article don't cover the needs of your app, explore other types of authentication offered in the Microsoft identity platform. The documentation for this platform covers more authentication scenarios, organized by application type.

Next steps

To learn more about how security works in Azure Digital Twins, see:

Or, now that authentication is set up, move on to creating and managing models in your instance: