Escritura de código de autenticación de aplicación cliente

Después de configurar una instancia y la autenticación de Azure Digital Twins, puede crear una aplicación cliente para usarla para interactuar con la instancia. Una vez configurado un proyecto cliente de inicio, necesitará escribir código en esa aplicación cliente para autenticarla en la instancia de Azure Digital Twins.

Azure Digital Twins se autentica mediante tokens de seguridad de Microsoft Entra basados en OAUTH 2.0. Para autenticar el SDK, deberá obtener un token de portador con los permisos correctos para Azure Digital Twins y pasarlo junto con las llamadas de API.

En este artículo se describe cómo obtener credenciales mediante la biblioteca de cliente Azure.Identity. Aunque en este artículo se muestran ejemplos de código en C#, como los que escribiría para el SDK de .NET (C#), puede usar una versión de Azure.Identity independientemente del SDK que utilice. (Para obtener más información sobre los SDK disponibles para Azure Digital Twins, vea API y SDK de Azure Digital Twins).

Requisitos previos

En primer lugar, complete los pasos de configuración que se especifican en Configuración de una instancia y autenticación. Esta configuración garantiza que tiene una instancia de Azure Digital Twins y que el usuario tiene permisos de acceso. Después de toda esta configuración, está listo para escribir código de aplicación cliente.

Para continuar, necesita un proyecto de aplicación cliente en el que escribir el código. Si aún no tiene un proyecto de aplicación cliente configurado, cree un proyecto básico en el lenguaje que prefiera para usarlo con este tutorial.

Autenticación con una biblioteca Azure.Identity

Azure.Identity es una biblioteca de cliente que proporciona varios métodos para obtener credenciales que puede usar para obtener un token de portador y autenticarse con el SDK. Aunque en este artículo se proporcionan ejemplos en C# , puede ver Azure.Identity para varios idiomas, incluido...

• .NET (C#)
• Java
• JavaScript
• Python

Tres métodos comunes de obtención de credenciales en Azure.Identity son:

• DefaultAzureCredential proporciona un flujo de autenticación TokenCredential predeterminado para las aplicaciones que se implementarán en Azure y es la opción recomendada para el desarrollo local. También se puede habilitar para probar los otros dos métodos recomendados en este artículo: contiene ManagedIdentityCredential y puede tener acceso a InteractiveBrowserCredential con una variable de configuración.
• ManagedIdentityCredential funciona bien en los casos en los que necesita identidades administradas (MSI) y es un buen candidato para trabajar con Azure Functions e implementar en los servicios de Azure.
• InteractiveBrowserCredential está diseñado para aplicaciones interactivas y se puede usar para crear un cliente de SDK autenticado.

En el resto de este artículo se muestra cómo usar estos métodos con el SDK de .NET (C#).

Agregación de Azure.Identity a un proyecto de .NET

Para configurar su proyecto de .NET de tal modo que se autentique con Azure.Identity, complete los siguientes pasos:

1. Incluya el paquete de SDK Azure.DigitalTwins.Core y el paquete Azure.Identity en el proyecto. En función de las herramientas que elija, puede incluir los paquetes con el administrador de paquetes de Visual Studio o con la herramienta de línea de comandos dotnet.

2. Agregue las siguientes instrucciones using al código del proyecto:

   using Azure.DigitalTwins.Core;
   using Azure.Identity;
   using System;
   

A continuación, agregue código para obtener credenciales mediante uno de los métodos de Azure.Identity. En las siguientes secciones se proporciona más información sobre el uso de cada una de ellas.

Método DefaultAzureCredential

DefaultAzureCredential proporciona un flujo de autenticación TokenCredential predeterminado para las aplicaciones que se implementarán en Azure y es la opción recomendada para el desarrollo local.

Para usar las credenciales predeterminadas de Azure, necesitará la dirección URL de la instancia de Azure Digital Twins (instrucciones para encontrarla).

Este es un ejemplo del código para agregar DefaultAzureCredential al proyecto:

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

    internal void RunSample()
    {
        //...

        DigitalTwinsClient client;
        try
        {
            var credential = new DefaultAzureCredential();
            client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
        }
        catch (Exception e)
        {
            Console.WriteLine($"Authentication or client creation error: {e.Message}");
            Environment.Exit(0);
        }
    }
}

Nota:

Actualmente hay un problema conocido que afecta a la clase contenedora DefaultAzureCredential que puede dar lugar a un error durante la autenticación. Si se produce este problema, puede intentar crear instancias de DefaultAzureCredential con el siguiente parámetro opcional para resolverlo: new DefaultAzureCredential(new DefaultAzureCredentialOptions { ExcludeSharedTokenCacheCredential = true });

Para más información sobre este problema, consulte Problemas conocidos de Azure Digital Twins.

Configuración de credenciales locales de Azure

Con DefaultAzureCredential, el ejemplo buscará las credenciales en el entorno local; por ejemplo, un inicio de sesión de Azure en una DefaultAzureCredential local o en Visual Studio o Visual Studio Code. Por este motivo, debe iniciar sesión en Azure localmente mediante uno de estos mecanismos para configurar las credenciales del ejemplo.

Si usa Visual Studio o Visual Studio Code para ejecutar códigos de ejemplo, asegúrese de que inicia sesión en ese editor con las mismas credenciales de Azure que quiere usar para acceder a la instancia de Azure Digital Twins. Si usa una ventana local de la CLI, ejecute el comando az login para iniciar sesión en la cuenta de Azure. Después de ejecutar el código de ejemplo, debería autenticarse automáticamente.

Método ManagedIdentityCredential

El método ManagedIdentityCredential funciona bien en los casos en los que necesita identidades administradas (MSI), por ejemplo, al autenticarse con Azure Functions.

Esto significa que puede usar ManagedIdentityCredential en el mismo proyecto que DefaultAzureCredential o InteractiveBrowserCredential, para autenticar una parte diferente del proyecto.

Para usar las credenciales predeterminadas de Azure, necesitará la dirección URL de la instancia de Azure Digital Twins (instrucciones para encontrarla). También puede que necesite un registro de aplicación y el Id. de aplicación (cliente).

En una función de Azure, puede usar las credenciales de identidad administrada de la siguiente manera:

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

    internal void RunSample()
    {
        DigitalTwinsClient client;
        try
        {
            // To use the function app's system-assigned identity:
            ManagedIdentityCredential cred = new ManagedIdentityCredential();
            // To use a user-assigned identity for the function app:
            //ManagedIdentityCredential cred = new ManagedIdentityCredential("<uai-client-ID>");

            client = new DigitalTwinsClient(new Uri(adtInstanceUrl), cred);
        }
        catch (Exception e)
        {
            Console.WriteLine($"Authentication or client creation error: {e.Message}");
            Environment.Exit(0);
        }
    }
}

