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

Después de configurar una instancia y autenticación de Azure Digital Twins, puede crear una aplicación cliente para interactuar con la instancia. En este artículo se explica cómo escribir código en esa aplicación cliente para autenticarlo 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, obtenga un token de portador con los permisos adecuados para Azure Digital Twins y páselo junto con las llamadas 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 lo que escribiría para el SDK de .NET (C#), puede usar una versión de Azure.Identity independientemente del SDK que use. Para más información sobre los SDK disponibles para Azure Digital Twins, consulte API y SDK de Azure Digital Twins.

Requisitos previos

En primer lugar, complete los pasos de configuración de 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
• Pitón

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

• DefaultAzureCredential proporciona un flujo de autenticación predeterminado TokenCredential para las aplicaciones que se implementan en Azure. Este método es la opción recomendada para el desarrollo local. También es capaz de probar los otros dos métodos recomendados en este artículo; encapsula ManagedIdentityCredential y puede acceder a InteractiveBrowserCredential con una variable de configuración.
• ManagedIdentityCredential funciona bien en los casos en los que se necesitan identidades administradas (MSI). Este método es un buen candidato para trabajar con Azure Functions e implementar en los servicios de Azure.
• InteractiveBrowserCredential está diseñado para aplicaciones interactivas. Este es un método para crear un cliente del 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 secciones siguientes se proporcionan más detalles sobre el uso de cada método.

Método DefaultAzureCredential

DefaultAzureCredential proporciona un flujo de autenticación predeterminado TokenCredential para las aplicaciones que se implementan en Azure. Este método es la opción recomendada para el desarrollo local.

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

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

Configuración de credenciales locales de Azure

Con DefaultAzureCredential, el ejemplo busca credenciales en el entorno local, como un inicio de sesión de Azure en una CLI de Azure local o en Visual Studio o Visual Studio Code. Por este motivo, debe iniciar sesión en Azure localmente a través de uno de estos mecanismos para configurar las credenciales del ejemplo.

Si usa Visual Studio o Visual Studio Code para ejecutar ejemplos de código, asegúrese de que ha iniciado sesión en ese editor con las mismas credenciales de Azure que desea 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. Una vez que haya iniciado sesión, el ejemplo de código se autentica automáticamente cuando se ejecuta.

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.

Puede usar ManagedIdentityCredential en el mismo proyecto que DefaultAzureCredential o InteractiveBrowserCredential para autenticar una parte diferente del proyecto.

Para usar las credenciales de Azure predeterminadas, necesita la dirección URL de la instancia de Azure Digital Twins (instrucciones para buscar). Es posible que también necesite un registro de aplicación y el identificador de aplicación (cliente) del registro.

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 sin parámetros, como se muestra en el ejemplo anterior, devuelve 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 id para el constructor.

Método InteractiveBrowserCredential

El método InteractiveBrowserCredential está diseñado para aplicaciones interactivas y abre un explorador web para la autenticación. Use este método en lugar de DefaultAzureCredential cuando necesite autenticación interactiva.

Para usar las credenciales del explorador interactivo, necesita un registro de aplicación que tenga permisos para las API de Azure Digital Twins. Para obtener pasos sobre cómo configurar este registro de aplicaciones, consulte Creación de un registro de aplicaciones con el acceso a Azure Digital Twins. Una vez configurado el registro de la aplicación, necesita los siguientes valores:

• el id. de la aplicación (cliente) del registro de la aplicación;
• el id. del directorio (inquilino) del registro de la aplicación;
• 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);
        }
    }
}

Autenticación con Azure Functions

Esta sección contiene opciones de configuración importantes para autenticarse con Azure Functions. Primero, conocerá variables de nivel de clase recomendadas y código de autenticación con el que la función puede 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 desde una variable de entorno o configuración de la aplicación, 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, cree y establezca el valor de la variable de entorno para que este código lo lea. Para obtener instrucciones sobre cómo hacerlo, consulte Configuración de las opciones 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>");
  

  Al crear la credencial sin parámetros, como se muestra en el ejemplo anterior, devuelve 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 id para el constructor.

  Más adelante, después de publicar la función, asegúrese de que la identidad de la función tenga permiso para acceder a las API de Azure Digital Twins. Para obtener instrucciones sobre cómo hacerlo, consulte 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 convierta esta variable en 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.

Después de agregar estas variables a una función, el código de función podría ser similar al ejemplo siguiente.

// 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, incluida la adición de 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 siguientes comandos en Azure Cloud Shell o en una CLI de Azure local.

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 se pasa el token de portador, conceda a la aplicación de funciones el rol Propietario de datos de Azure Digital Twins para la instancia de Azure Digital Twins, que proporciona permiso a la aplicación de funciones para realizar actividades del plano de datos en la instancia.

1. Use el siguiente comando para crear una identidad administrada por el sistema para la función (si la función ya tiene una, este comando imprime sus detalles). Anote el valor del campo principalId de 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 principalId valor del comando siguiente para dar a la función el rol Propietario de datos de Azure Digital Twins para 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.

El comando siguiente establece una variable de entorno para la dirección URL de la instancia que usa la función 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 el escaneo malintencionado de los puntos de conexión de Azure Digital Twins, las solicitudes con tokens de acceso desde fuera de la entidad de origen devuelven un mensaje de error "404 Sub-Domain no encontrado". Este error se devuelve incluso si al usuario o a la entidad de servicio se le ha asignado un rol de Propietario de Datos de Azure Digital Twins o de 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 diferente de la instancia, puede hacer que cada identidad federada de otro inquilino solicite un token desde el inquilino "inicio" 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 esta solicitud, la identidad recibe un token emitido para el recurso https://digitaltwins.azure.net 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 descritos en este artículo no cubren las necesidades de la aplicación, explore otros tipos de autenticación que se ofrecen en la plataforma de identidad de Microsoft. La documentación de esta plataforma abarca más escenarios de autenticación organizados por tipo de aplicación.

Pasos siguientes

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

• 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