Conectar con los servicios web de Dynamics 365 Customer Engagement mediante OAuth

Se aplica a Dynamics 365 (en línea), versión 9.x

OAuth es el método de autenticación admitido por la API web de Dynamics 365 Customer Engagement, y es uno de dos métodos de autenticación para el servicio de la organización; el otro es la autenticación de Active Directory. Un beneficio de usar OAuth es que la aplicación puede admitir autenticación de varios factores. Puede usar autenticación OAuth cuando la aplicación se conecte con el servicio de la organización o el servicio de detección.

Las llamadas de métodos a los servicios web deben autorizarse con el proveedor de identidad de ese extremo de servicio. La autorización es aprobada cuando un símbolo de acceso válido de OAuth 2.0 (usuario), emitido por Azure Active Directory, se proporciona en los encabezados de las solicitudes del mensaje.

La API de autenticación recomendada para uso con la API web de Dynamics 365 es Azure Active Directory Authentication Library (ADAL), que está disponible para una gran variedad de plataformas y de lenguajes de programación. La API ADAL administra la autenticación OAuth 2.0 con el proveedor de identidad de servicio web Dynamics 365. Para obtener más detalles del protocolo OAuth real usado, consulte Uso de OAuth para autenticarse con el servicio de CRM.

Nota

Debe usar las bibliotecas ADAL 2.0. Todas las herramientas, conjuntos y herramientas de Dynamics 365 Customer Engagement requieren los modelos admitidos por ADAL 2.0. Las bibliotecas ADAL 3.0 requieren una pantalla de inicio de sesión para capturar la información de la cuenta de usuario y no permiten pasar esta información de la cuenta de manera automatizada como requiere Dynamics 365 Customer Engagement.

Para poder usar la autenticación OAuth para conectarse con los servicios web de Dynamics 365, la aplicación primero se debe registrar con Azure Active Directory. Azure Active Directory se usa para comprobar que la aplicación está autorizada a acceder a los datos profesionales almacenados en un inquilino de Dynamics 365.

Autenticar usando ADAL

La autenticación del servicio web OAuth básica mediante ADAL se realiza con sólo unas líneas de código.

// TODO Substitute your correct CRM root service address,   
string resource = "https://mydomain.crm.dynamics.com";  
  
// TODO Substitute your app registration values that can be obtained after you  
// register the app in Active Directory on the Microsoft Azure portal.  
string clientId = "e5cf0024-a66a-4f16-85ce-99ba97a24bb2";  
string redirectUrl = "http://localhost/SdkSample";  
  
// Authenticate the registered application with Azure Active Directory.  
AuthenticationContext authContext =   
    new AuthenticationContext("https://login.windows.net/common", false);  
AuthenticationResult result = authContext.AcquireToken(resource, clientId, new Uri(redirectUrl));  

El contexto de autenticación se devuelve mediante un proveedor de autoridad conocido. Cuando no se conoce el inquilino de Azure Active Directory asociado con la instancia de Dynamics 365 a la que está llamando, puede usar una cadena constante de https://login.windows.net/common, que es la dirección URL de la autoridad para un escenario de inquilino múltiple. Un método alternativo para detectar dinámicamente la autoridad en tiempo de ejecución se describe más adelante en este tema.

La línea de código siguiente obtiene el resultado de autenticación que contiene el símbolo de acceso que busca. Puede enviar solicitudes de mensaje al servicio web con este símbolo.

Algunos elementos de interés más en este código son los valores de cadena usados. La variable de recursos contiene la dirección de raíz de seguridad de la capa de transporte (TLS) o capa de sockets seguros (SSL), incluido el dominio (organización), de su servidor de Dynamics 365. Las variables clientId y redirectUrl contienen información de registro de la aplicación que es el resultado de registrar la aplicación con Active Directory. Para obtener más información sobre el registro de aplicaciones, consulte Tutorial: Registrar una aplicación de Dynamics 365 con Azure Active Directory.

Use el símbolo de acceso en solicitudes de mensajes

Según la API Dynamics 365 que use, hay dos métodos diferentes para enviar una solicitud de mensaje a los servicios web. Para la API web, normalmente enviaría una solicitud de mensaje HTTP. Para el servicio de la organización, enviaría una solicitud de mensaje con el proxy del cliente web.

Solicitud de mensaje HTTP

Una vez que tenga el token de acceso, debe establecer el encabezado de autorización de la solicitud del mensaje que está enviando al servicio web al valor del token de acceso y especificar el tipo de token de Bearer. Para obtener más información sobre el encabezado de autorización, vea la sección 14.8 del Protocolo HTTP/1.1. El siguiente código demuestra cómo se hace esto utilizando la clase System.Net.Http.HttpClient.

using (HttpClient httpClient = new HttpClient())  
{  
    httpClient.Timeout = new TimeSpan(0, 2, 0);  // 2 minutes  
    httpClient.DefaultRequestHeaders.Authorization =   
        new AuthenticationHeaderValue("Bearer", result.AccessToken);  

Solicitudes del cliente web

Establezca simplemente el valor de propiedad HeaderToken con el símbolo de acceso al usar OrganizationWebProxyClient o DiscoveryWebProxyClient del servicio de organización.

Actualizar el símbolo de acceso

Se recomienda actualizar el símbolo de acceso antes de cada llamada a un método del servicio web de Dynamics 365. Para actualizar el símbolo de acceso, que ADAL almacena en la memoria caché, llame simplemente al método AcquireToken de nuevo utilizando el mismo contexto.

AuthenticationResult result = authContext.AcquireToken(resource, clientId, new Uri(redirectUrl));  

Luego, de nuevo establezca el encabezado de autorización con result.AccessToken al usar la API web, o HeaderToken al usar el servicio de organización.

httpClient.DefaultRequestHeaders.Authorization =   
    new AuthenticationHeaderValue("Bearer", result.AccessToken);  

Detectar la autoridad en tiempo de ejecución

La URL de la autoridad de autenticación y la URL del recurso pueden determinarse de forma dinámica en tiempo de ejecución mediante el siguiente código de ADAL. Este es el método recomendado para usar en comparación con la URL de autoridad conocida que se mostraba anteriormente en un fragmento de código.

AuthenticationParameters ap = AuthenticationParameters.CreateFromResourceUrlAsync(  
                        new Uri("https://mydomain.crm.dynamics.com/api/data/")).Result;  
  
String authorityUrl = ap.Authority;  
String resourceUrl  = ap.Resource;  

Para la API web, otra forma de obtener la URL de autoridad es enviar cualquier solicitud de mensaje al servicio web sin especifiar ningún token de acceso. Esto se conoce como desafío del portador. La respuesta se puede analizar para obtener la URL de autoridad.

httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "");  

Vea también

Tutorial: Registrar una aplicación de Dynamics 365 con Azure Active Directory
Documentación de autenticación multifactor
OAuth 2.0