Al crear la credencial, dejar el parámetro vacío como se muestra anteriormente devolverá la credencial de la identidad asignada por el sistema de la aplicación de funciones, si tiene una. Para especificar una identidad asignada por el usuario en su lugar, pase el identificador de cliente de la identidad asignada por el usuario al parámetro .

Método InteractiveBrowserCredential

El método InteractiveBrowserCredential está pensado para aplicaciones interactivas y abrirá un explorador web para la autenticación. Puede utilizar este método en lugar de DefaultAzureCredential en los casos en los que necesite una autenticación interactiva.

Para usar las credenciales interactivas del explorador, necesitará un registro de la aplicación que tenga permisos para las API de Azure Digital Twins. Si desea conocer los pasos para configurar este registro de aplicación, consulte Creación de un registro de aplicaciones con acceso a Azure Digital Twins. Una vez configurado el registro de la aplicación, necesitará...

• el id. de la aplicación (cliente) del registro de la aplicación;
• el id. del directorio (inquilino) del registro de la aplicación;
• la dirección URL de la instancia de Azure Digital Twins

Este es un ejemplo del código para crear un cliente de SDK autenticado mediante InteractiveBrowserCredential.

public class InteractiveBrowserCredentialSample
{
    // Your client / app registration ID
    private const string clientId = "<your-client-ID>";
    // Your tenant / directory ID
    private const string tenantId = "<your-tenant-ID>";
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    internal void RunSample()
    {
        //...

        DigitalTwinsClient client;
        try
        {
            var credential = new InteractiveBrowserCredential(tenantId, clientId);
            client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
        }
        catch (Exception e)
        {
            Console.WriteLine($"Authentication or client creation error: {e.Message}");
            Environment.Exit(0);
        }
    }
}

Nota:

Aunque puede especificar el identificador de cliente, el identificador de inquilino y la dirección URL de la instancia directamente en el código, como se muestra arriba, se recomienda que, en su lugar, el código obtenga estos valores de un archivo de configuración o una variable de entorno.

Autenticación con Azure Functions

Esta sección contiene algunas de las opciones de configuración importantes en el contexto de autenticación con Azure Functions. Primero, conocerá variables de nivel de clase recomendadas y código de autenticación con el que la función podrá acceder a Azure Digital Twins. A continuación, leerá algunos pasos de configuración finales que se deben completar con relación a la función después de publicar su código en Azure.

Escritura de código de aplicación

Al escribir la función de Azure, considere la posibilidad de agregar estas variables y este código a la función:

