Uso de la autenticación de OAuth con Microsoft Dataverse

OAuth 2.0 es el protocolo estándar del sector para autorización. Después de que los usuarios de aplicaciones proporcionan las credenciales para autenticarse, OAuth determina si están autorizadas para acceder a los recursos.

Las aplicaciones cliente deben admitir el uso de OAuth para acceder a los datos mediante la API web. OAuth habilita la autenticación en dos fases (2FA) o autenticación basada en certificados para escenarios de aplicación entre servidores.

OAuth requiere un proveedor de identidad para la autenticación. Para Dataverse, el proveedor de identidades se Microsoft Entra ID. Para autenticarse mediante una cuenta profesional o educativa de Microsoft, use el Biblioteca de autenticación de Microsoft (MSAL).

Nota:

En este artículo se presentan conceptos comunes relacionados con la conexión a Dataverse mediante OAuth con bibliotecas de autenticación. Este contenido se centra en cómo un desarrollador puede conectarse a Dataverse, pero no cubre el funcionamiento interno de OAuth o las bibliotecas. Para obtener información completa relacionada con la autenticación, consulte la documentación de Microsoft Entra ID. El artículo ¿Qué es la autenticación? es un buen punto de partida.

Los ejemplos que se proporcionan están preconfigurados con los valores de registro adecuados para que pueda ejecutarlos sin generar su propio registro de aplicaciones. Al publicar sus propias aplicaciones, debe usar sus propios valores de registro.

Registro de la aplicación

Al conectarse mediante OAuth, primero debe registrar una aplicación en el inquilino de Microsoft Entra ID. La forma en que registras la aplicación depende del tipo de aplicación que quieras realizar.

En todos los casos, comience con los pasos básicos para registrar una aplicación descrita en el artículo: Inicio rápido: Registro de una aplicación con el Plataforma de identidad de Microsoft. Para obtener instrucciones específicas de Dataverse, consulte Walkthrough: Registro de una aplicación con Microsoft Entra ID.

Las decisiones que debe tomar en este paso dependen principalmente de la opción Tipo de aplicación (consulte la sección siguiente).

Tipos de registro de la aplicación

Al registrar una aplicación con Microsoft Entra ID, elija el tipo de aplicación. Puede registrar dos tipos de aplicaciones:

Tipo de aplicación Descripción
Aplicación web/API Cliente web
Tipo de aplicación cliente que ejecuta todos los códigos en un servidor web.

Cliente basado en usuario-agente
Tipo de aplicación cliente que descarga código desde un servidor web y se ejecuta en un agente de usuario (por ejemplo, explorador web), como una aplicación de una sola página (SPA).
Native Tipo de aplicación cliente que está instalada nativamente en un dispositivo.

Al seleccionar Aplicación web/API, introduzca una URL de inicio de sesión. Microsoft Entra ID envía la respuesta de autenticación a esta dirección URL, incluido un token si la autenticación es correcta. Mientras desarrolla una aplicación, establezca esta dirección URL en https://localhost/appname:[port] para que pueda desarrollar y depurar su aplicación localmente. Al publicar la aplicación, cambie este valor a la dirección URL publicada de la aplicación.

Al seleccionar Nativo, escriba un URI de redirección. Esta dirección URL es un identificador único al que Microsoft Entra ID redirige al agente de usuario en una solicitud de OAuth 2.0. Esta URL suele ser un valor con un formato similar al siguiente: app://<guid>.

Dar acceso a Dataverse

Si su aplicación es un cliente que permite al usuario autenticado realizar operaciones, configure la aplicación para que tenga concedido el permiso delegado Acceder a Dynamics 365 como usuarios de la organización.

Para conocer los pasos específicos para establecer permisos, consulte Registrar una aplicación con Microsoft Entra ID.

Si la aplicación usa la autenticación de servidor a servidor (S2S), no es necesario completar este paso. Esa configuración requiere un usuario del sistema específico y las operaciones realizadas por esa cuenta de usuario en lugar de cualquier usuario que se deba autenticar.

Uso de secretos y certificados de cliente

En escenarios de servidor a servidor, no hay ninguna cuenta de usuario interactiva para autenticarse. En estos casos, debe proporcionar algunos medios de confirmar que la aplicación es de confianza. Confirme la confianza mediante secretos de cliente o certificados.

Para las aplicaciones que registre mediante el tipo de aplicación Aplicación web/API, puede configurar secretos. Configure estos secretos en el área Claves de Acceso a la API, dentro de la Configuración del registro de la aplicación.

Para ambos tipos de aplicación, puede cargar un certificado.

Más información: Conectar como aplicación

Usar bibliotecas de autenticación para conectarse

