Compartir vía

Utilice la autenticación con OAuth Microsoft Dataverse

  • Artículo

OAuth 2.0 es el protocolo estándar de la industria para la autorización. Después de que los usuarios de la aplicación proporcionan credenciales para autenticarse, OAuth determina si están autorizados para acceder a los recursos.

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

OAuth requiere un proveedor de identidad para la autenticación. Para Dataverse, el proveedor de identidades es Microsoft Entra ID. Para autenticarse usando una cuenta laboral o educativa de Microsoft, utilice la Biblioteca de autenticación de Microsoft (MSAL).

Nota

Este tema presentará conceptos comunes relacionados con la conexión al Dataverse usando OAuth con bibliotecas de autenticación. Este contenido se centrará en cómo un desarrollador puede Conectar, pero no en el funcionamiento interno ni en las bibliotecas. Dataverse OAuth Si desea obtener más información sobre autencación, consulte la documentación de Microsoft Entra ID. ¿Qué es la autenticación? es un buen lugar para comenzar.

Los ejemplos que proporcionamos se preconfiguran con los valores apropiados de registro para que pueda ejecutarlos sin generar su propio registro de la aplicación. Al publicar sus propias aplicaciones, debe usar sus propios valores de registro.

Registro de aplicaciones

Cuando usas Conectar OAuth, primero debes registrar una aplicación en tu inquilino de ID. Microsoft Entra Cómo debe registrar la aplicación depende del tipo de aplicación que desee crear.

En todos los casos, comience con los pasos básicos para registrar una aplicación que se describen en el artículo: Inicio rápido: Registrar una aplicación con la plataforma de identidad de Microsoft. Para obtener instrucciones específicas, consulte Tutorial: Registrar una aplicación con ID. Dataverse Microsoft Entra

Las opciones que deberá tomar en este paso dependen principalmente de la opción de tipo de aplicación (véase a continuación).

Tipos de registro de la aplicación

Cuando registra una aplicación con Microsoft Entra ID, una de las decisiones que debe tomar es el tipo de aplicación. Hay dos tipos de aplicación que puede registrar:

Tipo de aplicación Descripción
Aplicación web/API Cliente web
Un tipo de aplicación cliente que ejecuta todo el código en un servidor web.

Cliente basado en agente de usuario
Un tipo de aplicación cliente que descarga código de un servidor web y lo ejecuta dentro de un agente de usuario (por ejemplo, un navegador web), como una aplicación de página única (SPA).
Modo nativo de Un tipo de aplicación cliente que se instala de forma nativa en un dispositivo.

Cuando utiliza una aplicación web o API Seleccionar , debe proporcionar una URL de inicio de sesión , que es la URL donde ID envía la autenticación respuesta, incluido un token si la autenticación fue exitosa. Microsoft Entra Mientras desarrollas una aplicación, esta URL generalmente se establece en https://localhost/appname:[port] para que puedas desarrollar y depurar tu aplicación localmente. Al publicar la aplicación, necesita cambiar este valor en la dirección URL publicada de la aplicación.

Cuando usted es Seleccionar Nativo, debe proporcionar una URI de redireccionamiento. Esta URL es un identificador único al que Microsoft Entra ID redirigirá al agente de usuario en una OAuth solicitud 2.0. Esta URL normalmente es un valor con el siguiente formato: app://<guid>.

Dar acceso a Dataverse

Si su aplicación es un cliente que permite al usuario autenticado realizar operaciones, debe configurar la aplicación para que tenga Access Dynamics 365 como permiso delegado de los usuarios de la organización.

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

Si su aplicación va a usar la autenticación entre servidores (S2S), este paso no es obligatorio. Esa configuración requiere un usuario del sistema específico y las operaciones se realizarán por la cuenta de ese usuario en lugar de cualquier usuario que tenga que ser autenticado.

Uso de Secretos y certificados del cliente

En los escenarios entre servidores, no aparecerá una cuenta de usuario interactiva para la autenticación. En estos casos, debe proporcionar algunos medios de confirmar que la aplicación es de confianza. Esto se realiza con secretos o certificados del cliente.

Para las aplicaciones que están registradas con el tipo de aplicación Aplicación web/API , puedes configurar secretos. Estos se configuran utilizando el área Claves en Acceso API en la Configuración para el registro de la aplicación.

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

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

Uso de las bibliotecas de autenticación para conectar

Utilice una de las bibliotecas de cliente de autenticación de ID compatibles con Microsoft para Conectar, como la Microsoft Entra Biblioteca de autenticación de Microsoft (MSAL) Dataverse . ... Esta biblioteca está disponible para varias plataformas, como se muestra en los enlaces proporcionados.

Nota