• Código para leer la URL del servicio Azure Digital Twins como una variable de entorno o un valor de configuración Se recomienda leer la dirección URL del servicio en una configuración de aplicación o variable de entorno, en lugar de codificarla de forma rígida en la función. En una función de Azure, ese código para leer la variable de entorno podría tener el siguiente aspecto:

  private static readonly string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL");
  

  Más adelante, después de publicar la función, creará y establecerá el valor de la variable de entorno para que este código lea. Para obtener instrucciones sobre cómo hacerlo, vaya directamente a Configuración de la aplicación.

• Una variable estática para contener una instancia de HttpClient. HttpClient es relativamente caro de crear, por lo que es probable que le interese crearlo una vez con el código de autenticación, con el fin de evitar hacerlo para cada invocación de función.

  private static readonly HttpClient singletonHttpClientInstance = new HttpClient();
  

• Credencial de identidad administrada. Cree una credencial de identidad administrada para que la use la función con el fin de acceder a Azure Digital Twins.

  // To use the function app's system-assigned identity:
  var cred = new ManagedIdentityCredential();
  // To use a user-assigned identity for the function app:
  //var cred = new ManagedIdentityCredential("<uai-client-ID>");
  

  Si deja el parámetro vacío, como se muestra anteriormente, devolverá la credencial de la identidad asignada por el sistema de la aplicación de funciones, si tiene una. Para especificar una identidad asignada por el usuario en su lugar, pase el identificador de cliente de la identidad asignada por el usuario al parámetro .

  Más adelante, después de publicar la función, se asegurará de que la identidad de la función tenga permiso para acceder a API de Azure Digital Twins. Para obtener instrucciones sobre cómo hacerlo, vaya directamente a Asignación de un rol de acceso.

• Variable local DigitalTwinsClient. Agregue una variable dentro de la función para que contenga la instancia del cliente de Azure Digital Twins. No haga que esta variable sea estática dentro de la clase.

  var client = new DigitalTwinsClient(
      new Uri(adtInstanceUrl),
      cred,
      new DigitalTwinsClientOptions
      {
          Transport = new HttpClientTransport(singletonHttpClientInstance)
      });
  

• Comprobación nula de adtInstanceUrl. Agregue una comprobación de NULL y, a continuación, encapsule la lógica de la función en un bloque try/catch para detectar cualquier excepción.

Una vez agregadas estas variables a una función, el código de la función podría ser parecido al siguiente ejemplo.

// Default URL for triggering event grid function in the local environment.
// http://localhost:7071/runtime/webhooks/EventGrid?functionName={functionname}
//<Function_dependencies>
using Azure.Core.Pipeline;
using Azure.DigitalTwins.Core;
using Azure.Identity;
using Azure.Messaging.EventGrid;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Extensions.Logging;
using System;
using System.Net.Http;
//</Function_dependencies>

namespace DigitalTwins_Samples
{
    public class DigitalTwinsIngestFunctionSample
    {
        // Your Digital Twin URL is stored in an application setting in Azure Functions
        // <ADT_service_URL>
        private static readonly string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL");
        // </ADT_service_URL>
        // <HTTP_client>
        private static readonly HttpClient singletonHttpClientInstance = new HttpClient();
        // </HTTP_client>

        [FunctionName("TwinsFunction")]
        public void Run([EventGridTrigger] EventGridEvent eventGridEvent, ILogger log)
        {
            log.LogInformation(eventGridEvent.Data.ToString());
            if (adtInstanceUrl == null) log.LogError("Application setting \"ADT_SERVICE_URL\" not set");
            try
            {
                // Authenticate with Digital Twins
                // <ManagedIdentityCredential>
                // To use the function app's system-assigned identity:
                var cred = new ManagedIdentityCredential();
                // To use a user-assigned identity for the function app:
                //var cred = new ManagedIdentityCredential("<uai-client-ID>");
                // </ManagedIdentityCredential>
                // <DigitalTwinsClient>
                var client = new DigitalTwinsClient(
                    new Uri(adtInstanceUrl),
                    cred,
                    new DigitalTwinsClientOptions
                    {
                        Transport = new HttpClientTransport(singletonHttpClientInstance)
                    });
                // </DigitalTwinsClient>
                log.LogInformation($"ADT service client connection created.");

                // Add your business logic here.
            }
            catch (Exception e)
            {
                log.LogError(e.Message);
            }
        }
    }
}

Cuando haya terminado con el código de función, lo cual incluye agregar autenticación y la lógica de la función, publique la aplicación en Azure.

Configuración de la aplicación publicada

Por último, complete los siguientes pasos de configuración con relación a una función de Azure publicada, para asegurarse de que esta pueda acceder a su instancia de Azure Digital Twins.

Ejecute los comandos siguientes en Azure Cloud Shell o en una interfaz de la línea de comandos (CLI) local de Azure.

Nota:

