Verwenden der OAuth-Authentifizierung mit Microsoft Dataverse

OAuth 2.0 ist das branchenübliche Protokoll für die Autorisierung. Nachdem Anwendungsbenutzende Anmeldeinformationen zur Authentifizierung angegeben haben, bestimmt OAuth, ob sie zum Zugriff auf die Ressourcen berechtigt sind.

Clientanwendungen müssen die Verwendung von OAuth für den Zugriff auf Daten mithilfe der Web-API unterstützen. OAuth ermöglicht eine Zwei-Faktor-Authentifizierung (2FA) oder eine zertifikatsbasierte Authentifizierung für Server-zu-Server-Anwendungsszenarien.

OAuth benötigt für die Authentifizierung einen Identitätsanbieter. Für Dataverse ist der Identitätsanbieter Microsoft Entra ID. Um sich mit einem Microsoft Geschäfts-, Schul- oder Unikonto zu authentifizieren, verwenden Sie die Microsoft Authentication Library (MSAL) (MSAL).

Hinweis

In diesem Artikel werden allgemeine Konzepte für die Verbindung mit Dataverse mithilfe von OAuth mit Authentifizierungsbibliotheken vorgestellt. Dieser Inhalt konzentriert sich darauf, wie ein Entwickler eine Verbindung mit Dataverse herstellen kann, aber nicht die inneren Arbeiten von OAuth oder den Bibliotheken abdeckt. Vollständige Informationen zur Authentifizierung finden Sie in der Microsoft Entra ID Dokumentation. Der Artikel Was ist die Authentifizierung? ist ein guter Ausgangspunkt.

Die von uns bereitgestellten Beispiele sind mit geeigneten Registrierungswerten vorkonfiguriert, sodass Sie sie ausführen können, ohne ihre eigene App-Registrierung zu generieren. Wenn Sie eigene Apps veröffentlichen, müssen Sie eigene Registrierungswerte verwenden.

App-Registrierung

Wenn Sie eine Verbindung mit OAuth herstellen, müssen Sie zuerst eine Anwendung in Ihrem Microsoft Entra ID Mandanten registrieren. Wie Sie Ihre App registrieren, hängt vom Typ der App ab, die Sie erstellen möchten.

Beginnen Sie in allen Fällen mit den grundlegenden Schritten zum Registrieren einer im Artikel beschriebenen App: Schnellstart: Registrieren einer Anwendung mit dem Microsoft Identity Platform. Spezifische Anweisungen zu Dataverse finden Sie unter Walkthrough: Registrieren einer App mit Microsoft Entra ID.

Die Entscheidungen, die Sie in diesem Schritt treffen müssen, hängen hauptsächlich von der Auswahl des Anwendungstyps ab (siehe nächster Abschnitt).

Arten der App-Registrierung

Wenn Sie eine App bei Microsoft Entra ID registrieren, wählen Sie den Anwendungstyp aus. Sie können zwei Arten von Anwendungen registrieren:

Anwendungstyp Beschreibung
Web-App / API Webclient
Eine Art von Client-Anwendung, die den gesamten Code auf einem Webserver ausführt.

Benutzer-Agent-basierter Client
Ein Typ von Client-Anwendung, der Code von einem Webserver herunterlädt und innerhalb eines Benutzeragenten (z.B. eines Webbrowsers) ausgeführt wird, wie beispielsweise eine Single Page Application (SPA).
Native EinTyp von Client-Anwendung, der nativ auf einem Gerät installiert wird.

Wenn Sie Web App /API auswählen, geben Sie eine Sign-On URL ein. Microsoft Entra ID sendet die Authentifizierungsantwort an diese URL, einschließlich eines Tokens, wenn die Authentifizierung erfolgreich ist. Legen Sie beim Entwickeln einer App diese URL so https://localhost/appname:[port] fest, dass Sie Ihre App lokal entwickeln und debuggen können. Wenn Sie Ihre App veröffentlichen, ändern Sie diesen Wert in die veröffentlichte URL der App.