La Biblioteca de autenticación de Azure Active Directory (ADAL) ya no recibe actualizaciones de forma activa y está programada para recibir soporte solo hasta junio de 2022. MSAL es la biblioteca de autenticación recomendada para usar en proyectos.

Para obtener un ejemplo de código que demuestra el uso de las bibliotecas MSAL para la autenticación, consulte Dataverse el ejemplo de inicio rápido .

Bibliotecas de cliente .NET

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

Dataverse El SDK para .NET incluye las clases de cliente CrmServiceClient y ServiceClient para manejar la autenticación. La clase CrmServiceClient actualmente utiliza 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 solo requiere unas pocas líneas de código y unas pocas líneas más para configurar un HttpClient para ejecutar una solicitud.

Importante

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

Ejemplo sencillo:

A continuación se presenta la cantidad mínima de código necesaria para ejecutar una sola solicitud de web API, pero no es el método recomendado. Tenga en cuenta que este código utiliza la biblioteca MSAL y está tomado del ejemplo de Inicio rápido .

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 simple no representa un buen patrón para seguir porque token caducará en aproximadamente una hora. Las bibliotecas MSAL almacenarán en caché el token por usted y lo actualizarán cada vez que se llame al método. AcquireTokenInteractive Sin embargo, en este ejemplo simple, el token solo se adquiere una vez.

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

El enfoque recomendado es implementar una clase derivada de DelegatingHandler que se pasará al constructor de HttpClient. Este controlador le permitirá anular el método HttpClient.SendAsync para que token de acceso se actualice mediante las llamadas al método AcquireToken* con cada solicitud enviada por el cliente Http.

El siguiente es un ejemplo de una clase personalizada derivada de DelegatingHandler. Este código se toma del ejemplo de Inicio rápido mejorado que utiliza la biblioteca de autenticación 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);
    }
}

Usando esta OAuthMessageHandler clase, el Main método simple se vería así.

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

Los valores de la cadena de configuración se han movido a una cadena de conexión del archivo App.config, y el cliente Http está configurado 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;
    }
}

Consulte el ejemplo de Inicio rápido mejorado para ver el código completo.

Aunque este ejemplo utiliza HttpClient.GetAsync en lugar del anulado SendAsync, se aplicará a cualquiera de los HttpClient métodos que envíen una solicitud.

Conectar como aplicación

Algunas aplicaciones que va a crear no están previstas para ser ejecutadas recíprocamente por un usuario. Por ejemplo, es posible 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 puede llegar a realizar estos escenarios usando las credenciales de un usuario normal, la cuenta de ese usuario necesitaría usar una licencia de pago. Este no es el enfoque recomendado.

En estos casos, puede crear un usuario de aplicación especial que esté vinculado a una ID de aplicación registrada y utilizar una clave secreta configurada para la aplicación o cargar un certificado X.509. Microsoft Entra 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 necesitará:

  • Una aplicación registrada
  • Un usuario de Dataverse vinculado a la aplicación registrada
  • Conectarse usando la clave secreta de la aplicación o una huella digital del certificado

Registrar su aplicación

Al registrar una aplicación, se deben seguir muchos de los mismos pasos que se describen en Tutorial: Registrar una aplicación con Microsoft Entra ID, con las siguientes excepciones:

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

    Esta aplicación estará 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 , Seleccionar Cargar certificado.
  2. Seleccione el archivo que le gustaría 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. Seleccionar un período de tiempo de expiración.
  3. Seleccione Agregar.

Importante

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

Más información: Agregar credenciales

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

Lo primero que debe hacer es crear un rol de seguridad personalizado que definirá qué acceso y privilegios esta cuenta tendrá dentro de la organización de Dataverse. Más información: Crear o configurar un rol de seguridad personalizado

Después de crear el rol de seguridad personalizado, debe crear la cuenta de usuario que lo usará.

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 la aplicación.

Después de crear un usuario de la aplicación, asocie el usuario de la aplicación con el rol de seguridad personalizado que creó.

Conectar con el secreto de la aplicación

Si se conecta utilizando un secreto de cliente y usa Microsoft.Xrm.Tooling.Connector.CrmServiceClient , puede usar un código como el siguiente:

string SecretID = "00000000-0000-0000-0000-000000000000";
string AppID = "545ce4df-95a6-4115-ac2f-e8e5546e79af";
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
    }

}

Conectar con una huella digital del certificado

Si se conecta usando un certificado y usa Microsoft.Xrm.Tooling.Connector.CrmServiceClient , puede usar un código como el siguiente:

string CertThumbPrintId = "DC6C689022C905EA5F812B51F1574ED10F256FF6";
string AppID = "545ce4df-95a6-4115-ac2f-e8e5546e79af";
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
    }

}

Consultar también

Autenticación con servicios web Microsoft Dataverse
Autenticación de aplicaciones seguir
Descripción general de la biblioteca de autenticación de Microsoft