Connettersi ai servizi Web Microsoft Dynamics 365 tramite OAuth

Articolo
03/03/2017

Data di pubblicazione: gennaio 2017

Si applica a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

OAuth è il metodo di autenticazione supportato dall'API Web Microsoft Dynamics 365 ed è uno dei due metodi di autenticazione per il servizio dell'organizzazione - l'altro è l'autenticazione Active Directory. Il vantaggio dell'uso di OAuth consiste nel fatto che l'applicazione può supportare l'autenticazione a più fattori. Puoi utilizzare l'autenticazione OAuth quando la tua applicazione si connette al servizio dell'organizzazione o al servizio di individuazione.

Le chiamate dei metodi ai servizi Web devono essere autorizzate con il provider di identità per l'endpoint del servizio. L'autorizzazione viene approvata quando un valido token di accesso (utente) OAuth 2.0, emesso da Microsoft Azure Active Directory, viene fornito nelle intestazioni delle richieste dei messaggi.

L'API di autenticazione consigliata da utilizzare con l'API Web Dynamics 365, è la Libreria di autenticazione di Microsoft Azure Active Directory (ADAL) disponibile per una vasta gamma di piattaforme di linguaggi di programmazione. L'API ADAL gestisce l'autenticazione OAuth 2.0 con il provider di identità dei servizi Web Dynamics 365. Per ulteriori informazioni sull'effettivo protocollo OAuth utilizzato, vedi Utilizzare OAuth per eseguire l'autenticazione al servizio CRM.

Prima di poter utilizzare l'autenticazione OAuth per connetterti ai servizi Web Dynamics 365, la tua applicazione deve prima essere registrata in Microsoft Azure Active Directory.Azure Active Directory viene utilizzato per verificare che la tua applicazione sia abilitata per l'accesso ai dati aziendali archiviati in un tenant Dynamics 365.

Autenticazione tramite ADAL

L'autenticazione di base del servizio Web OAuth tramite ADAL viene eseguita con poche righe di codice.

// 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 = "https://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));

Il contesto di autenticazione viene restituito utilizzando un provider di autorità già noto. Se non conosci il tenant Azure Active Directory associato all'istanza di Dynamics 365 che stai chiamando, puoi utilizzare la stringa costante "https://login.windows.net/common", ovvero l'URL dell'autorità per uno scenario a più tenant. Un altro metodo per scoprire dinamicamente l'autorità in fase di esecuzione viene descritto più avanti in questo argomento.

La successiva riga di codice recupera il risultato di autenticazione che contiene il token di accesso che stai cercando. Puoi inviare richieste di messaggio ai servizi Web con questo token.

Altri elementi del codice interessanti sono i valori di stringa utilizzati. La variabile di risorsa contiene l'indirizzo radice Transport Layer Security (TLS) o Secure Sockets Layer (SSL), inclusi il dominio (organizzazione), del server Dynamics 365. Le variabili clientId e redirectUrl contengono le informazioni di registrazione dell'app che costituiscono il risultato della registrazione dell'app in Active Directory. Per ulteriori informazioni sulla registrazione dell'app, vedi Procedura dettagliata: registrare un'app Dynamics 365 con Azure Active Directory.

Usare il token di accesso nelle richieste di messaggio

A seconda dell'API Dynamics 365 che utilizzi sono disponibili due metodi diversi per inviare una richiesta di messaggio ai servizi Web. Per l'API Web, di norma invii una richiesta di messaggio HTTP. Per il servizio dell'organizzazione, invii una richiesta di messaggio utilizzando il proxy del client Web.

Richiesta messaggio HTTP

Una volta che il token di accesso è disponibile, devi impostare l'intestazione dell'autorizzazione per la richiesta di messaggio che stai inviando al servizio Web sul valore del token di accesso e specificare il tipo di token "Bearer". Per ulteriori informazioni sull'intestazione di autorizzazione, vedi la sezione 14.8 del Protocollo HTTP/1.1. Il codice seguente illustra come l'operazione viene eseguita utilizzando la classe 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);

Richieste client Web

Imposta semplicemente il valore della proprietà HeaderToken sul token di accesso quando si utilizza OrganizationWebProxyClient o DiscoveryWebProxyClient del servizio dell'organizzazione.

Aggiornare il token di accesso

È consigliabile aggiornare il token di accesso prima di ogni chiamata a un metodo di servizi Web Dynamics 365. È una soluzione alternativa alla scrittura del codice che controlla la data e l'ora di scadenza e del token di accesso e aggiorna il token quando è in scadenza.

Per aggiornare il token di accesso, che viene memorizzato nella cache da ADAL, puoi semplicemente chiamare il metodo AcquireToken utilizzando lo stesso contesto.

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

In seguito, imposta di nuovo l'intestazione di autorizzazione con result.AccessToken quando si utilizza l'API Web o HeaderToken quando si utilizza un servizio dell'organizzazione.

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

Rilevare l'autorità in fase di esecuzione

L'URL dell'autorità di autenticazione e l'URL della risorsa possono essere determinati dinamicamente in fase di esecuzione utilizzando il codice ADAL seguente. Si tratta del metodo consigliato rispetto all'URL dell'autorità mostrato in precedenza in un frammento di codice.

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

String authorityUrl = ap.Authority;
String resourceUrl  = ap.Resource;

Per l'API Web, un altro modo per ottenere l'URL dell'autorità consiste nell'inviare una richiesta di messaggio al servizio Web senza il token di accesso. Questo metodo è conosciuto come richiesta di connessione. La risposta può essere analizzata per ottenere l'URL dell'autorità.

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

Vedere anche

Procedura dettagliata: registrare un'app Dynamics 365 con Azure Active Directory
Documentazione dell'autenticazione a più fattori
OAuth 2.0

Microsoft Dynamics 365

Condividi tramite