Wenn Sie "Native" auswählen, geben Sie einen Umleitungs-URI ein. Diese URL ist ein eindeutiger Bezeichner, an den Microsoft Entra ID den Benutzer-Agent in einer OAuth 2.0-Anforderung umleitet. Diese URL ist normalerweise ein Wert, der so formatiert ist: app://<guid>.

Zugriff auf Dataverse geben

Wenn es sich bei Ihrer App um einen Client handelt, der es dem authentifizierten Benutzer ermöglicht, Vorgänge auszuführen, konfigurieren Sie die Anwendung so, dass sie über die delegierte Berechtigung Auf Dynamics 365 als Organisationsbenutzer zugreifen verfügt.

Spezifische Schritte zum Festlegen von Berechtigungen finden Sie unter Registern einer App mit Microsoft Entra ID.

Wenn Ihre App die Server-zu-Server-Authentifizierung (S2S) verwendet, müssen Sie diesen Schritt nicht ausführen. Für diese Konfiguration ist ein bestimmter Systembenutzer und die Vorgänge erforderlich, die von diesem Benutzerkonto ausgeführt werden, und nicht für jeden Benutzer, der authentifiziert werden muss.

Verwenden von geheimen Clientschlüsseln und Zertifikaten

Für Server-zu-Server-Szenarien gibt es kein interaktives Benutzerkonto, das authentifiziert werden soll. In diesen Fällen müssen Sie einige Mittel bereitstellen, um zu bestätigen, dass die Anwendung vertrauenswürdig ist. Bestätigen Sie die Vertrauensstellung mithilfe von geheimen Clientschlüsseln oder Zertifikaten.

Für Apps, die Sie mithilfe des Anwendungstyps "Web App /API " registrieren, können Sie geheime Schlüssel konfigurieren. Legen Sie diese geheimen Schlüssel im Schlüsselbereich unter API Access in den Einstellungen für die App-Registrierung fest.

Für beide Anwendungsarten können Sie ein Zertifikat hochladen.

Weitere Informationen: Als App verbinden

Authentifizierungsbibliotheken verwenden, um eine Verbindung herzustellen

Verwenden Sie eine der Microsoft unterstützten Microsoft Entra ID-Authentifizierungsclientbibliotheken, um eine Verbindung mit Dataverse herzustellen, z. B. die Microsoft Authentication Library (MSAL) (MSAL). Diese Bibliothek ist für verschiedene Plattformen verfügbar, wie in den bereitgestellten Links beschrieben.

Hinweis

Microsoft Authentication Library (MSAL) (ADAL) empfängt keine Updates aktiv und wird nur bis Juni 2022 unterstützt. Verwenden Sie MSAL als Authentifizierungsbibliothek für Projekte.