Esta sección la debe completar un usuario de Azure que tenga permisos para administrar el acceso de los usuarios a los recursos de Azure, lo cual abarca la concesión y delegación de permisos. Los roles comunes que cumplen este requisito son propietario, administrador de cuentas o la combinación de administrador de acceso de usuarios y colaborador. Para obtener más información sobre los requisitos de permisos para los roles de Azure Digital Twins, vea Configuración de una instancia y autenticación.

Asignación de un rol de acceso

La función de Azure requiere que se le pase un token de portador. Para asegurarse de que el token de portador se haya pasado, conceda a la aplicación de funciones el rol de propietario de datos de Azure Digital Twins para la instancia de Azure Digital Twins, lo que dará permiso a la aplicación de funciones para realizar actividades del plano de datos en la instancia.

1. Use el comando siguiente a fin de crear una identidad administrada por el sistema para la función (si la función ya tiene una, este comando imprimirá sus detalles). Tome nota del principalId campo en la salida. Este identificador se usará para hacer referencia a la función de forma que pueda concederle permisos en el paso siguiente.

   az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
   

2. Use el valor principalId en el comando siguiente para asignar a la función el rol de propietario de datos de Azure Digital Twins en la instancia de Azure Digital Twins.

   az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"
   

Configuración de la aplicación

A continuación, establezca una variable de entorno para que la dirección URL de la instancia de Azure Digital Twins sea accesible para la función.

Sugerencia

Para crear la dirección URL de la instancia de Azure Digital Twins, agregue https:// al principio del nombre de host de la instancia. Para ver el nombre de host, junto con todas las propiedades de la instancia, ejecute az dt show --dt-name <your-Azure-Digital-Twins-instance>.

El comando siguiente establece una variable de entorno para la dirección URL de la instancia que la función usará siempre que necesite acceder a la instancia.

az functionapp config appsettings set --resource-group <your-resource-group> --name <your-function-app-name> --settings "ADT_SERVICE_URL=https://<your-Azure-Digital-Twins-instance-host-name>"

Autenticación entre inquilinos

Azure Digital Twins es un servicio que solo admite un inquilino de Microsoft Entra: el inquilino principal de la suscripción donde se encuentra la instancia de Azure Digital Twins.

Como resultado, las solicitudes a las API de Azure Digital Twins requieren un usuario o una entidad de servicio que forme parte del mismo inquilino donde reside la instancia de Azure Digital Twins. Para evitar exámenes malintencionados de los puntos de conexión de Azure Digital Twins, las solicitudes con tokens de acceso desde fuera del inquilino de origen recibirán un mensaje de error "404 No se ha encontrado el subdominio". Este error se devolverá incluso si el usuario o la entidad de servicio recibió un rol propietario de datos de Azure Digital Twins o lector de datos de Azure Digital Twins a través de la colaboración B2B de Microsoft Entra.

Si necesita acceder a la instancia de Azure Digital Twins mediante una entidad de servicio o una cuenta de usuario que pertenezca a un inquilino distinto de la instancia, puede hacer que cada identidad federada de otro inquilino solicite un token del inquilino "principal" de la instancia de Azure Digital Twins.

Una manera de hacerlo es con el siguiente comando de la CLI, donde <home-tenant-ID> es el identificador del inquilino de Microsoft Entra que contiene la instancia de Azure Digital Twins:

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

Después de solicitarlo, la identidad recibirá un token emitido para el https://digitaltwins.azure.net recurso de Microsoft Entra, que tiene una notificación de identificador de inquilino coincidente a la instancia de Azure Digital Twins. El uso de este token en las solicitudes de API o con el código Azure.Identity, permitirá que la identidad federada acceda al recurso de Azure Digital Twins.

También puede especificar el inquilino principal en las opciones de credenciales en el código.

En el ejemplo siguiente se muestra cómo establecer un valor de identificador de inquilino de ejemplo para InteractiveBrowserTenantId en las opciones de DefaultAzureCredential:

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);
}

Hay opciones similares disponibles para establecer un inquilino para la autenticación con Visual Studio y Visual Studio Code. Para obtener más información sobre las opciones disponibles, consulte la documentación de DefaultAzureCredentialOptions.

Otros métodos de credenciales

Si los escenarios de autenticación resaltados anteriores no cubren las necesidades de la aplicación, puede explorar otros tipos de autenticación que se ofrecen en la plataforma de Microsoft Identity. La documentación de esta plataforma abarca más escenarios de autenticación organizados por tipo de aplicación.

Pasos siguientes

Obtenga más información sobre cómo funciona la seguridad en Azure Digital Twins:

• Seguridad para soluciones de Azure Digital Twins

O bien, ahora que la autenticación está configurada, continúe con la creación y administración de modelos en la instancia:

• Administración de modelos DTDL