Use una de las bibliotecas cliente de autenticación Microsoft Entra ID compatibles con Microsoft para conectarse a Dataverse, como el Biblioteca de autenticación de Microsoft (MSAL). Esta biblioteca está disponible para varias plataformas, tal como se describe en los vínculos proporcionados.

Nota:

Biblioteca de autenticación de Microsoft (ADAL) no recibe actualizaciones activamente y solo se admite hasta junio de 2022. Use MSAL como biblioteca de autenticación para proyectos.

Para ver un ejemplo de código que muestra el uso de bibliotecas de MSAL para la autenticación con Dataverse, consulte Inicio rápido: Ejemplo de API web (C#).

bibliotecas cliente de .NET

Dataverse admite la autenticación de aplicaciones con el punto de conexión de API web mediante el protocolo OAuth 2.0. Para las aplicaciones de .NET personalizadas, use MSAL para la autenticación de aplicaciones mediante el punto de conexión de la API web.

El SDK de Dataverse para .NET incluye clases de cliente CrmServiceClient y ServiceClient para controlar la autenticación. La clase CrmServiceClient actualmente usa ADAL para la autenticación, mientras que ServiceClient utiliza MSAL. Escribir el código de su aplicación para usar estos clientes elimina la necesidad de administrar la autenticación directamente. Ambos clientes trabajan con los puntos de conexión SDK y Web API.

Use el AccessToken con sus solicitudes

El objetivo de usar las bibliotecas de autenticación es obtener un token de acceso que pueda incluir con las solicitudes. Obtener el token esto requiere solo unas líneas de código y solo unas cuantas líneas más para configurar un HttpClient para ejecutar una solicitud.

Importante

Como se muestra en el código de ejemplo de este artículo, use un ámbito «<environment-url>/user_impersonation» para un cliente público. Para un cliente confidencial, use un ámbito de «<environment-url>/.default».

Ejemplo sencillo

El ejemplo siguiente es la cantidad mínima de código necesario para ejecutar una única solicitud de API web, pero no es el enfoque recomendado. El código de ejemplo usa la biblioteca MSAL y se toma del ejemplo Inicio rápido: Ejemplo de API web (C#).

string resource = "https://contoso.api.crm.dynamics.com";
var clientId = "51f81489-12ee-4a9e-aaae-a2591f45987d";
var redirectUri = "http://localhost"; // Loopback for the interactive login.

// MSAL authentication
var authBuilder = PublicClientApplicationBuilder.Create(clientId)
    .WithAuthority(AadAuthorityAudience.AzureAdMultipleOrgs)
    .WithRedirectUri(redirectUri)
    .Build();
var scope = resource + "/user_impersonation";
string[] scopes = { scope };

AuthenticationResult token =
    authBuilder.AcquireTokenInteractive(scopes).ExecuteAsync().Result;

// Set up the HTTP client
var client = new HttpClient
{
    BaseAddress = new Uri(resource + "/api/data/v9.2/"),
    Timeout = new TimeSpan(0, 2, 0)  // Standard two minute timeout.
};

HttpRequestHeaders headers = client.DefaultRequestHeaders;
headers.Authorization = new AuthenticationHeaderValue("Bearer", token.AccessToken);
headers.Add("OData-MaxVersion", "4.0");
headers.Add("OData-Version", "4.0");
headers.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json"));

// Web API call
var response = client.GetAsync("WhoAmI").Result;

Este enfoque sencillo no representa un buen patrón que se deba seguir porque el token expira en aproximadamente una hora. Las bibliotecas de MSAL almacenan en caché el token automáticamente y lo actualizan cada vez que se llama al AcquireTokenInteractive método . Sin embargo, en este ejemplo simple, el token solo se adquiere una vez.

Ejemplo que demuestra la delegación de un controlador de mensaje

Implemente una clase derivada de DelegatingHandler y pásela al constructor de HttpClient. Al usar este controlador, puede sobrescribir el método HttpClient.SendAsync para que el token de acceso se actualice mediante las llamadas al método AcquireToken* en cada solicitud enviada por el cliente HTTP.

El código siguiente es un ejemplo de una clase personalizada derivada de DelegatingHandler. Este código se toma del ejemplo de inicio rápido mejorado que usa la biblioteca de autenticación de MSAL.

class OAuthMessageHandler : DelegatingHandler
{
    private AuthenticationHeaderValue authHeader;
    public OAuthMessageHandler(string serviceUrl, string clientId, string redirectUrl, string username, string password,
            HttpMessageHandler innerHandler)
        : base(innerHandler)
    {
        string apiVersion = "9.2";
        string webApiUrl = $"{serviceUrl}/api/data/v{apiVersion}/";
        var authBuilder = PublicClientApplicationBuilder.Create(clientId)
                        .WithAuthority(AadAuthorityAudience.AzureAdMultipleOrgs)
                        .WithRedirectUri(redirectUrl)
                        .Build();
        var scope = serviceUrl + "/user_impersonation";
        string[] scopes = { scope };
        // First try to get an authentication token from the cache using a hint.
        AuthenticationResult authBuilderResult=null;
        try
        {
            authBuilderResult = authBuilder.AcquireTokenSilent(scopes, username)
               .ExecuteAsync().Result;
        }
        catch (Exception ex)
        {
            System.Diagnostics.Debug.WriteLine(
                $"Error acquiring auth token from cache:{System.Environment.NewLine}{ex}");
            // Token cache request failed, so request a new token.
            try
            {
                if (username != string.Empty && password != string.Empty)
                {
                    // Request a token based on username/password credentials.
                    authBuilderResult = authBuilder.AcquireTokenByUsernamePassword(scopes, username, password)
                                .ExecuteAsync().Result;
                }
                else
                {
                    // Prompt the user for credentials and get the token.
                    authBuilderResult = authBuilder.AcquireTokenInteractive(scopes)
                                .ExecuteAsync().Result;
                }
            }
            catch (Exception msalex)
            {
                System.Diagnostics.Debug.WriteLine(
                    $"Error acquiring auth token with user credentials:{System.Environment.NewLine}{msalex}");
                throw;
            }
        }
        //Note that an Microsoft Entra ID access token has finite lifetime, default expiration is 60 minutes.
        authHeader = new AuthenticationHeaderValue("Bearer", authBuilderResult.AccessToken);
    }

    protected override Task<HttpResponseMessage> SendAsync(
              HttpRequestMessage request, System.Threading.CancellationToken cancellationToken)
    {
        request.Headers.Authorization = authHeader;
        return base.SendAsync(request, cancellationToken);
    }
}

Cuando se usa esta OAuthMessageHandler clase, el método simple Main tiene este aspecto.

class Program
{
    static void Main(string[] args)
    {
        try
        {
            //Get configuration data from App.config connectionStrings
            string connectionString = ConfigurationManager.ConnectionStrings["Connect"].ConnectionString;

            using (HttpClient client = SampleHelpers.GetHttpClient(connectionString, SampleHelpers.clientId,
                SampleHelpers.redirectUrl))
            {
                // Use the WhoAmI function
                var response = client.GetAsync("WhoAmI").Result;

                if (response.IsSuccessStatusCode)
                {
                    //Get the response content and parse it.
                    JObject body = JObject.Parse(response.Content.ReadAsStringAsync().Result);
                    Guid userId = (Guid)body["UserId"];
                    Console.WriteLine("Your UserId is {0}", userId);
                }
                else
                {
                    Console.WriteLine("The request failed with a status of '{0}'",
                                response.ReasonPhrase);
                }
                Console.WriteLine("Press any key to exit.");
                Console.ReadLine();
            }
        }
        catch (Exception ex)
        {
            SampleHelpers.DisplayException(ex);
            Console.WriteLine("Press any key to exit.");
            Console.ReadLine();
        }
    }
}

Lea la siguiente información importante sobre el uso de un cadena de conexión o la autenticación de nombre de usuario y contraseña en el código de aplicación.

Importante

Microsoft recomienda usar el flujo de autenticación más seguro disponible. El flujo de autenticación descrito en este artículo requiere un alto grado de confianza en la aplicación y conlleva riesgos que no están presentes en otros flujos. Solo debe usar este flujo cuando otros flujos más seguros, como las identidades administradas, no sean viables.

Mueva los valores de la cadena de configuración a una cadena de conexión del archivo App.config y configure el cliente HTTP en el método GetHttpClient.

public static HttpClient GetHttpClient(string connectionString, string clientId, string redirectUrl, string version = "v9.2")
{
    string url = GetParameterValueFromConnectionString(connectionString, "Url");
    string username = GetParameterValueFromConnectionString(connectionString, "Username");
    string password = GetParameterValueFromConnectionString(connectionString, "Password");
    try
    {
        HttpMessageHandler messageHandler = new OAuthMessageHandler(url, clientId, redirectUrl, username, password,
                        new HttpClientHandler());

        HttpClient httpClient = new HttpClient(messageHandler)
        {
            BaseAddress = new Uri(string.Format("{0}/api/data/{1}/", url, version)),

            Timeout = new TimeSpan(0, 2, 0)  //2 minutes
        };

        return httpClient;
    }
    catch (Exception)
    {
        throw;
    }
}

Ver el ejemplo Inicio rápido mejorado para el código completo.

Aunque en este ejemplo se usa HttpClient.GetAsync en lugar de invalidar SendAsync, el mismo flujo de código se aplica a cualquiera de los métodos HttpClient que envían una solicitud.

Conectar como aplicación

Algunas aplicaciones que cree no están pensadas para que un usuario las ejecute de forma interactiva. Por ejemplo, puede que desee crear una aplicación cliente web que pueda realizar operaciones en datos de Dataverse o una aplicación de consola que realice una tarea programada de algún tipo.

Aunque podría lograr estos escenarios mediante el uso de credenciales para un usuario normal, esa cuenta de usuario necesita una licencia de pago. No use este enfoque.

En estos casos, cree un usuario de aplicación especial enlazado a una aplicación registrada Microsoft Entra ID. A continuación, use un secreto de clave configurado para la aplicación o cargue un certificado X.509 . Otro ventaja de este método es que no consume una licencia de pago.

Requisitos para conectarse como aplicación

Para conectarse como una aplicación, necesita:

  • Una aplicación registrada
  • Un usuario de Dataverse vinculado a la aplicación registrada
  • Conectar usando el secreto de la aplicación o la huella digital del certificado

Registrar la aplicación

Al registrar una aplicación, siga muchos de los mismos pasos descritos en Tutorial: Registro de una aplicación con Microsoft Entra ID, con las siguientes excepciones:

  • No es necesario conceder el permiso de acceso a Dynamics 365 como usuarios de la organización.

    Esta aplicación está enlazada a una cuenta de usuario específica.

  • Debe configurar un secreto para el registro de la aplicación o cargar un certificado de clave pública.

Puede crear o ver credenciales en el registro de su aplicación en Administrar>certificados y secretos.

Para agregar un certificado (clave pública):

  1. En la pestaña Certificados, seleccione Cargar certificado.
  2. Seleccione el archivo que desea cargar. Debe ser uno de los siguientes tipos de archivo: .cer, .pem, .crt.
  3. Proporcione una descripción.
  4. Seleccione Agregar.

Para agregar un secreto de cliente (contraseña de aplicación):

  1. En la pestaña Secretos de cliente, agregue una descripción para su secreto de cliente.
  2. Seleccione un período de tiempo de vencimiento.
  3. Seleccione Agregar.

Importante

Después de guardar los cambios de configuración, se muestra un valor secreto. Asegúrese de copiar el valor del secreto para usarlo en el código de la aplicación cliente, ya que no puede acceder a ese valor una vez que deje la página.

Más información: Agregar credenciales

Una cuenta de usuario de Dataverse vinculado a la aplicación registrada

En primer lugar, cree un rol de seguridad personalizado que defina el acceso y los privilegios que tiene esta cuenta dentro de la organización de Dataverse. Para obtener más información, consulte Creación o configuración de un rol de seguridad personalizado.

Después de crear el rol de seguridad personalizado, cree la cuenta de usuario que la usa.

Cree manualmente un usuario de la aplicación de Dataverse

El procedimiento para crear un usuario de la aplicación se puede encontrar en el artículo Administrar Power Platform: Crear un usuario de aplicación.

Tras crear un usuario de aplicación, asocie el usuario de la aplicación al rol de seguridad personalizado que ha creado.

Conexión mediante el secreto de aplicación

Si se conecta usando un secreto de cliente y usa Microsoft.Xrm.Tooling.Connector.CrmServiceClient, puede usar un código similar al que se muestra aquí:

string SecretID = "00000000-0000-0000-0000-000000000000";
string AppID = "00001111-aaaa-2222-bbbb-3333cccc4444";
string InstanceUri = "https://yourorg.crm.dynamics.com";

string ConnectionStr = $@"AuthType=ClientSecret;
                        SkipDiscovery=true;url={InstanceUri};
                        Secret={SecretID};
                        ClientId={AppID};
                        RequireNewInstance=true";
using (ServiceClient svc = new ServiceClient(ConnectionStr))
{
    if (svc.IsReady)
    {
    //your code goes here
    }

}

Conexión mediante una huella digital de certificado

Si se conecta mediante un certificado y usa el Microsoft.Xrm.Tooling.Connector.CrmServiceClient, puede usar un código similar al que se muestra aquí:

string CertThumbPrintId = "DC6C689022C905EA5F812B51F1574ED10F256FF6";
string AppID = "00001111-aaaa-2222-bbbb-3333cccc4444";
string InstanceUri = "https://yourorg.crm.dynamics.com";

string ConnectionStr = $@"AuthType=Certificate;
                        SkipDiscovery=true;url={InstanceUri};
                        thumbprint={CertThumbPrintId};
                        ClientId={AppID};
                        RequireNewInstance=true";
using (ServiceClient svc = new ServiceClient(ConnectionStr))
{
    if (svc.IsReady)
    {
    //your code goes here
    }

}

Consulte también

Authentication con servicios web de Microsoft Dataverse
Autenticación de aplicaciones de .NET Framework
Información general del Biblioteca de autenticación de Microsoft

  • Last updated on