Ein Codebeispiel, das die Verwendung von MSAL-Bibliotheken für die Authentifizierung mit Dataverse veranschaulicht, finden Sie unter Schnellstart: Web-API-Beispiel (C#).

.NET-Clientbibliotheken

Dataverse unterstützt die Anwendungsauthentifizierung mit dem Web-API-Endpunkt mithilfe des OAuth 2.0-Protokolls. Verwenden Sie für Ihre benutzerdefinierten .NET-Anwendungen MSAL für die Anwendungsauthentifizierung mithilfe des Web-API-Endpunkts.

Dataverse SDK für .NET umfasst Clientklassen CrmServiceClient und ServiceClient zur Verarbeitung der Authentifizierung. Die CrmServiceClient-Klasse verwendet derzeit ADAL für die Authentifizierung während ServiceClient MSAL verwendet. Durch das Schreiben Ihres Anwendungscodes zur Verwendung dieser Clients entfällt die Notwendigkeit, die Authentifizierung direkt zu verwalten. Beide Clients arbeiten mit den SDK- und Web-API-Endpunkten.

Verwenden Sie den AccessToken für Ihre Anfragen.

Der Sinn der Verwendung der Authentifizierungsbibliotheken besteht darin, ein Zugriffstoken zu erhalten, das Sie in Ihre Anfragen aufnehmen können. Das Abrufen des Tokens erfordert nur ein paar Zeilen Code und nur ein paar weitere Zeilen, um einen HttpClient zur Ausführung einer Anfrage zu konfigurieren.

Wichtig

Wie im Beispielcode dieses Artikels gezeigt, verwenden Sie den Bereich „<environment-url>/user_impersonation“ für einen öffentlichen Client. Verwenden Sie für einen vertraulichen Client den Bereich „<environment-url>/.default“.

Einfaches Beispiel

Das folgende Beispiel ist die Mindestmenge an Code, der zum Ausführen einer einzelnen Web-API-Anforderung erforderlich ist, aber nicht der empfohlene Ansatz. Der Beispielcode verwendet die MSAL-Bibliothek und stammt aus dem Schnellstartbeispiel Web-API (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;

Dieser einfache Ansatz stellt kein gutes Muster dar, da der token in etwa einer Stunde abläuft. MSAL-Bibliotheken zwischenspeichern das Token für Sie und aktualisieren es jedes Mal, wenn die AcquireTokenInteractive Methode aufgerufen wird. In diesem einfachen Beispiel wird der Token jedoch nur einmal erworben.

Beispiel zur Demonstration eines delegierten Meldungshandlers

Implementieren Sie eine von DelegatingHandler abgeleitete Klasse und übergeben Sie sie an den Konstruktor von HttpClient. Mithilfe dieses Handlers können Sie die HttpClient.SendAsync -Methode überschreiben, sodass das Zugriffstoken von den AcquireToken* Methodenaufrufen mit jeder anforderung aktualisiert wird, die vom Http-Client gesendet wird.

Der folgende Code ist ein Beispiel für eine kundenspezifische Klasse, die von DelegatingHandler abgeleitet ist. Dieser Code stammt aus dem Erweiterten Schnellstartbeispiel , das die MSAL-Authentifizierungsbibliothek verwendet.

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

Wenn Sie diese OAuthMessageHandler Klasse verwenden, sieht die einfache Main Methode wie folgt aus.

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

Lesen Sie die folgenden wichtigen Informationen zur Verwendung einer Verbindungszeichenfolge- oder Benutzernamen-/Kennwortauthentifizierung im Anwendungscode.

Wichtig

Microsoft empfiehlt, den sichersten verfügbaren Authentifizierungsflow zu verwenden. Der in diesem Artikel beschriebene Authentifizierungsablauf erfordert ein sehr hohes Maß an Vertrauen in die Anwendung und birgt Risiken, die in anderen Flows nicht vorhanden sind. Sie sollten diesen Flow nur verwenden, wenn andere sicherere Flows, z. B. verwaltete Identitäten, nicht praktikabel sind.

Verschieben Sie die Werte der Konfigurationszeichenfolge in eine Verbindungszeichenfolge in der App.config-Datei, und konfigurieren Sie den HTTP-Client in der Methode 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;
    }
}

Weitere Informationen zum vollständigen Coden finden Sie im Beispiel für den verbesserten Schnellstart.

Obwohl in diesem Beispiel HttpClient anstelle der überschriebenen GetAsync verwendet wird, gilt der gleiche Codefluss für jede der SendAsync Methoden, die eine Anforderung senden.

Als App verbinden

Einige apps, die Sie erstellen, sind nicht für die interaktive Ausführung durch einen Benutzer vorgesehen. Sie können z. B. eine Webanwendung erstellen, die Vorgänge für Dataverse-Daten ausführen kann, oder eine Konsolenanwendung, die eine geplante Aufgabe irgendeiner Art ausführt.

Obwohl Sie diese Szenarien mithilfe von Anmeldeinformationen für einen normalen Benutzer erreichen können, benötigt dieses Benutzerkonto eine kostenpflichtige Lizenz. Verwenden Sie diesen Ansatz nicht.

Erstellen Sie in diesen Fällen einen speziellen Anwendungsbenutzer, der an eine Microsoft Entra ID registrierte Anwendung gebunden ist. Verwenden Sie als Nächstes entweder einen schlüsselschlüssel, der für die App konfiguriert ist, oder laden Sie ein X.509-Zertifikat hoch. Ein weiterer Vorteil dieses Ansatzes ist, dass er keine kostenpflichtige Lizenz verbraucht.

Anforderungen für die Verbindung als App

Um eine Verbindung als App herzustellen, benötigen Sie Folgendes:

  • Eine registrierte App
  • Einen Dataverse-Benutzer, der an die registrierte App gebunden ist
  • Herstellen einer Verbindung mithilfe des Anwendungsgeheimnisses oder eines Zertifikatfingerabdrucks

Registrieren der App

Führen Sie bei der Registrierung einer App viele der gleichen Schritte aus, die in exemplarischer Vorgehensweise beschrieben werden: Registrieren einer App mit Microsoft Entra ID mit den folgenden Ausnahmen:

  • Sie müssen die Berechtigung für den Zugriff auf Dynamics 365 als Organisationsbenutzer nicht erteilen.

    Diese Anwendung ist an ein bestimmtes Benutzerkonto gebunden.

  • Sie müssen einen geheimen Schlüssel für die App-Registrierung konfigurieren oder ein Zertifikat mit öffentlichem Schlüssel hochladen.

Sie können Anmeldeinformationen in Ihrer App-Registrierung unter Verwalten>Zertifikate & Geheimnisse erstellen oder anzeigen.

So fügen Sie ein Zertifikat (öffentlicher Schlüssel) hinzu:

  1. Wählen Sie auf der Registerkarte Zertifikate die Option Zertifikat hochladen aus.
  2. Wählen Sie die Datei aus, die Sie hochladen möchten. Es muss einer der folgenden Dateitypen sein: .cer,.pem,.crt.
  3. Geben Sie eine Beschreibung an.
  4. Klicken Sie auf Hinzufügen.

So fügen Sie einen geheimen Clientschlüssel (Anwendungskennwort) hinzu:

  1. Fügen Sie auf der Registerkarte Geheime Clientschlüssel eine Beschreibung für Ihren geheimen Clientschlüssel hinzu.
  2. Wählen Sie einen Ablaufzeitraum aus.
  3. Klicken Sie auf Hinzufügen.

Wichtig

Nachdem Sie die Konfigurationsänderungen gespeichert haben, wird ein geheimer Wert angezeigt. Kopieren Sie unbedingt den geheimen Wert für die Verwendung in Ihrem Clientanwendungscode, da Sie nicht auf diesen Wert zugreifen können, sobald Sie die Seite verlassen.

Weitere Informationen: Anmeldeinformationen hinzufügen

Dataverse-Benutzerkonto, das an die registrierte App gebunden ist

Erstellen Sie zunächst eine benutzerdefinierte Sicherheitsrolle, die definiert, über welche Zugriffsrechte und Berechtigungen dieses Kontos innerhalb der Dataverse-Organisation verfügt. Weitere Informationen finden Sie unter Erstellen oder Konfigurieren einer benutzerdefinierten Sicherheitsrolle.

Nachdem Sie die benutzerdefinierte Sicherheitsrolle erstellt haben, erstellen Sie das Benutzerkonto, das sie verwendet.

Manuelles Erstellen eines Dataverse-Anwendungsbenutzers

Die Vorgehensweise zum Erstellen eines Anwendungsbenutzers finden Sie im Artikel zur Power Platform-Administration: Anwendungsbenutzer erstellen.

Nach der Erstellung eines Anwendungsbenutzers ordnen Sie den Anwendungsbenutzer der angepassten Sicherheitsrolle zu, die Sie erstellt haben.

Herstellen einer Verbindung mithilfe des geheimen Anwendungsschlüssels

Wenn Sie eine Verbindung mit einem Clientgeheimnis herstellen und Microsoft.Xrm.Tooling.Connector.CrmServiceClient verwenden, können Sie ähnlichen Code wie hier gezeigt nutzen:

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
    }

}

Herstellen einer Verbindung mithilfe eines Zertifikatfingerabdrucks

Wenn Sie eine Verbindung über ein Zertifikat und die Microsoft.Xrm.Tooling.Connector.CrmServiceClient-Datei herstellen, können Sie ähnlichen Code wie hier gezeigt verwenden:

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
    }

}

Siehe auch

Authentication mit Microsoft Dataverse Webdiensten
Authentifizierung von .NET Framework-Anwendungen
Übersicht der Microsoft Authentication Library (MSAL)

  • Last updated on